Identity providers

BucketDeck signs users in through an Amazon Cognito user pool. The pool federates to your identity provider. This guide covers:

• IAM Identity Center, the primary option;
• Entra ID and Okta over SAML 2.0;
• OIDC;
• Cognito-only users, with no external identity provider.

IAM Identity Center and Cognito-only users work on every plan. Other SAML identity providers and OIDC are part of BucketDeck Team and above; the BucketDeck Starter template offers only IAMIdentityCenter and CognitoOnly.

In every case, the IdP must send:

• email. It is required, and it's the identity used for roles and grants.
• groups (optional). Used for group-based roles and grants.

Because roles and grants are keyed on email, the email must be one users can't set for themselves:

• SAML (IAM Identity Center, Entra ID, Okta): the asserted email is trusted as is. Map it from an attribute only administrators control (see the notes per IdP below).
• OIDC: the IdP must also say the email is verified (email_verified). Users whose email isn't verified are refused. See OIDC identity providers.
• Cognito-only: the user's email must be marked verified. See Cognito-only users.

A refused user gets 403 forbidden on every request, sees a message that their email address isn't trusted, and can't use the portal at all. See the Security overview.

#IAM Identity Center

IAM Identity Center (IDC) can't be configured by CloudFormation for a customer-managed SAML application. The setup therefore takes two steps.

#Step 1: Deploy the stack

Deploy with IdentityProvider = IAMIdentityCenter and leave SamlMetadataUrl empty. When the stack is complete, copy these outputs:

• SamlAcsUrl: https://<prefix>-<account>.auth.<region>.amazoncognito.com/saml2/idpresponse
• SamlAudienceUri: urn:amazon:cognito:sp:<user pool id>
• PortalUrl

#Step 2: Create the custom SAML 2.0 application

1. Open the IAM Identity Center console, in the Region where your IDC instance lives (this can differ from the stack's Region).
2. Go to Applications → Add application. Choose I have an application I want to set up → SAML 2.0 → Next.
3. Fill in the configuration:
   • Display name: BucketDeck (shown in the AWS access portal).
   • Application start URL: the PortalUrl output. With this set, the access portal tile starts an SP-initiated sign-in, which is what Cognito expects.
   • Relay state: leave it empty.
   • IAM Identity Center metadata: copy the IAM Identity Center SAML metadata file URL. You need it in step 4.
   • Application metadata: choose Manually type your metadata values:
     • Application ACS URL: the SamlAcsUrl output.
     • Application SAML audience: the SamlAudienceUri output.
4. Choose Submit.

#Step 3: Attribute mappings

Open the application and go to Actions → Edit attribute mappings:

Save the changes.

Groups and IAM Identity Center. IDC doesn't officially support sending group names in SAML assertions. ${user:groups} is available but undocumented as a supported attribute, and it emits group IDs (GUIDs such as 90677c4b-...), not display names. If you map it:

• Assign roles and grants to groups in the admin console using the group ID as the group name. Find it in IDC → Groups → group → Group ID.
• Cognito stores a user's groups in a 2,048-character attribute. Users in many groups (more than about 50 GUIDs) may have the list truncated, or the sign-in may fail. Keep group membership for this app focused.

If you don't map groups, assign roles and grants per user (by email) in the admin console. This is the simplest and fully supported approach.

#Step 4: Assign users and groups

In the application, open Assigned users and groups → Assign users and groups. Add the people or groups who may use BucketDeck. Only assigned users can sign in.

#Step 5: Update the stack

Update the stack (use the current template), keep every other parameter, and set SamlMetadataUrl to the metadata URL you copied in step 2. The update:

• creates the Cognito SAML provider IAMIdentityCenter;
• switches the portal's app client to that provider;
• redeploys the portal configuration, so users go straight to IDC.

#Step 6: Test

Open PortalUrl, or the tile in the AWS access portal. Sign in as BootstrapAdminEmail. You should land in the portal with Administration available.

If your IDC certificate is rotated, Cognito picks up the new certificate from the metadata URL. If you replace the application, update SamlMetadataUrl.

#Other SAML identity providers

Deploy with IdentityProvider = SAML, follow the two-step pattern above, and enter the values below in your IdP.

#Microsoft Entra ID

1. Go to Enterprise applications → New application → Create your own application. Choose Integrate any other application you don't find in the gallery.
2. Single sign-on → SAML. In Basic SAML Configuration:
   • Identifier (Entity ID): SamlAudienceUri
   • Reply URL (ACS): SamlAcsUrl
   • Sign on URL: PortalUrl
3. Attributes & Claims:
   • Unique User Identifier (Name ID): user.userprincipalname or user.mail. Use the Email address format.
   • Add a claim with name email (no namespace) and source attribute user.mail.
   • Add a group claim. Choose Groups assigned to the application. Set the source attribute to Cloud-only group display names for names, or Group ID otherwise. Under Advanced options, select Customize the name of the group claim and set the name to groups.
4. Copy the App Federation Metadata Url into SamlMetadataUrl.
5. Assign users and groups to the enterprise application.

Entra ID emits group display names only for cloud-only groups. For synced groups, use sAMAccountName or IDs.

The email claim is trusted. user.mail is set by administrators (or synced from Active Directory) for member users. If guests (B2B) are assigned to the application, or users can edit mail in your tenant, use user.userprincipalname instead, where the UPN is the user's email.

#Okta

1. Go to Applications → Create App Integration → SAML 2.0.
2. Fill in the SAML settings:
   • Single sign-on URL: SamlAcsUrl. Check Use this for Recipient URL and Destination URL.
   • Audience URI (SP Entity ID): SamlAudienceUri.
   • Name ID format: EmailAddress. Application username: Email.
   • Attribute statement: email → user.email.
   • Group attribute statement: groups, filter Matches regex .*. A narrower filter, such as ^bucketdeck-, is recommended.
3. On the Sign On tab, copy the Metadata URL into SamlMetadataUrl.
4. Assign people and groups.

The email attribute is trusted. In Okta, make sure end users can't change their own primary email without verification: in Directory → Profile Editor → User (default), set email to Read only for users, or keep Okta's default of verifying a changed email before it takes effect.

#OIDC identity providers

Store the client secret in AWS Secrets Manager (plain-text SecretString), then deploy with IdentityProvider = OIDC and set OidcIssuer, OidcClientId and OidcClientSecretArn. The identity deploying the stack needs secretsmanager:GetSecretValue on that secret. There is no second step.

In your IdP, create a confidential web client:

• Redirect URI: <CognitoDomain>/oauth2/idpresponse, for example https://bucketdeck-123456789012.auth.eu-west-2.amazoncognito.com/oauth2/idpresponse.
• Scopes: openid email profile.
• Claims: email, a claim saying the email is verified (see below), and optionally groups. Cognito reads claims from the userinfo endpoint (attributes_request_method = GET). Make sure your IdP includes groups there, or in the ID token if it does both. Okta needs a groups claim on the authorization server; Entra ID needs groups added under Token configuration.

The issuer must serve /.well-known/openid-configuration.

#Verified email (required)

Many OIDC IdPs let users, or guests from other organisations, set their own email address. Because roles and grants are keyed on email, the stack maps the IdP claim named by the OidcEmailVerifiedClaim parameter (default email_verified) to Cognito's email_verified, and the API refuses any OIDC user for whom it isn't true, including the BootstrapAdminEmail user.

Cognito updates mapped attributes only when a user signs in through the IdP, so after you deploy or change this, users who are refused must sign out of the portal and sign in again.

#How groups reach the application

The IdP's groups attribute is mapped to the Cognito attribute custom:groups. That attribute then appears in the ID token the API reads.

When the IdP sends several values, Cognito flattens them into one string of the form [groupA,groupB]. Values that contain characters other than letters, digits, ., -, * and _ are URL-encoded. The API decodes this format. When you assign roles or grants to a group in the admin console, type the group name exactly as the IdP sends it.

#Cognito-only users

With IdentityProvider = CognitoOnly, users exist only in the Cognito user pool:

• Self sign-up is disabled.
• Passwords need at least 14 characters with mixed classes.
• TOTP MFA is required.

Create users in the Cognito console (User pools → pool → Users → Create user), or from the CLI:

aws cognito-idp admin-create-user --user-pool-id <UserPoolId> \
  --username [email protected] \
  --user-attributes Name=email,[email protected] Name=email_verified,Value=true \
  --desired-delivery-mediums EMAIL

The email must be verified: in the console, tick Mark email address as verified when you create the user. Users whose email isn't verified are refused by the portal. To fix an existing user:

aws cognito-idp admin-update-user-attributes --user-pool-id <UserPoolId> \
  --username [email protected] --user-attributes Name=email_verified,Value=true

Users can't change their own email from the portal. If an administrator changes a user's email, Cognito keeps the old, verified address in effect until the new one is verified (or the administrator sets email_verified=true in the same call).

By default, Cognito sends a limited number of emails per day. For more than a handful of users, configure Amazon SES for the user pool.