Administrator guide

Administrators manage BucketDeck from Administration in the portal (PortalUrl). Everything is stored in the stack's DynamoDB table, and every change is written to the audit log.

#Roles

• Every signed-in user without a role entry is a User, and sees nothing until a grant applies to them.
• Roles and grants match the user's email or groups. The email must be trusted: asserted by your SAML IdP, verified by your OIDC IdP (email_verified), or marked verified in the Cognito user pool (Identity providers).
• BootstrapAdminEmail (a stack parameter) is the bootstrap admin. The first person who signs in with that email is bound to it by their immutable user ID (Cognito sub) and is always an Admin, which prevents lock-out. The binding is recorded in the audit log.
• Under Administration → Roles, grant Admin to a user (user:[email protected]) or a group (group:<name>). For group names, see Identity providers. Grant Admin to at least one more person or group.

#Recovering the bootstrap admin

Reset the binding when the bootstrap admin's user ID changes (the user was recreated, the IdP issues a new subject, or you switched IdentityProvider). Either:

• Use a different person: update the stack and change BootstrapAdminEmail. The first sign-in with the new email takes over the binding.
• Keep the same email: update the stack with BootstrapAdminEmail set to another address you can sign in with, and sign in with it once. Then set it back and sign in with the original email, which takes the binding over again.

The table can't be edited directly: its items are encrypted and integrity-protected, and its resource policy lets only BucketDeck's own roles change them (Security overview).

#Personal AWS access

Instead of (or as well as) connections and grants, users can browse with their own AWS permissions, exactly as in the AWS console or CLI. Turn it on with stack parameters:

• IdentityCenterStartUrl: users choose Connect with SSO, approve BucketDeck in the AWS access portal, and see every account and permission set IAM Identity Center assigns them. Nothing is needed in the member accounts: the permission sets decide.
• IamUserKeySignIn=Enabled: users sign in with their IAM user access key (and MFA code if their policies require it). BucketDeck exchanges it for temporary credentials and doesn't keep the key.

Personal connections are private to the user and are not governed by grants: AWS IAM alone decides what they can do, and CloudTrail records the user's own identity. Sessions end when they expire (Identity Center: the session duration of your instance; keys: up to 36 hours) or when the user disconnects. Every connect, refusal and disconnect is in the audit log (aws.*). Leave both parameters empty to allow only connections that admins define.

#Connections

A connection is one way into one AWS account (Administration → Connections).

For a role connection:

1. Choose Add connection → IAM role, enter a name, the account ID and the default Region.
2. Open Set up role. It shows the external ID, the trusted principals, the exact trust and permissions policies, and a quick-create link for the spoke template with the parameters filled in. Deploy it in the target account (or use your StackSet's shared external ID).
3. Paste the spoke stack's RoleArn output and choose Test. The test assumes the role, lists buckets and reports each step; a failure names the AWS error.

Buckets (optional) limits the buckets shown for a connection. Empty means every bucket the role can list (s3:ListAllMyBuckets). List them explicitly when the role can't list buckets.

Deleting a connection deletes its secret (for keys) and every grant on it.

#Grants

A grant gives a subject permissions on scopes of a connection (Administration → Grants):

• A user's effective permissions on a bucket and key are the union of all grants that match them. Admins have every permission everywhere.
• Folder-wide operations (transfer jobs, search, Lens) need the permission on the whole prefix: a bucket-wide scope, or a scope prefix that contains the folder.
• Grants never exceed the connection's IAM role: if the spoke role is ReadOnly, a write grant still fails with access_denied from AWS.

Examples:

#Share links

Team and above. Users with share can create links to single objects that work without signing in, until they expire. Shares → All lists every user's links with their expiry and use count; revoke any link there. A link also stops working as soon as its creator loses read on the object, so removing a grant or a group membership revokes that person's links too. Each use is audited as share.open. Grant share sparingly and keep Maximum share lifetime short.

#Settings

Administration → Settings:

#Jobs

Jobs → All shows every user's jobs. Admins can cancel, retry and delete any job. A job's page shows its progress, counters, failures (with a CSV report) and a link to the Step Functions execution. Failed keys can be retried as a new job.

#Audit

Administration → Audit lists events by day: sign-in of the bootstrap admin, role, connection, grant and settings changes, jobs, share links, uploads, deletes, renames and metadata changes, with the actor and source IP. Events expire after the stack's AuditRetentionDays, capped by the plan (30 days on Starter, 90 on Team, 365 on Business, 3,650 on Enterprise).

For a full trail, CloudTrail in each account shows every S3 call with sourceIdentity set to the user's email (S3 object-level calls need CloudTrail data events).

#Licence and version

• Administration → Licence shows the AWS Marketplace licence state (active, grace, unlicensed) as AWS License Manager reports it, and when it was checked. Choose Refresh after renewing a contract. Without a valid licence, every page except this one shows that a licence is required.
• Administration → About shows the installed version and links to the release notes. To upgrade, see upgrading guide.

#Plan

Administration → About → Plan shows your plan, the AWS accounts counted against it and what each plan includes:

• AWS accounts are counted from your connections (this account included) and from the accounts people reached with their own AWS sign-in in the last 30 days. When all are in use, new accounts can't be connected; accounts already in use keep working.
• Features your plan doesn't include show a plan badge (for example Business) and explain what to upgrade to; the API refuses them too.
• Upgrading from Starter: choose the plan under Upgrade to and follow the upgrading guide. Between Team, Business and Enterprise, choose the plan the same way: the upgrade page prepares an offer that credits what is left of your contract; approve the cancellation of your current agreement, then accept the offer (upgrading guide). No stack update is needed.
• If the subscription ends, BucketDeck locks within an hour (only the licence page works) and keeps all data. Subscribing again unlocks it.

#Listing cache

Listings of large prefixes are cached in DynamoDB and patched as users upload, rename, delete and run jobs. If objects change outside BucketDeck, users can refresh a folder; admins can purge a connection's or bucket's cache in Administration → Settings → Cache.