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

Short description

Amazon Cognito user pools allow for signing in through third-party IdPs. Users 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 users to get user pool tokens from Amazon Cognito. For more information, see Using tokens with user pools.

Resolution

To integrate an Amazon Cognito user pool with IAM Identity Center, take the followings steps.

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

Create an Amazon Cognito user pool with an app client and domain name

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 already have a working IAM Identity Center environment, then skip the following section.

Activate IAM Identity Center and add a user

1.    Before activating 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

1.    Open the IAM Identity Center console and then, from the navigation pane, choose Applications.

2.    Choose Add application and Add custom SAML 2.0 application, and then choose Next.

3.    On the Configure application page, enter a Display name and a Description.

4.    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.

5.    Under Application metadata, choose Manually type your metadata values. Then provide the following values.

Important: Make sure to replace the domain-prefix, region, and userpool-id values with information that's specific to your environment.

Application Assertion Consumer Service (ACS) URL: https://<domain-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
Application SAML audience: urn:amazon:cognito:sp:<userpool-id>

6.    Choose Submit. Then, go to the Details page for the application that you added.

7.    Select the Actions dropdown list and 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 signing 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.

8.    Save your changes.

9.    Choose the Assign Users button and then assign your user to the application.

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

1.    Configure a SAML IdP in your user pool. Apply the following settings:

Under Metadata document, provide the metadata URL or upload the file that you downloaded in step 4 of the previous section. For more information, see Integrating third-party SAML identity providers with Amazon Cognito user pools.

Enter your SAML Provider name. For more information, see Choosing SAML identity provider names.

(Optional) Enter any SAML Identifiers.

2.    Configure a SAML provider attribute mapping. Apply the following settings:

In the SAML attribute field, provide an email value that matches the user attribute value provided in step 7 of the previous section. In the User pool attribute field, select Email from the dropdown list.

Note: Add any other attributes configured in IAM Identity Center in step 7 of the previous section.

3.    Save your changes.

Integrate the IdP with the user pool app client

1.    Sign in to the new Amazon Cognito console.

2.    Choose User Pools and select an appropriate user pool.

3.    Choose the App integration tab and then choose App client list.

4.    Select the appropriate app client.

5.    From the Hosted UI section, choose Edit.

6.    Select the appropriate IdP.

7.    Save your changes.

Test the setup

1.    Launch a hosted UI or construct the login endpoint URL using 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 already logged in as 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 with 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 choose Login.

4.    When you're redirected to the callback URL that includes a code or token from Amazon Cognito in the browser's address bar, 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. Starting an IdP-initiated sign in with the AWS access portal for IAM Identity Center doesn't work.