# User pool sign-in with third party identity providers
Third-party IdP sign-in
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).
![\[Authentication overview with social sign-in\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-cup.png)
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 [Understanding user pool JSON web tokens (JWTs)](amazon-cognito-user-pools-using-tokens-with-identity-providers.md).
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](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html) for access, ID, and refresh tokens. Then, it must [check the validity of the tokens](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html) 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html) and the [ authentication API endpoints](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html). 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 pages for [managed login](cognito-userpools-server-contract-reference.md). For more information, see [Using your own domain for managed login](cognito-user-pools-add-custom-domain.md).
+ You can't sign in federated users with API operations like [ InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) and [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html). Federated users can only sign in with the [Login endpoint](login-endpoint.md) or the [Authorize endpoint](authorization-endpoint.md).
+ The [Authorize endpoint](authorization-endpoint.md) is a *redirection* endpoint. If you provide an `idp_identifier` or `identity_provider` parameter in your request, it redirects silently to your IdP, bypassing managed login. Otherwise, it redirects to the managed login [Login endpoint](login-endpoint.md).
+ When managed login 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](cognito-user-pools-specifying-attribute-mapping.md#cognito-user-pools-specifying-attribute-mapping-requirements).
Example: `MyIDP_bob@example.com`
+ Amazon Cognito creates a [user group](cognito-user-pools-user-groups.md) for each OIDC, SAMl, and social IdP that you add to your user pool. The name of the group is in the format `[user pool ID]_[IdP name]`, for example `us-east-1_EXAMPLE_MYSSO` or `us-east-1_EXAMPLE_Google`. Each unique automatically-generated IdP user profile is automatically added to this group. [Linked users](cognito-user-pools-identity-federation-consolidate-users.md) aren't automatically added to this group, but you can add their profiles to the group in a separate process.
+ 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](cognito-user-pools-identity-federation-consolidate-users.md).
+ When you update your IdP in an [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request, your changes can take up to a minute to appear in managed login.
+ Amazon Cognito supports up to 20 HTTP redirects between itself and your IdP.
+ When your user signs in with managed login, 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, managed login 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**
+ [
## How federated sign-in works in Amazon Cognito user pools
](#cognito-user-pools-identity-federation-how-it-works)
+ [
## The responsibilities of an app as a service provider with Amazon Cognito
](#cognito-user-pools-identity-federation-how-it-works-app-responsibilities)
+ [
## Things to know about Amazon Cognito user pools third-party sign-in
](#cognito-user-pools-identity-federation-how-it-works-considerations)
+ [
# Configuring identity providers for your user pool
](cognito-user-pools-identity-provider.md)
+ [
# Using social identity providers with a user pool
](cognito-user-pools-social-idp.md)
+ [
# Using SAML identity providers with a user pool
](cognito-user-pools-saml-idp.md)
+ [
# Using OIDC identity providers with a user pool
](cognito-user-pools-oidc-idp.md)
+ [
# Mapping IdP attributes to profiles and tokens
](cognito-user-pools-specifying-attribute-mapping.md)
+ [
# Linking federated users to an existing user profile
](cognito-user-pools-identity-federation-consolidate-users.md)
# Configuring identity providers for your user pool
Identity providers
With user pools, you can implement sign-in through a variety of external identity providers (IdPs). This section of the guide has instructions for setting up these identity providers with your user pool in the Amazon Cognito console. Alternatively, you can use the user pools API and an AWS SDK to programmatically add user pool identity providers. For more information, see [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html).
The supported identity provider options include social providers like Facebook, Google, and Amazon, as well as OpenID Connect (OIDC) and SAML 2.0 providers. Before you get started, set yourself up with administrative credentials for your IdP. For each type of provider, you'll need to register your application, obtain the necessary credentials, and then configure the provider details in your user pool. Your users can then sign up and sign in to your application with their existing accounts from the connected identity providers.
The **Social and external providers** menu under **Authentication** adds and updates user pool IdPs. For more information, see [User pool sign-in with third party identity providers](cognito-user-pools-identity-federation.md).
**Topics**
+ [
## Set up user sign-in with a social IdP
](#cognito-user-pools-facebook-provider)
+ [
## Set up user sign-in with an OIDC IdP
](#cognito-user-pools-oidc-providers)
+ [
## Set up user sign-in with a SAML IdP
](#cognito-user-pools-saml-providers)
## Set up user sign-in with a social IdP
You can use federation to integrate Amazon Cognito user pools with social identity providers such as Facebook, Google, and Login with Amazon.
To add a social identity provider, you first create a developer account with the identity provider. After you have your developer account, register your app with the identity provider. The identity provider creates an app ID and an app secret for your app, and you configure those values in your Amazon Cognito user pools.
+ [Google identity platform](https://developers.google.com/identity/)
+ [Facebook for developers](https://developers.facebook.com/docs/facebook-login)
+ [Login with Amazon](https://developer.amazon.com/login-with-amazon)
+ [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/)
**To integrate user sign-in with a social IdP**
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit.
1. Choose the **Social and external providers** menu.
1. Choose **Add an identity provider**, or choose the **Facebook**, **Google**, **Amazon**, or **Apple** identity provider you have configured, locate **Identity provider information**, and choose **Edit**. For more information about adding a social identity provider, see [Using social identity providers with a user pool](cognito-user-pools-social-idp.md).
1. Enter your social identity provider's information by completing one of the following steps, based on your choice of IdP:
**Facebook, Google, and Login with Amazon**
Enter the app ID and app secret that you received when you created your client app.
**Sign In with Apple**
Enter the service ID that you provided to Apple, and the team ID, key ID, and private key you received when you created your app client.
1. For **Authorized scopes**, enter the names of the social identity provider scopes that you want to map to user pool attributes. Scopes define which user attributes, such as name and email, that you want to access with your app. When entering scopes, use the following guidelines based on your choice of IdP:
+ **Facebook** — Separate scopes with commas. For example:
`public_profile, email`
+ **Google, Login with Amazon, and Sign In with Apple** — Separate scopes with spaces. For example:
+ **Google:** `profile email openid`
+ **Login with Amazon:** `profile postal_code`
+ **Sign In with Apple:** `name email`
**Note**
For Sign In with Apple (console), use the check boxes to choose scopes.
1. Choose **Save changes**.
1. From the **App clients** menu, choose an app client from the list and then select **Edit**. Add the new social identity provider to the app client under **Identity providers**.
1. Choose **Save changes**.
For more information on social IdPs, see [Using social identity providers with a user pool](cognito-user-pools-social-idp.md).
## Set up user sign-in with an OIDC IdP
You can integrate user sign-in with an OpenID Connect (OIDC) identity provider (IdP) such as Salesforce or Ping Identity.
**To add an OIDC provider to a user pool**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools** from the navigation menu.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Social and external providers** menu and select **Add an identity provider**.
1. Choose an **OpenID Connect** identity provider.
1. Enter a unique name into **Provider name**.
1. Enter the client ID that you received from your provider into **Client ID**.
1. Enter the client secret that you received from your provider into **Client secret**.
1. Enter **Authorized scopes** for this provider. Scopes define which groups of user attributes (such as `name` and `email`) that your application will request from your provider. Scopes must be separated by spaces, following the [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-3.3) specification.
Your user must consent to provide these attributes to your application.
1. Choose an **Attribute request method** to provide Amazon Cognito with the HTTP method (either GET or POST) that Amazon Cognito uses to fetch the details of the user from the **userInfo** endpoint operated by your provider.
1. Choose a **Setup method** to retrieve OpenID Connect endpoints either by **Auto fill through issuer URL** or **Manual input**. Use **Auto fill through issuer URL** when your provider has a public `.well-known/openid-configuration` endpoint where Amazon Cognito can retrieve the URLs of the `authorization`, `token`, `userInfo`, and `jwks_uri` endpoints.
1. Enter the issuer URL or `authorization`, `token`, `userInfo`, and `jwks_uri` endpoint URLs from your IdP.
**Note**
You can use only port numbers 443 and 80 with discovery, auto-filled, and manually entered URLs. User logins fail if your OIDC provider uses any nonstandard TCP ports.
The issuer URL must start with `https://`, and must not end with a `/` character. For example, Salesforce uses this URL:
`https://login.salesforce.com`
The `openid-configuration` document associated with your issuer URL must provide HTTPS URLs for the following values: `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, and `jwks_uri`. Similarly, when you choose **Manual input**, you can only enter HTTPS URLs.
1. The OIDC claim **sub** is mapped to the user pool attribute **Username** by default. You can map other OIDC [claims](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims) to user pool attributes. Enter the OIDC claim, and select the corresponding user pool attribute from the drop-down list. For example, the claim **email** is often mapped to the user pool attribute **Email**.
1. Map additional attributes from your identity provider to your user pool. For more information, see [Specifying Identity Provider attribute mappings for your user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-specifying-attribute-mapping.html).
1. Choose **Create**.
1. From the **App clients** menu, select an app client from the list. To add the new SAML identity provider to the app client, navigate to the **Login pages** tab and select **Edit** on **Managed login pages configuration**.
1. Choose **Save changes**.
For more information on OIDC IdPs, see [Using OIDC identity providers with a user pool](cognito-user-pools-oidc-idp.md).
## Set up user sign-in with a SAML IdP
You can use federation for Amazon Cognito user pools to integrate with a SAML identity provider (IdP). You supply a metadata document, either by uploading the file or by entering a metadata document endpoint URL. For information about obtaining metadata documents for third-party SAML IdPs, see [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md).
**To configure a SAML 2.0 identity provider in your user pool**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Social and external provider** menu and select **Add an identity provider**.
1. Choose a **SAML** identity provider.
1. Enter **Identifiers** separated by commas. An identifier directs Amazon Cognito to check the user sign-in email address, and then direct the user to the provider that corresponds to their domain.
1. Choose **Add sign-out flow** if you want Amazon Cognito to send signed sign-out requests to your provider when a user logs out. Configure your SAML 2.0 identity provider to send sign-out responses to the `https://mydomain.auth.us-east-1.amazoncognito.com/saml2/logout` endpoint that Amazon Cognito creates when you configure managed login. The `saml2/logout` endpoint uses POST binding.
**Note**
If you select this option and your SAML identity provider expects a signed logout request, you also must configure the signing certificate provided by Amazon Cognito with your SAML IdP.
The SAML IdP will process the signed logout request and logout your user from the Amazon Cognito session.
1. Choose a **Metadata document source**. If your identity provider offers SAML metadata at a public URL, you can choose **Metadata document URL** and enter that public URL. Otherwise, choose **Upload metadata document** and select a metadata file you downloaded from your provider earlier.
**Note**
If your provider has a public endpoint, we recommend that you enter a metadata document URL, rather than uploading a file. If you use the URL, Amazon Cognito refreshes metadata automatically. Typically, metadata refresh happens every 6 hours or before the metadata expires, whichever is earlier.
1. **Map attributes between your SAML provider and your app** to map SAML provider attributes to the user profile in your user pool. Include your user pool required attributes in your attribute map.
For example, when you choose **User pool attribute** `email`, enter the SAML attribute name as it appears in the SAML assertion from your identity provider. Your identity provider might offer sample SAML assertions for reference. Some identity providers use simple names, such as `email`, while others use URL-formatted attribute names similar to:
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
1. Choose **Create**.
**Note**
If you see `InvalidParameterException` while creating a SAML IdP with an HTTPS metadata endpoint URL, make sure that the metadata endpoint has SSL correctly set up and that there is a valid SSL certificate associated with it. One example of such an exception would be "Error retrieving metadata from **".
**To set up the SAML IdP to add a signing certificate**
+ To get the certificate containing the public key that the IdP uses to verify the signed logout request, do the following:
1. Go to the **Social and external providers** menu of your user pool.
1. Select your SAML provider,
1. Choose **View signing certificate.**
For more information on SAML IdPs see [Using SAML identity providers with a user pool](cognito-user-pools-saml-idp.md).
# Using social identity providers with a user pool
Social identity providers
Your web and mobile app users can sign in through social identity providers (IdP) like Facebook, Google, Amazon, and Apple. With the built-in hosted web UI, Amazon Cognito provides token handling and management for all authenticated users. This way, your backend systems can standardize on one set of user pool tokens. You must enable managed login to integrate with supported social identity providers. When Amazon Cognito builds your managed login pages, it creates OAuth 2.0 endpoints that Amazon Cognito and your OIDC and social IdPs use to exchange information. For more information, see the [Amazon Cognito user pools Auth API reference](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html).
You can add a social IdP in the AWS Management Console, or you can use the AWS CLI or Amazon Cognito API.
**Note**
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).
**Topics**
+ [
## Set up a social IdP developer account and application
](#cognito-user-pools-social-idp-step-1)
+ [
## Configure your user pool with a social IdP
](#cognito-user-pools-social-idp-step-2)
+ [
## Test your social IdP configuration
](#cognito-user-pools-social-idp-step-3)
## Set up a social IdP developer account and application
Set up a developer app
Before you create a social IdP with Amazon Cognito, you must register your application with the social IdP to receive a client ID and client secret.
------
#### [ Facebook ]
For the latest information about configuration of Meta developer accounts and authentication, see [Meta App Development](https://developers.facebook.com/docs/development).
**How to register an application with Facebook/Meta**
1. Create a [developer account with Facebook](https://developers.facebook.com/docs/facebook-login).
1. [Sign in](https://developers.facebook.com/) with your Facebook credentials.
1. From the **My Apps** menu, choose **Create New App**.
1. Enter a name for your Facebook app, and then choose **Create App ID**.
1. On the left navigation bar, choose **Settings**, and then **Basic**.
1. Note the **App ID** and the **App Secret**. You will use them in the next section.
1. Choose **\$1 Add Platform** from the bottom of the page.
1. Choose **Website**.
1. Under **Website**, enter the path to the sign-in page for your app into **Site URL**.
```
https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com
```
1. Choose **Save changes**.
1. Enter the path to the root of your user pool domain into **App Domains**.
```
https://mydomain.auth.us-east-1.amazoncognito.com
```
1. Choose **Save changes**.
1. From the navigation bar choose **Add Product** and choose **Set up** for the **Facebook Login** product.
1. From the navigation bar choose **Facebook Login** and then **Settings**.
Enter the path to the `/oauth2/idpresponse` endpoint for your user pool domain into **Valid OAuth Redirect URIs**.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
```
1. Choose **Save changes**.
------
#### [ Login with Amazon ]
For the latest information about configuration of Login with Amazon developer accounts and authentication, see [Login with Amazon Documentation](https://developer.amazon.com/docs/login-with-amazon/documentation-overview.html).
**How to register an application with Login with Amazon**
1. Create a [developer account with Amazon](https://developer.amazon.com/login-with-amazon).
1. [Sign in](https://developer.amazon.com/lwa/sp/overview.html) with your Amazon credentials.
1. You need to create an Amazon security profile to receive the Amazon client ID and client secret.
Choose **Apps and Services** from navigation bar at the top of the page and then choose **Login with Amazon**.
1. Choose **Create a Security Profile**.
1. Enter a **Security Profile Name**, a **Security Profile Description**, and a **Consent Privacy Notice URL**.
1. Choose **Save**.
1. Choose **Client ID** and **Client Secret** to show the client ID and secret. You will use them in the next section.
1. Hover over the gear icon and choose **Web Settings**, and then choose **Edit**.
1. Enter your user pool domain into **Allowed Origins**.
```
https://mydomain.auth.us-east-1.amazoncognito.com
```
1. Enter your user pool domain with the `/oauth2/idpresponse` endpoint into **Allowed Return URLs**.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
```
1. Choose **Save**.
------
#### [ Google ]
For more information about OAuth 2.0 in the Google Cloud platform, see [Learn about authentication & authorization](https://developers.google.com/workspace/guides/auth-overview) in the Google Workspace for Developers documentation.
**How to register an application with Google**
1. Create a [developer account with Google](https://developers.google.com/identity).
1. Sign in to the [Google Cloud Platform console](https://console.cloud.google.com/home/dashboard).
1. From the top navigation bar, choose **Select a project**. If you already have a project in the Google platform, this menu displays your default project instead.
1. Select **NEW PROJECT**.
1. Enter a name for your product and then choose **CREATE**.
1. On the left navigation bar, choose **APIs and Services**, then **Oauth consent screen**.
1. Enter App information, an **App domain**, **Authorized domains**, and **Developer contact information**. Your **Authorized domains** must include `amazoncognito.com` and the root of your custom domain, for example `example.com`. Choose **SAVE AND CONTINUE**.
1. 1. Under **Scopes**, choose **Add or remove scopes**, and choose, at minimum, the following OAuth scopes.
1. `.../auth/userinfo.email`
1. `.../auth/userinfo.profile`
1. openid
1. Under **Test users**, choose **Add users**. Enter your email address and any other authorized test users, then choose **SAVE AND CONTINUE**.
1. Expand the left navigation bar again, and choose **APIs and Services**, then **Credentials**.
1. Choose **CREATE CREDENTIALS**, then **OAuth client ID**.
1. Choose an **Application type** and give your client a **Name**.
1. Under **Authorized JavaScript origins**, choose **ADD URI**. Enter your user pool domain.
```
https://mydomain.auth.us-east-1.amazoncognito.com
```
1. Under **Authorized redirect URIs**, choose **ADD URI**. Enter the path to the `/oauth2/idpresponse` endpoint of your user pool domain.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
```
1. Choose **CREATE**.
1. Securely store the values the Google displays under **Your client ID** and **Your client secret**. Provide these values to Amazon Cognito when you add a Google IdP.
------
#### [ Sign in with Apple ]
For the most up-to-date information about setting up Sign in with Apple, see [Configuring Your Environment for Sign in with Apple](https://developer.apple.com/documentation/signinwithapple/configuring-your-environment-for-sign-in-with-apple) in the Apple Developer documentation.
**How to register an application with Sign in with Apple (SIWA)**
1. Create a [developer account with Apple](https://developer.apple.com/programs/enroll/).
1. [Sign in](https://developer.apple.com/account/#/welcome) with your Apple credentials.
1. On the left navigation bar, choose **Certificates, Identifiers & Profiles**.
1. On the left navigation bar, choose **Identifiers**.
1. On the **Identifiers** page, choose the **\$1** icon.
1. On the **Register a New Identifier** page, choose **App IDs**, and then choose **Continue**.
1. On the **Select a type** page, choose **App**, then choose **Continue**.
1. On the **Register an App ID** page, do the following:
1. Under **Description**, enter a description.
1. Under **App ID Prefix**, enter a **Bundle ID**. Make a note of the value under **App ID Prefix**. You will use this value after you choose Apple as your identity provider in [Configure your user pool with a social IdP](#cognito-user-pools-social-idp-step-2).
1. Under **Capabilities**, choose **Sign In with Apple**, and then choose **Edit**.
1. On the **Sign in with Apple: App ID Configuration** page, choose to set up the app as either primary or grouped with other App IDs, and then choose **Save**.
1. Choose **Continue**.
1. On the **Confirm your App ID** page, choose **Register**.
1. On the **Identifiers** page, choose the **\$1** icon.
1. On the **Register a New Identifier** page, choose **Services IDs**, and then choose **Continue**.
1. On the **Register a Services ID** page, do the following:
1. Under **Description**, type a description.
1. Under **Identifier**, type an identifier. Make a note of this Services ID as you will need this value after you choose Apple as your identity provider in [Configure your user pool with a social IdP](#cognito-user-pools-social-idp-step-2).
1. Choose **Continue**, then **Register**.
1. Choose the Services ID you just create from the Identifiers page.
1. Select **Sign In with Apple**, and then choose **Configure**.
1. On the **Web Authentication Configuration** page, select the app ID that you created earlier as the **Primary App ID**.
1. Choose the **\$1** icon next to **Website URLs**.
1. Under **Domains and subdomains**, enter your user pool domain without an `https://` prefix.
```
mydomain.auth.us-east-1.amazoncognito.com
```
1. Under **Return URLs**, enter the path to the `/oauth2/idpresponse` endpoint of your user pool domain.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
```
1. Choose **Next**, and then **Done**. You don't need to verify the domain.
1. Choose **Continue**, and then choose **Save**.
1. On the left navigation bar, choose **Keys**.
1. On the **Keys** page, choose the **\$1** icon.
1. On the **Register a New Key** page, do the following:
1. Under **Key Name**, enter a key name.
1. Choose **Sign In with Apple**, and then choose **Configure**.
1. On the **Configure Key** page and select the app ID that you created earlier as the **Primary App ID**. Choose **Save**.
1. Choose **Continue**, and then choose **Register**.
1. On the **Download Your Key** page, choose **Download** to download the private key and note the **Key ID** shown, and then choose **Done**. You will need this private key and the **Key ID** value shown on this page after you choose Apple as your identity provider in [Configure your user pool with a social IdP](#cognito-user-pools-social-idp-step-2).
------
## Configure your user pool with a social IdP
Configure your user pool
**To configure a user pool social IdP with the AWS Management Console**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list or create a user pool.
1. Choose the **Social and external providers** menu and then select **Add an identity provider**.
1. Choose a social IdP: **Facebook**, **Google**, **Login with Amazon**, or **Sign in with Apple**.
1. Choose from the following steps, based on your choice of social IdP:
+ **Google** and **Login with Amazon** — Enter the **app client ID** and **app client secret** generated in the previous section.
+ **Facebook** — Enter the **app client ID** and **app client secret** generated in the previous section, and then choose an API version (for example, version 2.12). We recommend that you choose the latest possible version, as each Facebook API has a lifecycle and discontinuation date. Facebook scopes and attributes can vary between API versions. We recommend that you test your social identity log in with Facebook to make sure that federation works as you intend.
+ **Sign In with Apple** — Enter the **Services ID**, **Team ID**, **Key ID**, and **private key** generated in the previous section.
1. Enter the names of the **Authorized scopes** you want to use. Scopes define which user attributes (such as `name` and `email`) you want to access with your app. For Facebook, these should be separated by commas. For Google and Login with Amazon, they should be separated by spaces. For Sign in with Apple, select the check boxes for the scopes you want access to.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-social-idp.html)
Your app user is prompted to consent to providing these attributes to your app. For more information about social provider scopes, see the documentation from Google, Facebook, Login with Amazon, or Sign in with Apple.
With Sign in with Apple, the following are user scenarios where scopes might not be returned:
+ An end user encounters failures after leaving Apple’s sign in page (can be from Internal failures within Amazon Cognito or anything written by the developer)
+ The service ID identifier is used across user pools and/or other authentication services
+ A developer adds additional scopes after the end user has signed in before (no new information is retrieved)
+ A developer deletes the user and then the user signs in again without removing the app from their Apple ID profile
1. Map attributes from your IdP to your user pool. For more information, see [Specifying Identity Provider Attribute Mappings for Your User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-specifying-attribute-mapping.html).
1. Choose **Create**.
1. From the **App clients** menu, select an app client from the list. To add the new social identity provider to the app client, navigate to the **Login pages** tab and select **Edit** on **Managed login pages configuration**.
1. Choose **Save changes**.
## Test your social IdP configuration
Test social sign-in
In your application, you must invoke a browser in the user's client so that they can sign in with their social provider. Test sign-in with your social provider after you have completed the setup procedures in the preceding sections. The following example URL loads the sign-in page for your user pool with a prefix domain.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com
```
This link is the page that Amazon Cognito directs you to when you go to the **App clients** menu, select an app client, navigate to the **Login pages** tab, and select **View login page**. For more information about user pool domains, see [Configuring a user pool domain](cognito-user-pools-assign-domain.md). For more information about app clients, including client IDs and callback URLs, see [Application-specific settings with app clients](user-pool-settings-client-apps.md).
The following example link sets up silent redirect to a social provider from the [Authorize endpoint](authorization-endpoint.md) with an `identity_provider` query parameter. This URL bypasses interactive user pool sign-in with managed login and goes directly to the IdP sign-in page.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?identity_provider=Facebook|Google|LoginWithAmazon|SignInWithApple&response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com
```
# Using SAML identity providers with a user pool
SAML providers
You can choose to have your web and mobile app users sign in through a SAML identity provider (IdP) like [Microsoft Active Directory Federation Services (ADFS)](https://msdn.microsoft.com/en-us/library/bb897402.aspx), or [Shibboleth](http://www.shibboleth.net/). You must choose a SAML IdP which supports the [SAML 2.0 standard](http://saml.xml.org/saml-specifications).
With managed login, Amazon Cognito authenticates local and third-party IdP users and issues JSON web tokens (JWTs). With the tokens that Amazon Cognito issues, you can consolidate multiple identity sources into a universal OpenID Connect (OIDC) standard across all of your apps. Amazon Cognito can process SAML assertions from your third-party providers into that SSO standard. You can create and manage a SAML IdP in the AWS Management Console, through the AWS CLI, or with the Amazon Cognito user pools API. To create your first SAML IdP in the AWS Management Console, see [Adding and managing SAML identity providers in a user pool](cognito-user-pools-managing-saml-idp.md).
![\[Authentication overview with SAML sign-in\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml.png)
**Note**
Federation with sign-in through a third-party IdP is a feature of Amazon Cognito user pools. Amazon Cognito identity pools, sometimes called Amazon Cognito federated identities, are an implementation of federation that you must set up separately in each identity pool. A user pool can be a third-party IdP to an identity pool. For more information, see [Amazon Cognito identity pools](cognito-identity.md).
## Quick reference for IdP configuration
Quick reference
You must configure your SAML IdP to accept request and send responses to your user pool. The documentation for your SAML IdP will contain information about how to add your user pool as a relying party or application for your SAML 2.0 IdP. The documentation that follows provides the values that you must provide for the SP entity ID and assertion consumer service (ACS) URL.User pool SAML values quick reference
**SP entity ID**
```
urn:amazon:cognito:sp:us-east-1_EXAMPLE
```
**ACS URL**
```
https://Your user pool domain/saml2/idpresponse
```
You must configure your user pool to support your identity provider. The high-level steps to add an external SAML IdP are as follows.
1. Download SAML metadata from your IdP, or retrieve the URL to your metadata endpoint. See [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md).
1. Add a new IdP to your user pool. Upload the SAML metadata or provide the metadata URL. See [Adding and managing SAML identity providers in a user pool](cognito-user-pools-managing-saml-idp.md).
1. Assign the IdP to your app clients. See [Application-specific settings with app clients](user-pool-settings-client-apps.md).
**Topics**
+ [
## Quick reference for IdP configuration
](#cognito-user-pools-saml-idp-reference)
+ [
# Things to know about SAML IdPs in Amazon Cognito user pools
](cognito-user-pools-saml-idp-things-to-know.md)
+ [
## Case sensitivity of SAML user names
](#saml-nameid-case-sensitivity)
+ [
# Configuring your third-party SAML identity provider
](cognito-user-pools-integrating-3rd-party-saml-providers.md)
+ [
# Adding and managing SAML identity providers in a user pool
](cognito-user-pools-managing-saml-idp.md)
+ [
# SAML session initiation in Amazon Cognito user pools
](cognito-user-pools-SAML-session-initiation.md)
+ [
# Signing out SAML users with single sign-out
](cognito-user-pools-saml-idp-sign-out.md)
+ [
# SAML signing and encryption
](cognito-user-pools-SAML-signing-encryption.md)
+ [
# SAML identity provider names and identifiers
](cognito-user-pools-managing-saml-idp-naming.md)
# Things to know about SAML IdPs in Amazon Cognito user pools
Things to know
Implementation of a SAML 2.0 IdP comes with some requirements and restrictions. Refer to this section when you're implementing your IdP. You'll also find information that's useful for troubleshooting errors during SAML federation with a user pool.
**Amazon Cognito processes SAML assertions for you**
Amazon Cognito user pools support SAML 2.0 federation with POST-binding endpoints. This eliminates the need for your app to retrieve or parse SAML assertion responses, because the user pool directly receives the SAML response from your IdP through a user agent. Your user pool acts as a service provider (SP) on behalf of your application. Amazon Cognito supports SP-initiated and IdP-initiated single sign-on (SSO) as described in sections 5.1.2 and 5.1.4 of the [SAML V2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html).
**Provide a valid IdP signing certificate**
The signing certificate in your SAML provider metadata must not be expired when you configure the SAML IdP in your user pool.
**User pools support multiple signing certificates**
When your SAML IdP includes more than one signing certificate in SAML metadata, at sign-in your user pool determines that the SAML assertion is valid if it matches any certificate in the SAML metadata. Each signing certificate must be no longer than 4,096 characters in length.
**Maintain the relay state parameter**
Amazon Cognito and your SAML IdP maintain session information with a `relayState` parameter.
1. Amazon Cognito supports `relayState` values greater than 80 bytes. While SAML specifications state that the `relayState` value "must not exceed 80 bytes in length”, current industry practice often deviates from this behavior. As a consequence, rejecting `relayState` values greater than 80 bytes will break many standard SAML provider integrations.
1. The `relayState` token is an opaque reference to state information maintained by Amazon Cognito. Amazon Cognito doesn't guarantee the contents of the `relayState` parameter. Don't parse its contents such that your app depends on the result. For more information, see the [SAML 2.0 specification](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
**Identify the ACS endpoint**
Your SAML identity provider requires that you set an assertion consumer endpoint. Your IdP redirects your users to this endpoint with their SAML assertion. Configure the following endpoint in your user pool domain for SAML 2.0 POST binding in your SAML identity provider.
```
https://Your user pool domain/saml2/idpresponse
With an Amazon Cognito domain:
https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse
With a custom domain:
https://auth.example.com/saml2/idpresponse
```
See [Configuring a user pool domain](cognito-user-pools-assign-domain.md) for more information about user pool domains.
**No replayed assertions**
You can't repeat, or *replay*, a SAML assertion to your Amazon Cognito `saml2/idpresponse` endpoint. A replayed SAML assertion has an assertion ID that duplicates the ID of an earlier IdP response.
**User pool ID is SP entity ID**
You must provide your IdP with your user pool ID in the service provider (SP) `urn`, also called the *audience URI* or *SP entity ID*. The audience URI for your user pool has the following format.
```
urn:amazon:cognito:sp:us-east-1_EXAMPLE
```
You can find your user pool ID under **User pool overview** in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).
**Map all required attributes**
Configure your SAML IdP to provide values for any attributes that you set as required in your user pool. For example, `email` is a common required attribute for user pools. Before your users can sign in, your SAML IdP assertions must include a claim that you map to the **User pool attribute** `email`. For more information about attribute mapping, see [Mapping IdP attributes to profiles and tokens](cognito-user-pools-specifying-attribute-mapping.md).
**Assertion format has specific requirements**
Your SAML IdP must include the following claims in the SAML assertion.
+ A `NameID` claim. Amazon Cognito associates a SAML assertion with the destination user by `NameID`. If `NameID` changes, Amazon Cognito considers the assertion to be for a new user. The attribute that you set to `NameID` in your IdP configuration must have a persistent value. To assign SAML users to a consistent user profile in your user pool, assign your `NameID` claim from an attribute with a value that doesn't change.
```
carlos
```
A `Format` in your IdP `NameID` claim of `urn:oasis:names:tc:SAML:1.1:nameid-format:persistent` indicates that your IdP is passing an unchanging value. Amazon Cognito doesn't require this format declaration, and assigns a format of `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` if your IdP doesn't specify a format of the `NameID` claim. This behavior complies with section 2.2.2 *Complex Type NameIDType*, of [the SAML 2.0 specification](https://groups.oasis-open.org/higherlogic/ws/public/download/35711/sstc-saml-core-errata-2.0-wd-06-diff.pdf/latest).
+ An `AudienceRestriction` claim with an `Audience` value that sets your user pool SP entity ID as the target of the response.
```
urn:amazon:cognito:sp:us-east-1_EXAMPLE
```
+ For SP-initiated single sign-on, a `Response` element with an `InResponseTo` value of the original SAML request ID.
```
```
**Note**
IdP-initiated SAML assertions must *not* contain an `InResponseTo` value.
+ A `SubjectConfirmationData` element with a `Recipient` value of your user pool `saml2/idpresponse` endpoint and, for SP-initiated SAML, an `InResponseTo` value that matches the original SAML request ID.
```
```
**SP-initiated sign-in requests**
When the [Authorize endpoint](authorization-endpoint.md) redirects your user to your IdP sign-in page, Amazon Cognito includes a *SAML request* in a URL parameter of the `HTTP GET` request. A SAML request contains information about your user pool, including your ACS endpoint. You can optionally apply a cryptographic signature to these requests.
**Sign requests and encrypt responses**
Every user pool with a SAML provider generates an asymmetric key pair and *signing certificate* for a digital signature that Amazon Cognito assigns to SAML requests. Every external SAML IdP that you configure to support encrypted SAML response causes Amazon Cognito to generate a new key pair and *encryption certificate* for that provider. To view and download the certificates with the public key, choose your IdP in the **Social and external providers** menu in the Amazon Cognito console.
To establish trust with SAML requests from your user pool, provide your IdP with a copy of your user pool SAML 2.0 signing certificate. Your IdP might ignore SAML requests that your user pool signed if you don’t configure the IdP to accept signed requests.
1. Amazon Cognito applies a digital signature to SAML requests that your user passes to your IdP. Your user pool signs all single logout (SLO) requests, and you can configure your user pool to sign single sign-on (SSO) requests for any SAML external IdP. When you provide a copy of the certificate, your IdP can verify the integrity of your users' SAML requests.
1. Your SAML IdP can encrypt SAML responses with the encryption certificate. When you configure an IdP with SAML encryption, your IdP must only send encrypted responses.
**Encode non-alphanumeric characters**
Amazon Cognito doesn't accept 4-byte UTF-8 characters like 😐 or 𠮷 that your IdP passes as an attribute value. You can encode the character to Base64, pass it as text, and then decode it in your app.
In the following example, the attribute claim will not be accepted:
```
😐
```
In contrast to the preceding example, the following attribute claim will be accepted:
```
8J+YkA==
```
**Metadata endpoint must have valid transport-layer security**
If you see `InvalidParameterException` while creating a SAML IdP with an HTTPS metadata endpoint URL, for example, "Error retrieving metadata from **," make sure that the metadata endpoint has SSL correctly set up and that there is a valid SSL certificate associated with it. For more information about validating certificates, see [What Is An SSL/TLS Certificate?](https://aws.amazon.com/what-is/ssl-certificate/).
**Metadata endpoint must be on standard TCP port for HTTP or HTTPS**
Amazon Cognito only accepts metadata URLs for SAML providers on the standard TCP ports 80 for HTTP and 443 for HTTPS. As a security best practice, host SAML metadata at a TLS-encrypted URL with the `https://` prefix. Enter metadata URLs in the format *`http://www.example.com/saml2/metadata.xml`* or *`https://www.example.com/saml2/metadata.xml`*. The Amazon Cognito console accepts metadata URLs only with the `https://` prefix. You can also configure IdP metadata with [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) and [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html).
**App clients with IdP-initiated SAML can only sign in with SAML**
When you activate support for a SAML 2.0 IdP that supports IdP-initiated sign in an app client, you can only add other SAML 2.0 IdPs to that app client. You're prevented from adding the user directory in the user pool *and* all non-SAML external identity providers to an app client configured in this way.
**Logout responses must use POST binding**
The `/saml2/logout` endpoint accepts `LogoutResponse` as `HTTP POST` requests. User pools don't accept logout responses with `HTTP GET` binding.
**Metadata Signing Certificate Rotation**
Amazon Cognito caches SAML metadata for up to six hours when you provide metadata with a URL. When performing any metadata signing certificate rotation, configure your metadata source to publish *both* the original and new certificates for at least six hours. When Amazon Cognito refreshes the cache from the metadata URL, it treats each certificate as valid and your SAML IdP can start signing SAML assertions with the new certificate. After this period has elapsed, you can remove the original certificate from the published metadata.
## Case sensitivity of SAML user names
Case sensitivity
When a federated user attempts to sign in, the SAML identity provider (IdP) passes a unique `NameId` to Amazon Cognito in the user's SAML assertion. Amazon Cognito identifies a SAML-federated user by their `NameId` claim. Regardless of the case sensitivity settings of your user pool, Amazon Cognito recognizes a returning federated user from a SAML IdP when they pass their unique and case-sensitive `NameId` claim. If you map an attribute like `email` to `NameId`, and your user changes their email address, they can't sign in to your app.
Map `NameId` in your SAML assertions from an IdP attribute that has values that don't change.
For example, Carlos has a user profile in your case-insensitive user pool from an Active Directory Federation Services (ADFS) SAML assertion that passed a `NameId` value of `Carlos@example.com`. The next time Carlos attempts to sign in, your ADFS IdP passes a `NameId` value of `carlos@example.com`. Because `NameId` must be an exact case match, the sign-in doesn't succeed.
If your users can't log in after their `NameID` changes, delete their user profiles from your user pool. Amazon Cognito will create new user profiles the next time they sign in.
**Topics**
+ [
## Quick reference for IdP configuration
](#cognito-user-pools-saml-idp-reference)
+ [
# Things to know about SAML IdPs in Amazon Cognito user pools
](cognito-user-pools-saml-idp-things-to-know.md)
+ [
## Case sensitivity of SAML user names
](#saml-nameid-case-sensitivity)
+ [
# Configuring your third-party SAML identity provider
](cognito-user-pools-integrating-3rd-party-saml-providers.md)
+ [
# Adding and managing SAML identity providers in a user pool
](cognito-user-pools-managing-saml-idp.md)
+ [
# SAML session initiation in Amazon Cognito user pools
](cognito-user-pools-SAML-session-initiation.md)
+ [
# Signing out SAML users with single sign-out
](cognito-user-pools-saml-idp-sign-out.md)
+ [
# SAML signing and encryption
](cognito-user-pools-SAML-signing-encryption.md)
+ [
# SAML identity provider names and identifiers
](cognito-user-pools-managing-saml-idp-naming.md)
# Configuring your third-party SAML identity provider
Provider application configuration
When you want to add a SAML identity provider (IdP) to your user pool, you must make some configuration updates in the management interface of your IdP. This section describes how to format the values that you must provide to your IdP. You can also learn about how to retrieve the static or active-URL metadata document that identifies the IdP and its SAML claims to your user pool.
To configure third-party SAML 2.0 identity provider (IdP) solutions to work with federation for Amazon Cognito user pools, you must configure your SAML IdP to redirect to the following Assertion Consumer Service (ACS) URL: `https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse`. If your user pool has an Amazon Cognito domain, you can find your user pool domain path in the **Domain** menu of your user pool in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).
Some SAML IdPs require that you provide the `urn`, also called the audience URI or SP entity ID, in the form `urn:amazon:cognito:sp:us-east-1_EXAMPLE`. You can find your user pool ID under **User pool overview** in the Amazon Cognito console.
You must also configure your SAML IdP to provide values for any attributes that you designated as *required attributes* in your user pool. Typically, `email` is a required attribute for user pools, in which case the SAML IdP must provide some form of an `email` claim in their SAML assertion, and you must map the claim to the attribute for that provider.
The following configuration information for third-party SAML 2.0 IdP solutions is a good place to start setting up federation with Amazon Cognito user pools. For the most current information, consult your provider's documentation directly.
To sign SAML requests, you must configure your IdP to trust requests signed by your user pool signing certificate. To accept encrypted SAML responses, you must configure your IdP to encrypt *all* SAML responses to your user pool. Your provider will have documentation about configuring these features. For an example from Microsoft, see [Configure Microsoft Entra SAML token encryption](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/howto-saml-token-encryption).
**Note**
Amazon Cognito only requires your identity provider metadata document. Your provider might also offer customized configuration information for SAML 2.0 federation with IAM or AWS IAM Identity Center. To learn how to set up Amazon Cognito integration, look for general directions for retrieving the metadata document and manage the rest of the configuration in your user pool.
| Solution | More information |
| --- | --- |
| Microsoft Entra ID | [Federation Metadata](https://learn.microsoft.com/en-us/entra/identity-platform/federation-metadata) |
| Okta | [How to Download the IdP Metadata and SAML Signing Certificates for a SAML App Integration](https://support.okta.com/help/s/article/Location-to-download-Okta-IDP-XML-metadata-for-a-SAML-app-in-the-new-Admin-User-Interface) |
| Auth0 | [Configure Auth0 as SAML Identity Provider](https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-identity-provider) |
| Ping Identity (PingFederate) | [Exporting SAML metadata from PingFederate](https://docs.pingidentity.com/integrations/contentful/configuring_single_sign-on/pf_contentful_integration_exporting_saml_metadata_from_pf.html) |
| JumpCloud | [SAML Configuration Notes](https://jumpcloud.com/support/saml-configuration-notes) |
| SecureAuth | [SAML application integration](https://docs.secureauth.com/2104/en/saml-application-integration.html) |
# Adding and managing SAML identity providers in a user pool
Add a SAML provider
After you configure your identity provider to work with Amazon Cognito, you can add it to your user pools and app clients. The following procedures demonstrate how to create, modify, and delete SAML providers in an Amazon Cognito user pool.
------
#### [ AWS Management Console ]
You can use the AWS Management Console to create and delete SAML identity providers (IdPs).
Before you create a SAML IdP, you must have the SAML metadata document that you get from the third-party IdP. For instructions on how to get or generate the required SAML metadata document, see [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md).
**To configure a SAML 2.0 IdP in your user pool**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Social and external providers** menu and then select **Add an identity provider**.
1. Choose a **SAML** IdP.
1. Enter a **Provider name**. You can pass this friendly name in an `identity_provider` request parameter to the [Authorize endpoint](authorization-endpoint.md).
1. Enter **Identifiers** separated by commas. An identifier tells Amazon Cognito it should check the email address a user enters when they sign in, and then direct them to the provider that corresponds to their domain.
1. Choose **Add sign-out flow** if you want Amazon Cognito to send signed sign-out requests to your provider when a user logs out. You must configure your SAML 2.0 IdP to send sign-out responses to the `https://mydomain.auth.us-east-1.amazoncognito.com/saml2/logout` endpoint that is created when you configure managed login. The `saml2/logout` endpoint uses POST binding.
**Note**
If this option is selected and your SAML IdP expects a signed logout request, you must also provide your SAML IdP with the signing certificate from your user pool.
The SAML IdP will process the signed logout request and sign out your user from the Amazon Cognito session.
1. Choose your **IdP-initiated SAML sign-in** configuration. As a security best practice, choose **Accept SP-initiated SAML assertions only**. If you have prepared your environment to securely accept unsolicited SAML sign-in sessions, choose **Accept SP-initiated and IdP-initiated SAML assertions**. For more information, see [SAML session initiation in Amazon Cognito user pools](cognito-user-pools-SAML-session-initiation.md).
1. Choose a **Metadata document source**. If your IdP offers SAML metadata at a public URL, you can choose **Metadata document URL** and enter that public URL. Otherwise, choose **Upload metadata document** and select a metadata file you downloaded from your provider earlier.
**Note**
We recommend that you enter a metadata document URL if your provider has a public endpoint instead of uploading a file. Amazon Cognito automatically refreshes metadata from the metadata URL. Typically, metadata refresh happens every 6 hours or before the metadata expires, whichever is earlier.
1. **Map attributes between your SAML provider and your user pool** to map SAML provider attributes to the user profile in your user pool. Include your user pool required attributes in your attribute map.
For example, when you choose **User pool attribute** `email`, enter the SAML attribute name as it appears in the SAML assertion from your IdP. If your IdP offers sample SAML assertions, you can use these sample assertions to help you to find the name. Some IdPs use simple names, such as `email`, while others use names like the following.
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
1. Choose **Create**.
------
#### [ API/CLI ]
Use the following commands to create and manage a SAML identity provider (IdP).
**To create an IdP and upload a metadata document**
+ AWS CLI: `aws cognito-idp create-identity-provider`
Example with metadata file: `aws cognito-idp create-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-type SAML --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
Where `details.json` contains:
```
"ProviderDetails": {
"MetadataFile": "",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
```
**Note**
If the ** contains any instances of the character `"`, you must add `\` as an escape character: `\"`.
Example with metadata URL: `aws cognito-idp create-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-type SAML --provider-details MetadataURL=https://myidp.example.com/sso/saml/metadata --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
+ AWS API: [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html)
**To upload a new metadata document for an IdP**
+ AWS CLI: `aws cognito-idp update-identity-provider`
Example with metadata file: `aws cognito-idp update-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
Where `details.json` contains:
```
"ProviderDetails": {
"MetadataFile": "",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
```
**Note**
If the ** contains any instances of the character `"`, you must add `\` as an escape character: `\"`.
Example with metadata URL: `aws cognito-idp update-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-details MetadataURL=https://myidp.example.com/sso/saml/metadata --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
+ AWS API: [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html)
**To get information about a specific IdP**
+ AWS CLI: `aws cognito-idp describe-identity-provider`
`aws cognito-idp describe-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1`
+ AWS API: [DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html)
**To list information about all IdPs**
+ AWS CLI: `aws cognito-idp list-identity-providers`
Example: `aws cognito-idp list-identity-providers --user-pool-id us-east-1_EXAMPLE --max-results 3`
+ AWS API: [ListIdentityProviders](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListIdentityProviders.html)
**To delete an IdP**
+ AWS CLI: `aws cognito-idp delete-identity-provider`
`aws cognito-idp delete-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1`
+ AWS API: [DeleteIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteIdentityProvider.html)
------
**To set up the SAML IdP to add a user pool as a relying party**
+ The user pools service provider URN is: `urn:amazon:cognito:sp:us-east-1_EXAMPLE`. Amazon Cognito requires an audience restriction value that matches this URN in the SAML response. Configure your IdP to use the following POST binding endpoint for the IdP-to-SP response message.
```
https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse
```
+ Your SAML IdP must populate `NameID` and any required attributes for your user pool in the SAML assertion. `NameID` is used for uniquely identifying your SAML federated user in the user pool. Your IdP must pass each user’s SAML name ID in a consistent, case-sensitive format. Any variation in the value of a user's name ID creates a new user profile.
**To provide a signing certificate to your SAML 2.0 IDP**
+ To download a copy of the the public key from Amazon Cognito that your IdP can use to validate SAML logout requests, choose the **Social and external providers** menu of your user pool, select your IdP, and under **View signing certificate**, select **Download as .crt**.
You can delete any SAML provider you have set up in your user pool with the Amazon Cognito console.
**To delete a SAML provider**
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).
1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit.
1. Choose the **Social and external providers** menu.
1. Select the radio button next to the SAML IdPs you wish to delete.
1. When you are prompted to **Delete identity provider**, enter the name of the SAML provider to confirm deletion, and then choose **Delete**.
# SAML session initiation in Amazon Cognito user pools
SP- and IdP-initiated sign-in
Amazon Cognito supports service provider-initiated (SP-initiated) single sign-on (SSO) and IdP-initiated SSO. As a best security practice, implement SP-initiated SSO in your user pool. Section 5.1.2 of the [ SAML V2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#5.1.2.SP-Initiated%20SSO:%20%20Redirect/POST%20Bindings|outline) describes SP-initiated SSO. Amazon Cognito is the identity provider (IdP) to your app. The app is the service provider (SP) that retrieves tokens for authenticated users. However, when you use a third-party IdP to authenticate users, Amazon Cognito is the SP. When your SAML 2.0 users authenticate with an SP-initiated flow, they must always first make a request to Amazon Cognito and redirect to the IdP for authentication.
For some enterprise use cases, access to internal applications starts at a bookmark on a dashboard hosted by the enterprise IdP. When a user selects a bookmark, the IdP generates a SAML response and sends it to the SP to authenticate the user with the application.
You can configure a SAML IdP in your user pool to support IdP-initiated SSO. When you support IdP-initiated authentication, Amazon Cognito can't verify that it has solicited the SAML response that it receives because Amazon Cognito doesn't initiate authentication with a SAML request. In SP-initiated SSO, Amazon Cognito sets state parameters that validate a SAML response against the original request. With SP-initiated sign-in you can also guard against cross-site request forgery (CSRF).
**Topics**
+ [
## Implement SP-initated SAML sign-in
](#cognito-user-pools-saml-idp-authentication)
+ [
## Implement IdP-initiated SAML sign-in
](#cognito-user-pools-SAML-session-initiation-idp-initiation)
## Implement SP-initated SAML sign-in
SP-initiated sign-in
As a best practice, implement service-provider-initiated (SP-initiated) sign-in to your user pool. Amazon Cognito initiates your user's session and redirects them to your IdP. With this method, you have the greatest control over who presents sign-in requests. You can also permit IdP-initiated sign-in under certain conditions.
The following process shows how users complete SP-initiated sign in to your user pool through a SAML provider.
![\[Authentication flow diagram of Amazon Cognito SP-initiated SAML sign-in.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-stepbystep.png)
1. Your user enters their email address at a sign-in page. To determine your user’s redirect to their IdP, you can collect their email address in a custom-built application or invoke managed login in web view.
You can configure your managed login pages to display a list of IdPs or to prompt for an email address and match it to the identifier of your SAML IdP. To prompt for an email address, edit your managed login branding style and in **Foundation**, locate **Authentication behavior** and under **Provider display**, set **Display style** to **Domain search input**.
1. Your app invokes your user pool redirect endpoint and requests a session with the client ID that corresponds to the app and the IdP ID that corresponds to the user.
1. Amazon Cognito redirects your user to the IdP with a SAML request, [optionally signed](cognito-user-pools-SAML-signing-encryption.md#cognito-user-pools-SAML-signing.title), in an `AuthnRequest` element.
1. The IdP authenticates the user interactively, or with a remembered session in a browser cookie.
1. The IdP redirects your user to your user pool SAML response endpoint with the [optionally-encrypted](cognito-user-pools-SAML-signing-encryption.md#cognito-user-pools-SAML-signing-encryption.title) SAML assertion in their POST payload.
**Note**
Amazon Cognito cancels sessions that don't receive a response within 5 minutes, and redirects the user to managed login. When your user experiences this outcome, they receive a `Something went wrong` error message.
1. After it verifies the SAML assertion and [maps user attributes](cognito-user-pools-specifying-attribute-mapping.md#cognito-user-pools-specifying-attribute-mapping.title) from the claims in the response, Amazon Cognito internally creates or updates the user's profile in the user pool. Typically, your user pool returns an authorization code to your user's browser session.
1. Your user presents their authorization code to your app, which exchanges the code for JSON web tokens (JWTs).
1. Your app accepts and processes your user's ID token as authentication, generates authorized requests to resources with their access token, and stores their refresh token.
When a user authenticates and receives an authorization code grant, the user pool returns ID, access, and refresh tokens. The ID token is a authentication object for OIDC-based identity management. The access token is an authorization object with [OAuth 2.0](https://oauth.net/2/) scopes. The refresh token is an object that generates new ID and access tokens when your user's current tokens have expired. You can configure the duration of users' tokens in your user pool app client.
You can also choose the duration of refresh tokens. After a user's refresh token expires, they must sign in again. If they authenticated through a SAML IdP, your users' session duration is set by the expiration of their tokens, not the expiration of their session with their IdP. Your app must store each user's refresh token and renew their session when it expires. Managed login maintains user sessions in a browser cookie that's valid for 1 hour.
## Implement IdP-initiated SAML sign-in
IdP-initiated sign-in
When you configure your identity provider for IdP-initiated SAML 2.0 sign-in, you can present SAML assertions to the `saml2/idpresponse` endpoint in your user pool domain without the need to initiate the session at the [Authorize endpoint](authorization-endpoint.md). A user pool with this configuration accepts IdP-initiated SAML assertions from a user pool external identity provider that the requested app client supports.
![\[Authentication flow diagram of Amazon Cognito IdP-initiated SAML sign-in.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-idpinit.png)
1. A user requests SAML sign-in with your application.
1. Your application invokes a browser or redirects the user to the sign-in page for their SAML provider.
1. The IdP authenticates the user interactively, or with a remembered session in a browser cookie.
1. The IdP redirects your user to your application with the SAML assertion, or response, in their POST body.
1. Your application adds the SAML assertion to the POST body of a request to your user pool `saml2/idpresponse` endpoint.
1. Amazon Cognito issues an authorization code to your user.
1. Your user presents their authorization code to your app, which exchanges the code for JSON web tokens (JWTs).
1. Your application accepts and processes your user's ID token as authentication, generates authorized requests to resources with their access token, and stores their refresh token.
The following steps describe the overall process to configure and sign in with an IdP-initiated SAML 2.0 provider.
1. Create or designate a user pool and app client.
1. Create a SAML 2.0 IdP in your user pool.
1. Configure your IdP to support IdP initiation. IdP-initiated SAML introduces security considerations that other SSO providers aren’t subject to. Because of this, you can’t add non-SAML IdPs, including the user pool itself, to any app client that uses a SAML provider with IdP-initiated sign-in.
1. Associate your IdP-initiated SAML provider with an app client in your user pool.
1. Direct your user to the sign-in page for your SAML IdP and retrieve a SAML assertion.
1. Direct your user to your user pool `saml2/idpresponse` endpoint with their SAML assertion.
1. Receive JSON web tokens (JWTs).
To accept unsolicited SAML assertions in your user pool, you must consider its effect on your app security. Request spoofing and CSRF attempts are likely when you accept IdP-initiated requests. Although your user pool can't verify an IdP-initiated sign-in session, Amazon Cognito validates your request parameters and SAML assertions.
Additionally, your SAML assertion must not contain an `InResponseTo` claim and must have been issued within the previous 6 minutes.
You must submit requests with IdP-initiated SAML to your `/saml2/idpresponse`. For SP-initiated and managed login authorization requests, you must provide parameters that identify your requested app client, scopes, redirect URI, and other details as query string parameters in `HTTP GET` requests. For IdP-initiated SAML assertions, however, the details of your request must be formatted as a `RelayState` parameter in the body of an `HTTP POST` request. The request body must also contain your SAML assertion as a `SAMLResponse` parameter.
The following is an example request and response for an IdP-initiated SAML provider.
```
POST /saml2/idpresponse HTTP/1.1
User-Agent: USER_AGENT
Accept: */*
Host: example.auth.us-east-1.amazoncognito.com
Content-Type: application/x-www-form-urlencoded
SAMLResponse=[Base64-encoded SAML assertion]&RelayState=identity_provider%3DMySAMLIdP%26client_id%3D1example23456789%26redirect_uri%3Dhttps%3A%2F%2Fwww.example.com%26response_type%3Dcode%26scope%3Demail%2Bopenid%2Bphone
HTTP/1.1 302 Found
Date: Wed, 06 Dec 2023 00:15:29 GMT
Content-Length: 0
x-amz-cognito-request-id: 8aba6eb5-fb54-4bc6-9368-c3878434f0fb
Location: https://www.example.com?code=[Authorization code]
```
------
#### [ AWS Management Console ]
**To configure an IdP for IdP-initiated SAML**
1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML identity provider.
1. Disassociate all social and OIDC identity providers from your app client, if any are associated.
1. Navigate to the **Social and external providers** menu of your user pool.
1. Edit or add a SAML provider.
1. Under **IdP-initiated SAML sign-in**, choose **Accept SP-initiated and and IdP-initiated SAML assertions**.
1. Choose **Save changes**.
------
#### [ API/CLI ]
**To configure an IdP for IdP-initiated SAML**
Configure IdP-initiated SAML with the `IDPInit` parameter in a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports IdP-initiated SAML.
```
"ProviderDetails": {
"MetadataURL" : "https://myidp.example.com/saml/metadata",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
```
------
# Signing out SAML users with single sign-out
Single sign-out with SAML
Amazon Cognito supports SAML 2.0 [single logout](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#5.3.Single%20Logout%20Profile|outline) (SLO. With SLO, your application can sign out users from their SAML identity providers (IdPs) when they sign out from your user pool. This way, when users want to sign in to your application again, they must authenticate with their SAML IdP. Otherwise, they might have IdP or user pool browser cookies in place that pass them through to your application without the requirement that they provide credentials.
When you configure your SAML IdP to support **Sign-out flow**, Amazon Cognito redirects your user with a signed SAML logout request to your IdP. Amazon Cognito determines the redirect location from the `SingleLogoutService` URL in your IdP metadata. Amazon Cognito signs the sign-out request with your user pool signing certificate.
![\[Authentication flow diagram of Amazon Cognito SAML sign-out. The user requests sign-out and Amazon Cognito redirects them to their provider with a SAML sign-out request.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-sign-out.png)
When you direct a user with a SAML session to your user pool `/logout` endpoint, Amazon Cognito redirects your SAML user with the following request to the SLO endpoint that's specified in the IdP metadata.
```
https://[SingleLogoutService endpoint]?
SAMLRequest=[encoded SAML request]&
RelayState=[RelayState]&
SigAlg=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256&
Signature=[User pool RSA signature]
```
Your user then returns to your `saml2/logout` endpoint with a `LogoutResponse` from their IdP. Your IdP must send the `LogoutResponse` in an `HTTP POST` request. Amazon Cognito then redirects them to the redirect destination from their initial sign-out request.
Your SAML provider might send a `LogoutResponse` with more than one `AuthnStatement` in it. The `sessionIndex` in the first `AuthnStatement` in a response of this type must match the `sessionIndex` in the SAML response that originally authenticated the user. If the `sessionIndex` is in any other `AuthnStatement`, Amazon Cognito won’t recognize the session and your user won’t be signed out.
------
#### [ AWS Management Console ]
**To configure SAML sign-out**
1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML IdP.
1. When you create or edit your SAML identity provider, under **Identity provider information**, check the box with the title **Add sign-out flow**.
1. From the **Social and external providers** menu of your user pool, choose your IdP and locate the **Signing certificate**.
1. Choose **Download as .crt**.
1. Configure your SAML provider to support SAML single logout and request signing, and upload the user pool signing certificate. Your IdP must redirect to `/saml2/logout` in your user pool domain.
------
#### [ API/CLI ]
**To configure SAML sign-out**
Configure single logout with the `IDPSignout` parameter of a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports SAML single logout.
```
"ProviderDetails": {
"MetadataURL" : "https://myidp.example.com/saml/metadata",
"IDPSignout" : "true",,
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
```
------
# SAML signing and encryption
Signing and encryption
SAML 2.0 sign-in is built around the user of an application as a bearer of requests and responses in their authentication flow. You might want to ensure that users aren't reading or modifying these SAML documents in transit. To accomplish this, add SAML signing and encryption to the SAML identity providers (IdPs) in your user pool. With SAML signing, your user pools adds a signature to SAML sign-in and sign-out requests. With your user pool public key, your IdP can verify that it's receiving unmodified SAML requests. Then, when your IdP responds and passes SAML assertions to users' browser sessions, the IdP can encrypt that response so that the user can't inspect their own attributes and entitlements.
With SAML signing and encryption, all cryptographic operations during user pool SAML operations must generate signatures and ciphertext with user-pool-provided keys that Amazon Cognito generates. Currently, you can't configure a user pool to sign requests or accept encrypted assertions with an external key.
**Note**
Your user pool certificates are valid for 10 years. Once per year, Amazon Cognito generates new signing and encryption certificates for your user pool. Amazon Cognito returns the most recent certificate when you request the signing certificate, and signs requests with the most recent signing certificate. Your IdP can encrypt SAML assertions with any user pool encryption certificate that isn’t expired. Your previous certificates continue to be valid for their entire duration and the public key doesn't change between certificates. As a best practice, update the certificate in your provider configuration annually.
**Topics**
+ [
## Accepting encrypted SAML responses from your IdP
](#cognito-user-pools-SAML-encryption)
+ [
## Signing SAML requests
](#cognito-user-pools-SAML-signing)
## Accepting encrypted SAML responses from your IdP
Amazon Cognito and your IdP can establish confidentiality in SAML responses when users sign in and sign out. Amazon Cognito assigns a public-private RSA key pair and a certificate to each external SAML provider that you configure in your user pool. When you enable response encryption for your user pool SAML provider, you must upload your certificate to an IdP that supports encrypted SAML responses. Your user pool connection to your SAML IdP isn’t functional before your IdP begins to encrypt all SAML assertions with the provided key.
The following is an overview of the flow of an encrypted SAML sign-in.
1. Your user starts sign-in and chooses their SAML IdP.
1. Your user pool [Authorize endpoint](authorization-endpoint.md) redirects your user to their SAML IdP with a SAML sign-in request. Your user pool can optionally accompany this request with a signature that enables integrity verification by the IdP. When you want to sign SAML requests, you must configure your IdP to accept requests that your user pool has signed with the public key in the signing certificate.
1. The SAML IdP signs in your user and generates a SAML response. The IdP encrypts the response with the public key and redirects your user to your user pool `/saml2/idpresponse` endpoint. The IdP must encrypt the response as defined by the SAML 2.0 specification. For more information, see `Element ` in [Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf).
1. Your user pool decrypts the ciphertext in the SAML response with the private key and signs in your user.
**Important**
When you enable response encryption for a SAML IdP in your user pool, your IdP must encrypt all responses with a public key that's specific to the provider. Amazon Cognito doesn't accept unencrypted SAML responses from a SAML external IdP that you configure to support encryption.
Any external SAML IdP in your user pool can support response encryption, and each IdP receives its own key pair.
------
#### [ AWS Management Console ]
**To configure SAML response encryption**
1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML IdP.
1. When you create or edit your SAML identity provider, under **Sign requests and encrypt responses**, check the box with the title **Require encrypted SAML assertions from this provider**.
1. From the **Social and external providers** menu of your user pool, select your SAML IdP and choose **View encryption certificate**.
1. Choose **Download as .crt** and provide the downloaded file to your SAML IdP. Configure your SAML IdP to encrypt SAML responses with the key in the certificate.
------
#### [ API/CLI ]
**To configure SAML response encryption**
Configure response encryption with the `EncryptedResponses` parameter of a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports request signing.
```
"ProviderDetails": {
"MetadataURL" : "https://myidp.example.com/saml/metadata",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
```
To get the encryption certificate from your user pool, make a [DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html) API request and retrieve the value of `ActiveEncryptionCertificate` in the response parameter `ProviderDetails`. Save this certificate and provide it to your IdP as the encryption certificate for sign-in requests from your user pool.
------
## Signing SAML requests
The ability to prove the integrity of SAML 2.0 requests to your IdP is a security advantage of Amazon Cognito SP-initiated SAML sign-in. Each user pool with a domain receives a user pool X.509 signing certificate. With the public key in this certificate, user pools apply a cryptographic signature to the *sign-out requests* that your user pool generates when your users select a SAML IdP. You can optionally configure your app client to sign SAML *sign-in requests*. When you sign your SAML requests, your IdP can check that the signature in the XML metadata of your requests matches the public key in the user pool certificate that you provide.
------
#### [ AWS Management Console ]
**To configure SAML request signing**
1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML IdP.
1. When you create or edit your SAML identity provider, under **Sign requests and encrypt responses**, check the box with the title **Sign SAML requests to this provider**.
1. From the **Social and external providers** menu of your user pool, choose **View signing certificate**.
1. Choose **Download as .crt** and provide the downloaded file to your SAML IdP. Configure your SAML IdP to verify the signature of incoming SAML requests.
------
#### [ API/CLI ]
**To configure SAML request signing**
Configure request signing with the `RequestSigningAlgorithm` parameter of a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports request signing.
```
"ProviderDetails": {
"MetadataURL" : "https://myidp.example.com/saml/metadata",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
```
------
# SAML identity provider names and identifiers
SAML names and identifiers
When you name your SAML identity providers (IdPs) and assign IdP identifiers, you can automate the flow of SP-initiated sign-in and sign-out requests to that provider. For information about string constraints to the provider name, see the `ProviderName` property of [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html#CognitoUserPools-CreateIdentityProvider-request-ProviderName).
![\[Authentication flow diagram of Amazon Cognito SP-initiated SAML sign-in with an IdP identifier and managed login. The user provides an email address to managed login and Amazon Cognito automatically redirects them to their provider.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-identifier.png)
You can also choose up to 50 identifiers for your SAML providers. An identifier is a friendly name for an IdP in your user pool, and must be unique within the user pool. If your SAML identifiers match your users' email domains, managed login requests each user's email address, evaluates the domain in their email address, and redirects them to the IdP that corresponds to their domain. Because the same organization can own multiple domains, a single IdP can have multiple identifiers.
Whether you use or don't use email-domain identifiers, you can use identifiers in a multi-tenant app to redirect users to the correct IdP. When you want to bypass managed login entirely, you can customize the links that you present to users such that they redirect through the [Authorize endpoint](authorization-endpoint.md) directly to their IdP. To sign in your users with an identifier and redirect to their IdP, include the identifier in the format `idp_identifier=myidp.example.com` in the request parameters of their initial authorization request.
Another method to pass a user through to your IdP is to populate the parameter `identity_provider` with the name of your IdP in the following URL format.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
identity_provider=MySAMLIdP&
client_id=1example23456789&
redirect_uri=https://www.example.com
```
After a user signs in with your SAML IdP, your IdP redirects them with a SAML response in the `HTTP POST` body to your `/saml2/idpresponse` endpoint. Amazon Cognito processes the SAML assertion and, if the claims in the response meet expectations, redirects to your app client callback URL. After your user has completed authentication in this way, they have interacted with webpages for only your IdP and your app.
With IdP identifiers in a domain format, managed login requests email addresses at sign-in and then, when the email domain matches an IdP identifier, redirects users to the sign-in page for their IdP. As an example, you build an app that requires sign-in by employees of two different companies. The first company, AnyCompany A, owns `exampleA.com` and `exampleA.co.uk`. The second company, AnyCompany B, owns `exampleB.com`. For this example, you have set up two IdPs, one for each company, as follows:
+ For IdP A, you define identifiers `exampleA.com` and `exampleA.co.uk`.
+ For IdP B, you define identifier `exampleB.com`.
In your app, invoke managed login for your app client to prompt each user to enter their email address. Amazon Cognito derives the domain from the email address, correlates the domain to an IdP with a domain identifier, and redirects your user to the correct IdP with a request to the [Authorize endpoint](authorization-endpoint.md) that contains an `idp_identifier` request parameter. For example, if a user enters `bob@exampleA.co.uk`, the next page that they interact with is the IdP sign-in page at `https://auth.exampleA.co.uk/sso/saml`.
You can also implement the same logic independently. In your app, you can build a custom form that collects user input and correlates it to the correct IdP according to your own logic. You can generate custom portals for each of your app tenants, where each links to the authorize endpoint with the tenant's identifier in the request parameters.
To collect an email address and parse the domain in managed login, assign at least one identifier to each SAML IdP that you have assigned to your app client. By default, the managed login sign-in screen displays a button for each of the IdPs that you have assigned to your app client. However, if you have successfully assigned identifiers, your classic hosted UI sign-in page looks like the following image.
![\[An Amazon Cognito managed login sign-in page displaying local user sign-in and a prompt for a federated user to enter an email address.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cup-saml-identifiers.png)
**Note**
In the classic hosted UI, the sign-in page for your app client automatically prompts for an email address when you assign identifiers to your IdPs. In the managed login experience, you must enable this behavior in the branding editor. In the **Authentication behavior** settings category, select **Domain search input** under the heading **Provider display**.
Domain parsing in managed login requires that you use domains as your IdP identifiers. If you assign an identifier of any type to each of the SAML IdPs for an app client, managed login for that app no longer displays IdP-selection buttons. Add IdP identifiers for SAML when you intend to use email parsing or custom logic to generate redirects. When you want to generate silent redirects and also want your managed login pages to display a list of IdPs, don't assign identifiers and use the `identity_provider` request parameter in your authorization requests.
+ If you assign only one SAML IdP to your app client, the managed login sign-in page displays a button to sign in with that IdP.
+ If you assign an identifier to every SAML IdP that you activate for your app client, a user input prompt for an email address appears in the managed login sign-in page.
+ If you have multiple IdPs and you do not assign an identifier to all of them, the managed login sign-in page displays a button to sign in with each assigned IdP.
+ If you assigned identifiers to your IdPs and you want your managed login pages to display a selection of IdP buttons, add a new IdP that has no identifier to your app client, or create a new app client. You can also delete an existing IdP and add it again without an identifier. If you create a new IdP, your SAML users will create new user profiles. This duplication of active users might have a billing impact in the month that you change your IdP configuration.
For more information about IdP setup, see [Configuring identity providers for your user pool](cognito-user-pools-identity-provider.md).
# Using OIDC identity providers with a user pool
OIDC providers
Users can sign in to your application using their existing accounts from OpenID Connect (OIDC) identity providers (IdPs). With OIDC providers, users of independent single sign-on systems can provide existing credentials while your application receives OIDC tokens in the shared format of user pools. To configure an OIDC IdP, set up your IdP to handle your user pool as the RP and configure your application to handle your user pool as the IdP. Amazon Cognito serves as an intermediate step between multiple OIDC IdPs and your applications. Your user pool applies attribute-mapping rules to the claims in the ID and access tokens that your provider passes directly to your user pool. Amazon Cognito then issues new tokens based on the mapped user attributes and any additional adjustments you've made to the authentication flow with [Lambda triggers](cognito-user-pools-working-with-lambda-triggers.md#lambda-triggers-for-federated-users).
Users who sign in with an OIDC IdP aren't required to provide new credentials or information to access your user pool application. Your application can silently redirect them to their IdP for sign-in, with a user pool as a tool in the background that standardizes the token format for your application. To learn more about IdP redirection, see [Authorize endpoint](authorization-endpoint.md).
Like with other third-party identity providers, you must register your application with the OIDC provider and obtain information about the IdP application that you want to connect to your user pool. A user pool OIDC IdP requires a client ID, client secret, scopes that you want to request, and information about provider service endpoints. Your user pool can discover the provider OIDC endpoints from a discovery endpoint or you can enter them manually. You must also examine provider ID tokens and create attribute mappings between the IdP and the attributes in your user pool.
![\[User pool OIDC IdP authentication flow\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/flow-cup-oidc-endpoints.png)
See [OIDC user pool IdP authentication flow](cognito-user-pools-oidc-flow.md) for more details about this authentication flow.
**Note**
Sign-in through a third party (federation) is available in Amazon Cognito user pools. This feature is independent of OIDC federation with Amazon Cognito identity pools.
You can add an OIDC IdP to your user pool in the AWS Management Console, through the AWS CLI, or with the user pool API method [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html).
**Topics**
+ [
## Prerequisites
](#cognito-user-pools-oidc-idp-prerequisites)
+ [
## Register an application with an OIDC IdP
](#cognito-user-pools-oidc-idp-step-1)
+ [
## Add an OIDC IdP to your user pool
](#cognito-user-pools-oidc-idp-step-2)
+ [
## Test your OIDC IdP configuration
](#cognito-user-pools-oidc-idp-step-3)
+ [
# OIDC user pool IdP authentication flow
](cognito-user-pools-oidc-flow.md)
## Prerequisites
Before you begin, you need the following:
+ A user pool with an app client and a user pool domain. For more information, see [Create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
+ An OIDC IdP with the following configuration:
+ Supports `client_secret_post` client authentication. Amazon Cognito doesn't check the `token_endpoint_auth_methods_supported` claim at the OIDC discovery endpoint for your IdP. Amazon Cognito doesn't support `client_secret_basic` client authentication. For more information on client authentication, see [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) in the OpenID Connect documentation.
+ Only uses HTTPS for OIDC endpoints such as `openid_configuration`, `userInfo`, and `jwks_uri`.
+ Only uses TCP ports 80 and 443 for OIDC endpoints.
+ Only signs ID tokens with HMAC-SHA, ECDSA, or RSA algorithms.
+ Publishes a key ID `kid` claim at its `jwks_uri` and includes a `kid` claim in its tokens.
+ Presents a non-expired public key with a valid root CA trust chain.
## Register an application with an OIDC IdP
Register with an OIDC IdP
Before you add an OIDC IdP to your user pool configuration and assign it to app clients, you set up an OIDC client application in your IdP. Your user pool is the relying-party application that will manage authentication with your IdP.
**To register with an OIDC IdP**
1. Create a developer account with the OIDC IdP.
**Links to OIDC IdPs**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-oidc-idp.html)
1. Register your user pool domain URL with the `/oauth2/idpresponse` endpoint with your OIDC IdP. This ensures that the OIDC IdP later accepts it from Amazon Cognito when it authenticates users.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
```
1. Select the [scopes](cognito-user-pools-define-resource-servers.md#cognito-user-pools-define-resource-servers-about-scopes) that you want your user directory to share with your user pool. The scope **openid** is required for OIDC IdPs to offer any user information. The `email` scope is needed to grant access to the `email` and `email_verified` [claims](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims). Additional scopes in the OIDC specification are `profile` for all user attributes and `phone` for `phone_number` and `phone_number_verified`.
1. The OIDC IdP provides you with a client ID and a client secret. Note these values and add them to the configuration of the OIDC IdP that you add to your user pool later.
**Example: Use Salesforce as an OIDC IdP with your user pool**
You use an OIDC IdP when you want to establish trust between an OIDC-compatible IdP such as Salesforce and your user pool.
1. [Create an account](https://developer.salesforce.com/signup) on the Salesforce Developers website.
1. [Sign in](https://developer.salesforce.com) through your developer account that you set up in the previous step.
1. From your Salesforce page, do one of the following:
+ If you’re using Lightning Experience, choose the setup gear icon, then choose **Setup Home**.
+ If you’re using Salesforce Classic and you see **Setup** in the user interface header, choose it.
+ If you’re using Salesforce Classic and you don’t see **Setup** in the header, choose your name from the top navigation bar, and choose **Setup** from the drop-down list.
1. On the left navigation bar, choose **Company Settings**.
1. On the navigation bar, choose **Domain**, enter a domain, and choose **Create**.
1. On the left navigation bar, under **Platform Tools**, choose **Apps**.
1. Choose **App Manager**.
1.
1. Choose **New connected app**.
1. Complete the required fields.
Under **Start URL**, enter a URL at the `/authorize` endpoint for the user pool domain that signs in with your Salesforce IdP. When your users access your connected app, Salesforce directs them to this URL to complete sign-in. Then Salesforce redirects the users to the callback URL that you have associated with your app client.
```
https://mydomain.auth.us-east-1.amazoncognito.com/authorize?response_type=code&client_id=&redirect_uri=https://www.example.com&identity_provider=CorpSalesforce
```
1. Enable **OAuth settings** and enter the URL of the `/oauth2/idpresponse` endpoint for your user pool domain in **Callback URL**. This is the URL where Salesforce issues the authorization code that Amazon Cognito exchanges for an OAuth token.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
```
1. Select your [scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes). You must include the scope **openid**. To grant access to the **email** and **email\$1verified** [claims](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims), add the **email** scope. Separate scopes by spaces.
1. Choose **Create**.
In Salesforce, the client ID is called a **Consumer Key**, and the client secret is a **Consumer Secret**. Note your client ID and client secret. You will use them in the next section.
## Add an OIDC IdP to your user pool
Add an OIDC IdP to your user pool
After you set up your IdP, you can configure your user pool to handle authentication requests with an OIDC IdP.
------
#### [ Amazon Cognito console ]
**Add an OIDC IdP in the console**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools** from the navigation menu.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Social and external providers** menu and then select **Add an identity provider**.
1. Choose an **OpenID Connect** IdP.
1. Enter a unique **Provider name**.
1. Enter the IdP **Client ID**. This is the ID of the application client you build in your OIDC IdP. The client ID that you provide must be an OIDC provider that you've configured with a callback url of `https://[your user pool domain]/oauth2/idpresponse`.
1. Enter the IdP **Client secret**. This must be the client secret for the same application client from the previous step.
1. Enter **Authorized scopes** for this provider. Scopes define which groups of user attributes (such as `name` and `email`) that your application will request from your provider. Scopes must be separated by spaces, following the [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-3.3) specification.
Your IdP might prompt users to consent to providing these attributes to your application when they sign in.
1. Choose an **Attribute request method**. IdPs might require that requests to their `userInfo` endpoints are formatted as either `GET` or `POST`. The Amazon Cognito `userInfo` endpoint requires `HTTP GET` requests, for example.
1. Choose a **Setup method** for the way that you want your user pool to determine the path to key OIDC-federation endpoints at your IdP. Typically, IdPs host a `/well-known/openid-configuration` endpoint at an issuer base URL. If this is the case for your provider, the **Auto fill through issuer URL** option prompts you for that base URL, attempts to access the `/well-known/openid-configuration` path from there, and reads the endpoints listed there. You might have non-typical endpoint paths or wish to pass requests to one or more endpoints through an alternate proxy. In this case, select **Manual input** and specify paths for the `authorization`, `token`, `userInfo`, and `jwks_uri` endpoints.
**Note**
The URL should start with `https://`, and shouldn't end with a slash `/`. Only port numbers 443 and 80 can be used with this URL. For example, Salesforce uses this URL:
`https://login.salesforce.com`
If you choose auto fill, the discovery document must use HTTPS for the following values: `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, and `jwks_uri`. Otherwise the login will fail.
1. Configure your attribute-mapping rules under **Map attributes between your OpenID Connect provider and your user pool**. **User pool attribute** is the *destination* attribute in the Amazon Cognito user profile and **OpenID Connect attribute** is the *source* attribute that you want Amazon Cognito to find in an ID-token claim or `userInfo` response. Amazon Cognito automatically maps the OIDC claim **sub** to `username` in the destination user profile.
For more information, see [Mapping IdP attributes to profiles and tokens](cognito-user-pools-specifying-attribute-mapping.md).
1. Choose **Add identity provider**.
1. From the **App clients** menu, select an app client from the list. Navigate to the **Login pages** tab and under **Managed login pages configuration**, select **Edit**. Locate **Identity providers** and add your new OIDC IdP.
1. Choose **Save changes**.
------
#### [ API/CLI ]
See the OIDC configuration in example two at [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html#API_CreateIdentityProvider_Example_2). You can modify this syntax and use it as the request body of `CreateIdentityProvider`, `UpdateIdentityProvider`, or the `--cli-input-json` input file for [create-identity-provider](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/create-identity-provider.html).
------
## Test your OIDC IdP configuration
Test your OIDC IdP configuration
In your application, you must invoke a browser in the user's client so that they can sign in with their OIDC provider. Test sign-in with your provider after you have completed the setup procedures in the preceding sections. The following example URL loads the sign-in page for your user pool with a prefix domain.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com
```
This link is the page that Amazon Cognito directs you to when you go to the **App clients** menu, select an app client, navigate to the **Login pages** tab, and select **View login page**. For more information about user pool domains, see [Configuring a user pool domain](cognito-user-pools-assign-domain.md). For more information about app clients, including client IDs and callback URLs, see [Application-specific settings with app clients](user-pool-settings-client-apps.md).
The following example link sets up silent redirect to the `MyOIDCIdP` provider from the [Authorize endpoint](authorization-endpoint.md) with an `identity_provider` query parameter. This URL bypasses interactive user pool sign-in with managed login and goes directly to the IdP sign-in page.
```
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?identity_provider=MyOIDCIdP&response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com
```
# OIDC user pool IdP authentication flow
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](cognito-user-pools-oidc-idp.md#cognito-user-pools-oidc-step-2-substep-9) to differ from those you authorize and request in the [app client](user-pool-settings-client-apps.md#user-pool-settings-client-apps-scopes) 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. A user accesses your managed login sign-in page, and chooses to sign in with their OIDC IdP.
1. Your application directs the user's browser to the authorization endpoint of your user pool.
1. Your user pool redirects the request to the authorization endpoint of the OIDC IdP.
1. Your IdP displays a login prompt.
1. In your application, your user's session displays a sign-in prompt for the OIDC IdP.
1. The user enters their credentials for the IdP or presents a cookie for an already-authenticated session.
1. After your user authenticates, the OIDC IdP redirects to Amazon Cognito with an authorization code.
1. Your user pool exchanges the authorization code for ID and access tokens. Amazon Cognito receives access tokens when you configure your IdP with the scopes `openid`. The claims in the ID token and the `userInfo` response are determined by additional scopes from your IdP configuration, for example `profile` and `email`.
1. Your IdP issues the requested tokens.
1. Your user pool determines the path to the IdP `jwks_uri` endpoint from the issuer URLs in your IdP configuration and requests the token signing keys from the JSON web key set (JWKS) endpoint.
1. The IdP returns signing keys from the JWKS endpoint.
1. Your user pool validates the IdP tokens from signature and expiration data in the tokens.
1. Your user pool authorizes a request to the IdP `userInfo` endpoint with the access token. The IdP responds with user data based on the access token scopes.
1. Your user pool compares the ID token and `userInfo` response from the IdP to the attribute-mapping rules in your user pool. It writes mapped IdP attributes to user pool profile attributes.
1. Amazon Cognito issues your application bearer tokens, which might include identity, access, and refresh tokens.
1. Your application processes the user pool tokens and signs the user in.
![\[User pool OIDC IdP authentication flow\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/flow-cup-oidc-endpoints.png)
**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](http://openid.net/specs/openid-connect-core-1_0.html) token for identity management, and the access token is a standard [OAuth 2.0](https://oauth.net/2/) token. For more information about grant types that your user pool app client can support, see [Authorize endpoint](authorization-endpoint.md).
## How a user pool processes claims from an OIDC provider
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.
1. 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. Amazon Cognito refreshes the signing key from the JWKS endpoint in your IdP configuration for each IdP ID token that it processes.
1. Compare the ID token signature to the signature that it expects based on provider metadata.
1. Compare the `iss` claim to the OIDC issuer configured for the IdP.
1. 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.
1. 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.
# Mapping IdP attributes to profiles and tokens
Mapping IdP attributes
Identity provider (IdP) services, including Amazon Cognito, can typically record more information about a user. You might want to know what company they work for, how to contact them, and other identifying information. But the format that these attributes take has variations between providers. For example, set up three IdPs from three different vendors with your user pool and examine an example SAML assertion, ID token, or `userInfo` payload from each. One will represent the user's email address as `email`, another as `emailaddress`, and the third as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`.
A major benefit that comes from consolidation of IdPs with a user pool is the ability to map the variety of attribute names into a single OIDC token schema with consistent, predicable, shared attribute names. This way, your developers aren't required to maintain the logic for processing a complex variety of single sign-on events. This format consolidation is attribute mapping. User pool attribute mapping assigns IdP attribute names to the corresponding user pool attribute names. For example, you can configure your user pool to write the value of an `emailaddress` claim to the standard user pool attribute `email`.
Each user pool IdP has a separate attribute-mapping schema. To specify attribute mappings for your IdP, configure a user pool identity provider in the Amazon Cognito console, an AWS SDK, or the user pools REST API .
## Things to know about mappings
Before you begin to set up user-attribute mapping, review the following important details.
+ When a federated user signs in to your application, a mapping must be present for each user pool attribute that your user pool requires. For example, if your user pool requires an `email` attribute for sign-up, map this attribute to its equivalent from the IdP.
+ By default, mapped email addresses are unverified. You can't verify a mapped email address using a one-time code. Instead, map an attribute from your IdP to get the verification status. For example, Google and most OIDC providers include the `email_verified` attribute.
+ You can map identity provider (IdP) tokens to custom attributes in your user pool. Social providers present an access token, and OIDC providers present an access and ID token. To map a token, add a custom attribute with a maximum length of 2,048 characters, grant your app client write access to the attribute, and map `access_token` or `id_token` from the IdP to the custom attribute.
+ For each mapped user pool attribute, the maximum value length of 2,048 characters must be large enough for the value that Amazon Cognito obtains from the IdP. Otherwise, Amazon Cognito reports an error when users sign in to your application. Amazon Cognito doesn't support mapping IdP tokens to custom attributes when the tokens are more than 2,048 characters long.
+ Amazon Cognito derives the `username` attribute in a federated user's profile from specific claims that your federated IdP passes, as shown in the following table. Amazon Cognito prepends this attribute value with the name of your IdP, for example `MyOIDCIdP_[sub]`. When you want your federated users to have an attribute that exactly matches an attribute in your external user directory, map that attribute to a Amazon Cognito sign-in attribute like `preferred_username`.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-specifying-attribute-mapping.html)
+ When a user pool is [case insensitive](user-pool-case-sensitivity.md), Amazon Cognito converts the username source attribute to lowercase in federated users' automatically-generated usernames. The following is an example username for a case-sensitive user pool: `MySAML_TestUser@example.com`. The following is the same username for a case-*insensitive* user pool: `MySAML_testuser@example.com`.
In case-insensitive user pools, your Lambda triggers that process the username must account for this modification to any mixed-case claims for user name source attributes. To link your IdP to a user pool that has a different case-sensitivity setting than your current user pool, create a new user pool.
+ Amazon Cognito must be able to update your mapped user pool attributes when users sign in to your application. When a user signs in through an IdP, Amazon Cognito updates the mapped attributes with the latest information from the IdP. Amazon Cognito only updates mapped attributes when their values change. To ensure that Amazon Cognito can update the attributes, check the following requirements:
+ All of the user pool custom attributes that you map from your IdP must be *mutable*. You can update mutable custom attributes at any time. By contrast, you can only set a value for a user's *immutable* custom attribute when you first create the user profile. To create a mutable custom attribute in the Amazon Cognito console, activate the **Mutable** checkbox for the attribute you add when you select **Add custom attributes** in the **Sign-up** menu. Or, if you create your user pool by using the [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API operation, you can set the `Mutable` parameter for each of these attributes to `true`. If your IdP sends a value for a mapped immutable attribute, Amazon Cognito returns an error and sign-in fails.
+ In the app client settings for your application, the mapped attributes must be *writable*. You can set which attributes are writable in the **App clients** page in the Amazon Cognito console. Or, if you create the app client by using the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) API operation, you can add these attributes to the `WriteAttributes` array. If your IdP sends a value for a mapped non-writable attribute, Amazon Cognito doesn't set the attribute value and proceeds with authentication.
+ When IdP attributes contain multiple values, Amazon Cognito flattens all values into a single comma-delimited string enclosed in the square-bracket characters `[` and `]`. Amazon Cognito URL form-encodes the values containing non-alphanumeric characters except for `.`, `-`, `*`, and `_`. You must decode and parse the individual values before you use them in your app.
+ The destination attribute retains any value that your attribute-mapping rules assign to it unless a sign-in or administrative action changes it. Amazon Cognito doesn't remove attributes from users when the source attribute is no longer sent in the provider token or SAML assertion. The following actions remove the value of an attribute from a user pool profile for a federated user:
1. The IdP sends a blank value for the source attribute and a mapping rule applies the blank value to the destination attribute.
1. You clear the value of the mapped attribute with an [DeleteUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserAttributes.html) or [AdminDeleteUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDeleteUserAttributes.html) request.
## Specifying identity provider attribute mappings for your user pool (AWS Management Console)
You can use the AWS Management Console to specify attribute mappings for the IdP your user pool.
**Note**
Amazon Cognito will map incoming claims to user pool attributes only if the claims exist in the incoming token. If a previously mapped claim no longer exists in the incoming token, it won't be deleted or changed. If your application requires mapping of deleted claims, you can use the Pre-Authentication Lambda trigger to delete the custom attribute during authentication and allow these attributes to repopulate from the incoming token.
**To specify a social IdP attribute mapping**
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit.
1. Choose the **Social and external providers** menu.
1. Choose **Add an identity provider**, or choose the **Facebook**, **Google**, **Amazon** or **Apple** IdP you have configured. Locate **Attribute mapping** and choose **Edit**.
For more information about adding a social IdP, see [Using social identity providers with a user pool](cognito-user-pools-social-idp.md).
1. For each attribute you need to map, complete the following steps:
1. Select an attribute from the **User pool attribute** column. This is the attribute that is assigned to the user profile in your user pool. Custom attributes are listed after standard attributes.
1. Select an attribute from the **** attribute** column. This will be the attribute passed from the provider directory. Known attributes from the social provider are provided in a drop-down list.
1. To map additional attributes between your IdP and Amazon Cognito, choose **Add another attribute**.
1. Choose **Save changes**.
**To specify a SAML provider attribute mapping**
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit.
1. Choose the **Social and external providers** menu.
1. Choose **Add an identity provider**, or choose the SAML IdP you have configured. Locate **Attribute mapping**, and choose **Edit**. For more information about adding a SAML IdP, see [Using SAML identity providers with a user pool](cognito-user-pools-saml-idp.md).
1. For each attribute you need to map, complete the following steps:
1. Select an attribute from the **User pool attribute** column. This is the attribute that is assigned to the user profile in your user pool. Custom attributes are listed after standard attributes.
1. Select an attribute from the **SAML attribute** column. This will be the attribute passed from the provider directory.
Your IdP might offer sample SAML assertions for reference. Some IdPs use simple names, such as `email`, while others use URL-formatted attribute names similar to:
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
1. To map additional attributes between your IdP and Amazon Cognito, choose **Add another attribute**.
1. Choose **Save changes**.
## Specifying identity provider attribute mappings for your user pool (AWS CLI and AWS API)
The following request body for [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) maps the SAML provider "MyIdP" attributes `emailaddress`, `birthdate`, and `phone` to the user pool attributes `email`, `birthdate`, and `phone_number`, in that order. This is a complete request body for a SAML 2.0 provider—your request body will vary depending on IdP type and specific details. The attribute mapping is in the `AttributeMapping` parameter.
```
{
"AttributeMapping": {
"email" : "emailaddress",
"birthdate" : "birthdate",
"phone_number" : "phone"
},
"IdpIdentifiers": [
"IdP1",
"pdxsaml"
],
"ProviderDetails": {
"IDPInit": "true",
"IDPSignout": "true",
"EncryptedResponses" : "true",
"MetadataURL": "https://auth.example.com/sso/saml/metadata",
"RequestSigningAlgorithm": "rsa-sha256"
},
"ProviderName": "MyIdP",
"ProviderType": "SAML",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
Use the following commands to specify IdP attribute mappings for your user pool.
**To specify attribute mappings at provider creation time**
+ AWS CLI: `aws cognito-idp create-identity-provider`
Example with metadata file: `aws cognito-idp create-identity-provider --user-pool-id --provider-name=SAML_provider_1 --provider-type SAML --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
Where `details.json` contains:
```
{
"MetadataFile": ""
}
```
**Note**
If the ** contains any quotations (`"`), they must be escaped (`\"`).
Example with metadata URL:
```
aws cognito-idp create-identity-provider \
--user-pool-id us-east-1_EXAMPLE \
--provider-name=SAML_provider_1 \
--provider-type SAML \
--provider-details MetadataURL=https://myidp.example.com/saml/metadata \
--attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
+ API/SDK: [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html)
**To specify attribute mappings for an existing IdP**
+ AWS CLI: `aws cognito-idp update-identity-provider`
Example: `aws cognito-idp update-identity-provider --user-pool-id --provider-name --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
+ API/SDK: [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html)
**To get information about attribute mapping for a specific IdP**
+ AWS CLI: `aws cognito-idp describe-identity-provider`
Example: `aws cognito-idp describe-identity-provider --user-pool-id --provider-name `
+ API/SDK: [DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html)
# Linking federated users to an existing user profile
Linking federated users
Often, the same user has a profile with multiple identity providers (IdPs) that you have connected to your user pool. Amazon Cognito can link each occurrence of a user to the same user profile in your directory. This way, one person who has multiple IdP users can have a consistent experience in your app. [AdminLinkProviderForUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminLinkProviderForUser.html) tells Amazon Cognito to recognize a user's unique ID in your federated directory as a user in the user pool. A user in your user pool counts as one monthly active user (MAU) for the purposes of [billing](https://aws.amazon.com/cognito/pricing/) when you have zero or more federated identities associated with the user profile.
When a federated user signs in to your user pool for the first time, Amazon Cognito looks for a local profile that you have linked to their identity. If no linked profile exists, your user pool creates a new profile. You can create a local profile and link it to your federated user at any time before their first sign-in, in an `AdminLinkProviderForUser` API request, either in a planned prestaging task or in a [Pre sign-up Lambda trigger](user-pool-lambda-pre-sign-up.md). After your user signs in and Amazon Cognito detects a linked local profile, your user pool reads your user's claims and compares them to mapping rules for the IdP. Your user pool then updates the linked local profile with the claims mapped from their sign-in. In this way, you can configure the local profile with access claims and keep their identity claims up-to-date with your provider. After Amazon Cognito matches your federated user to a linked profile, they always sign in to that profile. You can then link more of your user's provider identities to the same profile, giving one customer a consistent experience in your app. To link a federated user who has previously signed in, you must first delete their existing profile. You can identify existing profiles by their format: `[Provider name]_identifier`. For example, `LoginWithAmazon_amzn1.account.AFAEXAMPLE`. A user that you created and then linked to a third-party user identity has the username that they were created with, and an `identities` attribute that contains the details of their linked identities.
**Important**
Because `AdminLinkProviderForUser` allows a user with an external federated identity to sign in as an existing user in the user pool, it is critical that it only be used with external IdPs and provider attributes that have been trusted by the application owner.
For example, if you're a managed service provider (MSP) with an app that you share with multiple customers. Each of the customers signs in to your app through Active Directory Federation Services (ADFS). Your IT administrator, Carlos, has an account in each of your customers' domains. You want Carlos to be recognized as an app administrator every time he signs in, regardless of the IdP.
Your ADFS IdPs present Carlos' email address `msp_carlos@example.com` in the `email` claim of the Carlos' SAML assertions to Amazon Cognito. You create a user in your user pool with the user name `Carlos`. The following AWS Command Line Interface (AWS CLI) commands link Carlos' identities from IdPs ADFS1, ADFS2, and ADFS3.
**Note**
You can link a user based on specific attribute claims. This ability is unique to OIDC and SAML IdPs. For other provider types, you must link based on a fixed source attribute. For more information, see [AdminLinkProviderForUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminLinkProviderForUser.html). You must set `ProviderAttributeName` to `Cognito_Subject` when you link a social IdP to a user profile. `ProviderAttributeValue` must be the user's unique identifier with your IdP.
```
aws cognito-idp admin-link-provider-for-user \
--user-pool-id us-east-1_EXAMPLE \
--destination-user ProviderAttributeValue=Carlos,ProviderName=Cognito \
--source-user ProviderName=ADFS1,ProviderAttributeName=email,ProviderAttributeValue=msp_carlos@example.com
aws cognito-idp admin-link-provider-for-user \
--user-pool-id us-east-1_EXAMPLE \
--destination-user ProviderAttributeValue=Carlos,ProviderName=Cognito \
--source-user ProviderName=ADFS2,ProviderAttributeName=email,ProviderAttributeValue=msp_carlos@example.com
aws cognito-idp admin-link-provider-for-user \
--user-pool-id us-east-1_EXAMPLE \
--destination-user ProviderAttributeValue=Carlos,ProviderName=Cognito \
--source-user ProviderName=ADFS3,ProviderAttributeName=email,ProviderAttributeValue=msp_carlos@example.com
```
The user profile `Carlos` in your user pool now has the following `identities` attribute.
```
[{
"userId": "msp_carlos@example.com",
"providerName": "ADFS1",
"providerType": "SAML",
"issuer": "http://auth.example.com",
"primary": false,
"dateCreated": 111111111111111
}, {
"userId": "msp_carlos@example.com",
"providerName": "ADFS2",
"providerType": "SAML",
"issuer": "http://auth2.example.com",
"primary": false,
"dateCreated": 111111111111111
}, {
"userId": "msp_carlos@example.com",
"providerName": "ADFS3",
"providerType": "SAML",
"issuer": "http://auth3.example.com",
"primary": false,
"dateCreated": 111111111111111
}]
```
**Things to know about linking federated users**
+ You can link up to five federated users to each user profile.
+ You can link users to each IdP from up to five IdP attribute claims, as defined by the `ProviderAttributeName` parameter of `SourceUser` in an `AdminLinkProviderForUser` API request. For example, if you have linked at least one user to the source attributes `email`, `phone`, `department`, `given_name`, and `location`, you can only link additional users on one of those five attributes.
+ You can link federated users to either an existing federated user profile, or to a local user.
+ You can't link providers to user profiles in the AWS Management Console.
+ Your user's ID token contains all of their associated providers in the `identities` claim.
+ You can set a password for the automatically-created federated user profile in an [AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API request. That user's status then changes from `EXTERNAL_PROVIDER` to `CONFIRMED`. A user in this state can sign in as a federated user, and initiate authentication flows in the API like a linked local user. They can also modify their password and attributes in token-authenticated API requests like [ChangePassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ChangePassword.html) and [UpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserAttributes.html). As a best security practice and to keep users in sync with your external IdP, don't set passwords on federated user profiles. Instead, link users to local profiles with `AdminLinkProviderForUser`.
+ Amazon Cognito populates user attributes to a linked local user profile when the user signs in through their IdP. Amazon Cognito processes identity claims in the ID token from an OIDC IdP, and also checks the `userInfo` endpoint of both OAuth 2.0 and OIDC providers. Amazon Cognito prioritizes information in an ID token over information from `userInfo`.
When you learn that your user is no longer using an external user account that you've linked to their profile, you can disassociate that user account with your user pool user. When you linked your user, you supplied the user's attribute name, attribute value and provider name in the request. To remove a profile that your user no longer needs, make an [AdminDisableProviderForUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDisableProviderForUser.html) API request with equivalent parameters.
See [AdminLinkProviderForUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminLinkProviderForUser.html) for additional command syntax and examples in the AWS SDKs.