How do I use a third-party IdP to configure IAM Identity Center for my Amazon Cognito user pool?

Resolution

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

Note: If you have a user pool that has an app client, then proceed to the Activate IAM Identity Center and add a user section.

Complete the following steps:

1. Create a new application.
2. Create an Amazon Cognito prefix domain in the format: https://cognitoexample.auth.region.amazoncognito.com. Or, create a custom domain. For more information, see Configuring a user pool domain.
3. (Optional) Apply branding to managed login pages.

Activate IAM Identity Center and add a user

Note: If you have a working IAM Identity Center environment, then proceed to the Configure a SAML application section.

Complete the following steps:

1. Review the IAM Identity Center prerequisites and considerations.
2. Activate IAM Identity Center. 
   Note: For the instance type, you must choose an organization instance of IAM Identity Center that you create in the AWS Organizations management account.
3. Confirm your identity source, and then create a user.

Configure a SAML application

Complete the following steps:

1. Open the IAM Identity Center console.
2. In the navigation pane, choose Applications.
3. Choose Add application, and then select I have an application I want to set up under Setup preference.
4. For Application type, select SAML 2.0, and then choose Next.
5. On the Configure application page, enter a display name and a description.
6. Note the URL of the IAM Identity Center SAML metadata file, or choose the Download hyperlink to download the file. 
7. Under Application metadata, choose Manually type your metadata values. Then, enter the following values:
   For Application Assertion Consumer Service (ACS) URL, enter https://domain-prefix.auth.region.amazoncognito.com/saml2/idpresponse.
   For Application SAML audience, enter urn:amazon:cognito:sp:userpool-id.
   Note: Replace domain-prefix with your domain prefix, region with your AWS Region, and userpool-id with your user pool ID.
8. Choose Submit.
9. On the Details page for your application, choose the Actions dropdown list.
10. Choose Edit attribute mappings, and then enter the following attributes:
    For User attribute in the application, keep the default subject.
    For Maps to this string value or user attribute in IAM Identity Center, enter ${user:subject}.
    For Format, enter Persistent.
    For User attribute in the application, enter email.
    For Maps to this string value or user attribute in IAM Identity Center, enter ${user:email}.
    For Format, enter Basic.
    Note: IAM Identity Center sends the attribute mappings to Amazon Cognito when you sign in. Make sure that you map all your user pool's required attributes. For more information about available mapping attributes, see Supported external identity provider attributes.
11. Choose Submit.
12. Under the Assigned users and groups section, choose Assign users and groups.
13. Find your user, and then choose Assign.

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

To configure a SAML IdP in your user pool, see Adding and managing SAML identity providers in a user pool. When you specify a SAML provider attribute mapping, enter a valid email in the SAML attribute field. For User pool attribute, select email.

For information about provider names and identifiers, see SAML identity provider names and identifiers.

Use the user pool app client to integrate the Identity Provider

Complete the following steps:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose User pools.
3. Under Applications, choose App clients.
4. Select an app client.
5. In the Login pages section, choose Edit.
6. In the Identity providers section, select your IdP.
7. Choose Save changes.

Test the setup

To test a service provider (SP) initiated sign-in, complete the following steps:

1. Open the Amazon Cognito console, and then choose View login page on the Login pages tab of your app client. Or, create the login endpoint URL. Use the following example naming pattern, and replace the example values with your values:
   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 Implicit grant. Then set response_type to token in your request URL.
2. On the Login pages tab, select the IAM Identity Center IdP.
   If your browser redirects you to your app client's callback URL, then you successfully logged in as a user. The user pool tokens appear 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.

When Amazon Cognito redirects you to the callback URL with a code or token, the setup is complete.

To test for Identity provider (IdP) initiated sign-in, complete the following steps:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose User pools, and then select your user pool.
3. In the navigation pane, choose Social and external provider.
4. Select your IdP, and then choose Edit in Identity provider information section.
5. In the IdP-initiated SAML sign-in section, choose Accept SP-initiated and IdP-initiated SAML assertions.
   Note: You can add other SAML providers to an app client that accepts a SAML provider with IdP-initiated sign-in. Remove other social or OpenID Connect (OIDC) providers or Cognito user pool directories from the app client.
6. Choose Save changes.
7. Open the IAM Identity Center console, and then select your SAML 2.0 application.
8. Choose the Actions dropdown, and then choose Edit configuration.
9. Under Application properties, add the following relay state value:
   identity_provider=identity-provider-name&client_id=app-client-id&redirect_uri=callback-url&response_type=token&scope=openid+email
   Note: Replace the example values with your values.
10. Choose Submit.
11. In the navigation pane, choose Settings.
12. In the Identity source section, copy the AWS access portal URL and open it in your browser.
13. Enter the user credentials, and then choose Login.
14. Select the Cognito application.

If Amazon Cognito redirects you to the callback URL with a code or token, then the setup is complete.

Related information

How federated sign-in works in Amazon Cognito user pools

Understanding user pool JSON web tokens (JWTs)