How do I use an Amazon Cognito user pool to integrate IAM Identity Center?

Short description

Amazon Cognito user pools allow users to sign in through third-party IdPs. You can use IAM Identity Center to federate through the Security Assertion Markup Language version 2.0 (SAML 2.0) IdP. For more information, see How federated sign-in works in Amazon Cognito user pools.

A user pool integrated with IAM Identity Center allows you to retrieve user pool tokens from Amazon Cognito. For more information, see Using tokens with user pools.

Resolution

To use an Amazon Cognito user pool to integrate IAM Identity Center, complete the followings steps.

Note: If you have a user pool that has an app client, then skip the following section.

Use an app client and domain name to create an Amazon Cognito user pool

Complete the following steps:

1. Create a user pool.
2. Add an app client and set up the hosted web UI.
3. Add a domain name for your user pool.
   Note: If you have a working IAM Identity Center environment, then skip the following section.

Activate IAM Identity Center and add a user

Complete the following steps:

1. Before you activate IAM Identity Center, review the prerequisites and considerations.
2. Activate IAM Identity Center.
3. Choose your identity source and create a user.

Configure a SAML application from the IAM Identity Center console

Complete the following steps:

1. Open the IAM Identity Center console.
2. In the navigation pane, choose Applications.
3. Choose Add application and Add custom SAML 2.0 application.
4. Choose Next.
5. On the Configure application page, enter a Display name and a Description.
6. Copy the URL of the IAM Identity Center SAML metadata file or choose the Download hyperlink. You use these resources in later steps to create an IdP in a user pool.
7. Under Application metadata, choose Manually type your metadata values. Then, provide the following values.
   Important: Make sure that you replace the domain-prefix, AWS Region, and userpool-id values with information that's specific to your environment.
   Application Assertion Consumer Service (ACS) URL: https://.auth..amazoncognito.com/saml2/idpresponse
   Application SAML audience: urn:amazon:cognito:sp:<userpool-id>
8. Choose Submit.
9. Navigate to the Details page for the application that you added.
10. Select the Actions dropdown list.
11. Choose Edit attribute mappings. Then, provide the following attributes:
    User attribute in the application: subject
    Note: subject is prefilled.
    Maps to this string value or user attribute in IAM Identity Center: ${user:subject}
    Format: Persistent User attribute in the application: email
    Maps to this string value or user attribute in IAM Identity Center: ${user:email}
    Format: Basic
    The mapped attributes are sent to Amazon Cognito when you sign in. Make sure that all your user pool's required attributes are mapped here. To learn more about attributes available for mapping, see Supported IAM Identity Center attributes.
12. Save your changes.
13. Choose Assign Users.
14. Assign your user to the application.

Configure IAM Identity Center as a SAML IdP in your user pool

Complete the following steps:

1. To configure a SAML IdP in your user pool, complete the following steps:
   Under Metadata document, provide the metadata URL or upload the file that you downloaded. For more information, see Configuring your third-party SAML identity provider.
   Enter your SAML Provider name. For more information, see SAML identity provider names and identifiers.
   (Optional) Enter SAML Identifiers.
2. To configure a SAML provider attribute mapping, complete the following steps:
   In the SAML attribute field, enter an email value that matches the user attribute value.
3. In the User pool attribute field, from the dropdown list, select Email.
   Note: Add any other attributes configured in IAM Identity Center.
4. Save your changes.

Use the user pool app client to integrate the IdP

Complete the following steps:

1. Sign in to the Amazon Cognito console.
2. Choose User Pools.
3. Select an appropriate user pool.
4. Choose the App integration.
5. Choose App client list.
6. Select the appropriate app client.
7. In the Hosted UI section, choose Edit.
8. Select the appropriate IdP.
9. Save your changes.

Test the setup

Complete the following steps:

1. To launch a hosted UI or construct the login endpoint URL, use the following naming pattern:
   https://example_domain_prefix.auth.example_region.amazoncognito.com/login?response_type=token&client_id=example_client_id&redirect_uri=example_redirect_url
   For example: https://my-user-pool.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=a1b2c3d4e5f6g7h8i9j0k1l2m3&redirect_uri=https://example.com
   For OAuth 2.0 grant types, choose Authorization code grant so the login endpoint prompts Amazon Cognito to return authorization codes when users sign in. For OAuth 2.0 grant types, choose Implicit grant for Amazon Cognito to return access tokens when users sign in. Then, replace response_type=code with response_type=token in the URL.
2. Choose IAM IdC.
   If you're redirected to your app client's callback URL, then you're logged in as a user in your browser. The user pool tokens appear directly in the URL of the web browser's address bar.
   Note: To skip this step, create an Authorize endpoint URL that has the following naming pattern:
   https://yourDomainPrefix.auth.region.amazoncognito.com/oauth2/authorize?response_type=token&identity_provider=samlProviderName&client_id=yourClientId&redirect_uri=redirectUrl&scope=allowedOauthScopes
3. Enter the user credentials, and then choose Login.
4. When you're redirected to the callback URL that includes a code or token from Amazon Cognito, the setup is complete.
   Note: Amazon Cognito supports only service provider (SP) initiated sign-ins. You must use the login endpoint or the authorize endpoint to test the setup. If the IAM Identity Center doesn't work, then use the AWS access portal to start an IdP-initiated sign.