OIDC user pool IdP authentication flow

When your user signs in to your application using an OIDC IdP, they pass through the following authentication flow.

1. Your user lands on the Amazon Cognito built-in sign-in page, and is offered the option to sign in through an OIDC IdP such as Salesforce.

2. Your user is redirected to the authorization endpoint of the OIDC IdP.

3. After your user is authenticated, the OIDC IdP redirects to Amazon Cognito with an authorization code.

4. Amazon Cognito exchanges the authorization code with the OIDC IdP for an access token.

5. Amazon Cognito creates or updates the user account in your user pool.

6. Amazon Cognito issues your application bearer tokens, which might include identity, access, and refresh tokens.

Note

Amazon Cognito cancels authentication requests that do not complete within 5 minutes, and redirects the user to the hosted UI. The page displays a Something went wrong error message.

OIDC is an identity layer on top of OAuth 2.0, which specifies JSON-formatted (JWT) identity tokens that are issued by IdPs to OIDC client apps (relying parties). See the documentation for your OIDC IdP for information about to add Amazon Cognito as an OIDC relying party.

When a user authenticates with an authorization code grant, the user pool returns ID, access, and refresh tokens. The ID token is a standard OIDC token for identity management, and the access token is a standard OAuth 2.0 token. For more information about grant types that your user pool app client can support, see Authorize endpoint.

How a user pool processes claims from an OIDC provider

When your user completes sign-in with a third-party OIDC provider, the Amazon Cognito hosted UI retrieves an authorization code from the IdP. Your user pool exchanges the authorization code for access and ID tokens with the token endpoint of your IdP. Your user pool doesn't pass these tokens on to your user or your app, but uses them to build a user profile with data that it presents in claims in its own tokens.

Amazon Cognito doesn't independently validate the access token. Instead, it requests user-attribute information from the provider userInfo endpoint and expects the request to be denied if the token isn't valid.

Amazon Cognito validates the provider ID token with the following checks:

1. Check that the provider signed the token with an algorithm from the following set: RSA, HMAC, Elliptic Curve.

2. If the provider signed the token with an asymmetric signing algorithm, check that the signing key ID in the token kid claim is listed at the provider jwks_uri endpoint.

3. Compare the ID token signature to the signature that it expects based on provider metadata.

4. Compare the iss claim to the OIDC issuer configured for the IdP.

5. Compare the aud claim matches the client ID configured on the IdP, or that it contains the configured client ID if there are multiple values in the aud claim.

6. Check that the timestamp in the exp claim is not before the current time.

Your user pool validates the ID token, then attempts a request to the provider userInfo endpoint with the provider access token. It retrieves any user profile information that the scopes in the access token authorize it to read. Your user pool then searches for the user attributes that you have set as required in your user pool. You must create attribute mappings in your provider configuration for required attributes. Your user pool checks the provider ID token and the userInfo response. Your user pool writes all claims that match mapping rules to user attributes on the user pool user profile. Your user pool ignores attributes that match a mapping rule but aren't required and aren't found in the provider's claims.