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.
-
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.
-
Your user is redirected to the
authorization
endpoint of the OIDC IdP. -
After your user authenticates, the OIDC IdP redirects to Amazon Cognito with an authorization code.
-
Amazon Cognito exchanges the authorization code with the OIDC IdP for an access token.
-
Amazon Cognito creates or updates the user account in your user pool.
-
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
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:
-
Check that the provider signed the token with an algorithm from the following set: RSA, HMAC, Elliptic Curve.
-
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 providerjwks_uri
endpoint. -
Compare the ID token signature to the signature that it expects based on provider metadata.
-
Compare the
iss
claim to the OIDC issuer configured for the IdP. -
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 theaud
claim. -
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.