Adding user pool sign-in through a third party

Your app users can either sign in directly through a user pool, or they can federate through a third-party identity provider (IdP). The user pool manages the overhead of handling the tokens that are returned from social sign-in through Facebook, Google, Amazon, and Apple, and from OpenID Connect (OIDC) and SAML IdPs. With the built-in hosted web UI, Amazon Cognito provides token handling and management for authenticated users from all IdPs. This way, your backend systems can standardize on one set of user pool tokens.

How federated sign-in works in Amazon Cognito user pools

Sign-in through a third party (federation) is available in Amazon Cognito user pools. This feature is independent of federation through Amazon Cognito identity pools (federated identities).

Amazon Cognito is a user directory and an OAuth 2.0 identity provider (IdP). When you sign in local users to the Amazon Cognito directory, your user pool is an IdP to your app. A local user exists exclusively in your user pool directory without federation through an external IdP.

When you connect Amazon Cognito to social, SAML, or OpenID Connect (OIDC) IdPs, your user pool acts as a bridge between multiple service providers and your app. To your IdP, Amazon Cognito is a service provider (SP). Your IdPs pass an OIDC ID token or a SAML assertion to Amazon Cognito. Amazon Cognito reads the claims about your user in the token or assertion and maps those claims to a new user profile in your user pool directory.

Amazon Cognito then creates a user profile for your federated user in its own directory. Amazon Cognito adds attributes to your user based on the claims from your IdP and, in the case of OIDC and social identity providers, an IdP-operated public userinfo endpoint. Your user's attributes change in your user pool when a mapped IdP attribute changes. You can also add more attributes independent of those from the IdP.

After Amazon Cognito creates a profile for your federated user, it changes its function and presents itself as the IdP to your app, which is now the SP. Amazon Cognito is a combination OIDC and OAuth 2.0 IdP. It generates access tokens, ID tokens, and refresh tokens. For more information about tokens, see Using tokens with user pools.

You must design an app that integrates with Amazon Cognito to authenticate and authorize your users, whether federated or local.

The responsibilities of an app as a service provider with Amazon Cognito

Verify and process the information in the tokens

In most scenarios, Amazon Cognito redirects your authenticated user to an app URL that it appends with an authorization code. Your app exchanges the code for access, ID, and refresh tokens. Then, it must check the validity of the tokens and serve information to your user based on the claims in the tokens.

Respond to authentication events with Amazon Cognito API requests

Your app must integrate with the Amazon Cognito user pools API and the authentication API endpoints. The authentication API signs your user in and out, and manages tokens. The user pools API has a variety of operations that manage your user pool, your users, and the security of your authentication environment. Your app must know what to do next when it receives a response from Amazon Cognito.

Things to know about Amazon Cognito user pools third-party sign-in

• If you want your users to sign in with federated providers, you must choose a domain. This sets up the Amazon Cognito hosted UI and hosted UI and OIDC endpoints. For more information, see Using your own domain for the hosted UI.

• You can't sign in federated users with API operations like InitiateAuth and AdminInitiateAuth. Federated users can only sign in with the Login endpoint or the Authorize endpoint.

• The Authorize endpoint is a redirection endpoint. If you provide an idp_identifier or identity_provider parameter in your request, it redirects silently to your IdP, bypassing the hosted UI. Otherwise, it redirects to the hosted UI Login endpoint. For an example, see Example scenario: bookmark Amazon Cognito apps in an enterprise dashboard.

• When the hosted UI redirects a session to a federated IdP, Amazon Cognito includes the user-agent header Amazon/Cognito in the request.

• Amazon Cognito derives the username attribute for a federated user profile from a combination of a fixed identifier and the name of your IdP. To generate a user name that matches your custom requirements, create a mapping to the preferred_username attribute. For more information, see Things to know about mappings.

  Example: [e-mail]

• Amazon Cognito records information about your federated user's identity to an attribute, and a claim in the ID token, called identities. This claim contains your user's provider and their unique ID from the provider. You can't change the identities attribute in a user profile directly. For more information about how to link a federated user, see Linking federated users to an existing user profile.

• When you update your IdP in an UpdateIdentityProvider API request, your changes can take up to a minute to appear in the hosted UI.

• Amazon Cognito supports up to 20 HTTP redirects between itself and your IdP.

• When your user signs in with the hosted UI, their browser stores an encrypted login-session cookie which records the client and provider they signed in with. If they attempt to sign in again with the same parameters, the hosted UI reuses any unexpired existing session, and the user authenticates without providing credentials again. If your user signs in again with a different IdP, including a switch to or from local user pool sign-in, they must provide credentials and generate a new login session.

  You can assign any of your user pool IdPs to any app client, and users can only sign in with an IdP that you assigned to their app client.

Topics

• Configuring identity providers for your user pool
• Adding social identity providers to a user pool
• Adding SAML identity providers to a user pool
• Adding OIDC identity providers to a user pool
• Specifying identity provider attribute mappings for your user pool
• Linking federated users to an existing user profile