Single sign-on

Everyone signs in to a self-hosted console through your identity provider (IdP). The stack's Cognito user pool is only a broker: it has no passwords and no self sign-up, and the console sends every sign-in straight to your IdP. Until single sign-on is configured, the only way in is emergency access.

Single sign-on is set through stack parameters, so CloudFormation reviews and records every change. You can set it at launch or later from the console.

Choose the provider name once. Changing IdpName after members exist, whether by switching between SAML and OpenID Connect, renaming the provider, or moving to another IdP, locks out every existing member, and there's no in-product way to restore their access today. See Changing the identity provider.

Set up the app in your IdPCopy Anchor Link

The values come from the stack's outputs.

SAML 2.0Copy Anchor Link

• Assertion Consumer Service (ACS) URL: CognitoSamlAcsUrl.
• Audience / SP entity id: CognitoSamlEntityId.
• Name ID: a value that never changes for a user, such as their email address. Cognito names each federated user after the provider name and this value.
• Attributes: release the user's email in the claim named by EmailAttribute (default http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). Optionally release http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname and http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname.
• Start URL: if your IdP shows an app tile, make it open the ConsoleUrl output. Sign-in must start at the console; IdP-initiated SAML isn't enabled.
• Copy the app's metadata URL; it becomes SamlMetadataUrl.

OpenID ConnectCopy Anchor Link

• Redirect URI: CognitoOidcRedirectUri.
• Scopes: openid email profile (or set OidcScopes).
• Claims: email is required; given_name and family_name are optional. Cognito identifies each user by the sub claim.
• Note the issuer URL, client id and client secret; they become OidcIssuer, OidcClientId and OidcClientSecret.

Apply it with a stack updateCopy Anchor Link

From the consoleCopy Anchor Link

1. Sign in to the console (through emergency access if single sign-on isn't set up yet) and open Settings → Single sign-on.
2. Choose the protocol and fill in the provider name, then the metadata URL (SAML) or the issuer and client id (OpenID Connect), and the email attribute.
3. Sign in to the AWS console in the stack's account first, then choose Open stack update in the AWS console.
   • If you're signed in to more than one AWS session, AWS first asks you to choose one.
   • In the wrong account the update fails closed: the wizard reports that the resource account doesn't match the account in the stack's ARN.
4. In the update wizard:
   • Use existing template is already selected. A single sign-on change never changes the release.
   • Parameters: the wizard doesn't take values from the link, so enter the ones the console page shows, and leave every other parameter unchanged. For OpenID Connect, also paste your client secret into OidcClientSecret; the link never carries it.
   • Stack options: leave Express mode unchecked, set Behavior on provisioning failure to Roll back all resources, and set Delete newly created resources during a rollback to Use deletion policy.
   • Acknowledge that the stack creates IAM resources, and submit.

The console page also shows the equivalent aws cloudformation update-stack command, with every other parameter kept at its previous value.

At launchCopy Anchor Link

Set SsoType, IdpName, EmailAttribute and either SamlMetadataUrl or OidcIssuer, OidcClientId and OidcClientSecret. See Parameters.

What the update doesCopy Anchor Link

A single sign-on update creates or replaces the Cognito identity provider, points the app client at it, and rolls the server onto new tasks. It runs no database transition and takes no snapshot; the old tasks keep serving until the new ones are healthy. In our tests it took three to four minutes.

If the attribute mapping turns out wrong (for example, users arrive without an email), fix the IdP or EmailAttribute and run another update.

First sign-in and membersCopy Anchor Link

Single sign-on lets people authenticate; it doesn't give them access. A person who signs in without a membership or an invitation sees No access yet. There's no automatic membership.

• With AdminEmail set, the first person to sign in through single sign-on with that address becomes the owner.
• Otherwise, invite the first members from an emergency session:
  1. Sign in through emergency access.
  2. Open Settings → Members and invite each person by the email address your IdP sends, with their role. Invite at least one owner.
  3. Tell them to sign in at the console URL. The console sends no email, so invitations reach people only through you. After signing in through your IdP they see the invitation and join.

How sign-in behavesCopy Anchor Link

• Signing in at the console goes straight to your IdP. No Cognito sign-in page or provider picker appears.
• Signing out ends the Tracemill and Cognito sessions, not your IdP session. The next sign-in may go through without a prompt.
• Right after you switch identity providers, the first sign-out can land on Cognito's generic error page. Reload the console; it doesn't recur.

Changing the identity providerCopy Anchor Link

Cognito names each federated user after the provider name and the user identifier your IdP sends (the SAML Name ID, or the OIDC sub). A member who signs in under a different provider name, or with a different identifier, is a new user to Tracemill, with no memberships. Their old user, and the memberships and history attached to it, stay behind. That happens when you:

• switch between SAML and OpenID Connect, which always requires a new IdpName;
• rename the provider (IdpName);
• move to another IdP, for example from Okta to Microsoft Entra ID.

After any of these, every existing member is locked out: they sign in and see No access yet, and there's no in-product way to restore their access today.

• Don't change the provider name, the protocol or the IdP once members exist.
• If a provider migration is unavoidable, contact Tracemill support before you make the change.

Changing the metadata URL, client id or secret, or the email attribute keeps every member, as long as the provider name, the protocol and the IdP's user identifiers stay the same.