OIDC user pool IdP authentication flow - Amazon Cognito
How a user pool processes claims from an OIDC provider

OIDC user pool IdP authentication flow

With OpenID Connect (OIDC) sign-in, your user pool automates an authorization-code sign-in flow with your identity provider (IdP). After your user completes sign-in with their IdP, Amazon Cognito collects their code at the oauth2/idpresponse endpoint of the external provider. With the resulting access token, your user pool queries the IdP userInfo endpoint to retrieve user attributes. Your user pool then compares the received attributes to the attribute-mapping rules you've set up and populates the user's profile and ID token accordingly.

The OAuth 2.0 scopes that you request in your OIDC provider configuration define the user attributes that the IdP provides to Amazon Cognito. As a best security practice, only request the scopes that correspond to attributes that you want to map to your user pool. For example, if your user pool requests openid profile, you'll get all possible attributes, but if you request openid email phone_number you'll only get the user's email address and phone number. You can configure the scopes that you request from OIDC IdPs to differ from those you authorize and request in the app client and user pool authentication request.

When your user signs in to your application using an OIDC IdP, your user pool conducts 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, for example Salesforce.

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

  3. After your user authenticates, 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.

User pool OIDC IdP authentication flow
Note

Amazon Cognito cancels authentication requests that do not complete within 5 minutes, and redirects the user to managed login. 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, managed login 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.