Amazon Cognito user pool OIDC

Audience: AWS administrators using a Cognito user pool as the OpenID Connect provider for TokenTimer Enterprise.

Multi-provider SSO: Configure Cognito under System Settings → Manage SSO providers (or bootstrap via sso-providers.json / Helm ssoProviders[]). Sign-in and callback URLs are slug-scoped. See the OIDC quickstart first.

TokenTimer is the OAuth/OIDC relying party; the user pool is the authorization server. (If you federate into Cognito from another SAML IdP, configure that federation on the user pool; TokenTimer still talks OIDC to Cognito.)

See the SSO identity provider guides for prerequisites and callback URLs.

URLs to register

Replace <slug> with your provider slug (e.g. cognito).

Purpose	Value
Allowed callback URL (app client)	https://tokentimer.example.com/auth/oidc/<slug>/callback

---

1. User pool and domain

1. Amazon Cognito console, User pools: create or select a pool.
2. Note User pool ID (e.g. us-east-1_AbCdEfGhI).
3. App integration, Domain:
   • Cognito domain: https://<prefix>.auth.<region>.amazoncognito.com, or
   • Custom domain (ACM certificate required).

A domain is required for the hosted UI and for OAuth2 authorize endpoints listed in discovery (user pool domain).

2. App client (confidential)

App integration, App clients, Create app client (app client settings):

Setting	Value
Application type	Traditional web application (or confidential client with secret)
Client secret	Generate and store as SSO_<SLUG>_OIDC_CLIENT_SECRET
Authentication flows	Authorization code grant
Allowed callback URLs	https://tokentimer.example.com/auth/oidc/<slug>/callback
Allowed sign-out URLs (optional)	https://tokentimer.example.com/login
OpenID Connect scopes	openid, email, profile
OAuth 2.0 grant types	Authorization code

Copy Client ID into SSO Providers (config.client_id).

3. Issuer and discovery

Cognito issuer format (OIDC IdP):

https://cognito-idp.<region>.amazonaws.com/<userPoolId>

Example discovery:

https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbCdEfGhI/.well-known/openid-configuration

Set Issuer in SSO Providers to the issuer value from that JSON. Authorization and token endpoints in the document use your Cognito domain host; discovery must succeed from the TokenTimer API unless you set explicit endpoint overrides on the provider.

4. Groups

Cognito user pool groups appear in tokens as cognito:groups (array).

1. Users, Groups: create groups matching your role mapping names.
2. Assign users to groups.

In SSO Providers under Claim mapping:

Field	Paths
Email	email
Display name	name
Groups	cognito:groups
Subject	sub

Do not strip the cognito: prefix (see Claim mapping).

Optional: map custom attributes via a Pre token generation Lambda trigger if you need extra claims.

5. TokenTimer configuration

In SSO Providers (slug e.g. cognito):

Field	Value
Issuer	https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbCdEfGhI
Client ID	<app-client-id>
Scopes	openid profile email

SSO_COGNITO_OIDC_CLIENT_SECRET=<app-client-secret>
API_URL=https://tokentimer.example.com
APP_URL=https://tokentimer.example.com

Ensure the API container can reach cognito-idp.<region>.amazonaws.com and your Cognito domain over HTTPS (VPC endpoints or egress as needed).

6. Verify

1. Hosted UI test: https://<domain>/login?client_id=...&response_type=code&scope=openid+email+profile&redirect_uri=... (optional sanity check).
2. TokenTimer login page: provider button (e.g. Sign in with Cognito).
3. Confirm cognito:groups in the resolved profile (audit idp_groups_seen).

Troubleshooting

Symptom	Likely cause	Fix
redirect_mismatch	Callback not in app client list	Add exact URL
Discovery OK but authorize fails	Missing Cognito domain	Assign domain under App integration
Invalid issuer	Wrong region or pool ID	Copy issuer from discovery
No cognito:groups	User not in groups	Assign pool groups
API cannot reach discovery	Network policy	Open egress or disable discovery and set manual endpoints on the provider

Official references

• User pool as OIDC IdP
• App client settings
• Assign a domain
• User pool groups