How do I set up Auth0 as a SAML identity provider with an Amazon Cognito user pool?

Short description

Amazon Cognito user pools allow signing in through a third party (federation), including through a SAML IdP such as Auth0. For more information, see Adding user pool sign-in through a third party and Adding SAML identity providers to a user pool.

A user pool integrated with Auth0 allows users in your Auth0 application to get user pool tokens from Amazon Cognito. For more information, see Using tokens with user pools.

To set up Auth0 as SAML IdP, you need an Amazon Cognito user pool with an app client and domain name and an Auth0 account with an Auth0 application on it.

Resolution

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

For more information, see the following articles:

• Tutorial: Creating a user pool
  Note: When creating a user pool, the standard attribute email is selected by default. For more information about user pool attributes, see User pool attributes.
• Setting up the hosted UI with the Amazon Cognito console
  Note: When adding an app client, you can clear the Generate client secret check box. An app client secret isn't required and using an app client secret prevents the Amazon Cognito JavaScript (browser) SDK from authenticating users.
• Adding a domain name for your user pool

Sign up for an Auth0 account

Enter your email address and a password on the Auth0 Sign Up page to get started. If you already have an account, then log in.

Create an Auth0 application

1. On the Auth0 website dashboard, choose Applications, and then choose Create Application.
2. In the Create Application dialog box, enter a name for your application. For example, My App.
3. Under Choose an application type, choose Single Page Web Applications.
4. Choose Create.

Create a test user for your Auth0 application

1. On the left navigation bar, choose User Management, and then choose Users.
2. Choose Create Your First User. Or, if this isn't your first user, choose Create User.
3. In the Create user dialog box, enter an email and password for the user.
4. Choose Save.

Configure SAML settings for your application

1. On the left navigation bar, choose Applications.
2. Choose the name of the application you created.
3. On the Addons tab, turn on SAML2 Web App.
4. In the Addon: SAML2 Web App dialog box, on the Settings tab, for Application Callback URL enter: https://yourDomainPrefix.auth.region.amazoncognito.com/saml2/idpresponse.
   Note: Replace yourDomainPrefix and region with the values for your user pool. Find them in the Amazon Cognito console on the Domain name tab of the management page for your user pool.
   -or-
   Enter a custom domain callback URL similar to the following: https//yourCustomDomain/saml2/idpresponse. For more information, see Adding a custom domain to a user pool.
5. Under Settings, do the following:
   For audience, delete the comment delimiter (//) and replace the default value (urn:foo) with urn:amazon:cognito:sp:yourUserPoolId.
   Note: Replace yourUserPoolId with your Amazon Cognito user pool ID. Find the ID in the Amazon Cognito console on the General settings tab of the management page for your user pool.
   For mappings and email, delete the comment delimiters (//). Do the same for any other attributes required by your Amazon Cognito user pool. For more information, see User pool attributes.
   For nameIdentifierFormat, delete the comment delimiters ( //). Replace the default value (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) with urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
6. (Optional) Choose Debug, then log in as the test user you created to confirm that the configuration works.
7. Choose Enable, and then choose Save.

Get the IdP metadata for your Auth0 application

In the Addon: SAML2 Web App dialog box, on the Usage tab, find Identity Provider Metadata. Then, do either of the following:

• Right-click download, and then copy the URL.
• Choose download to download the .xml metadata file.

Configure Auth0 as SAML IdP in Amazon Cognito

For more information, see Creating and managing a SAML identity provider for a user pool. Follow the instructions under To configure a SAML 2.0 identity provider in your user pool.

When creating the SAML IdP, for Metadata document, either paste the Identity Provider Metadata URL or upload the .xml metadata file.

Map email address from IdP attribute to user pool attribute

For more information, see Specifying identity provider attribute mappings for your user pool and follow the instructions under To specify a SAML provider attribute mapping.

When adding a SAML attribute, for SAML Attribute, enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. For User pool attribute, choose Email from the list.

Change app client settings in Amazon Cognito

1. In the Amazon Cognito console management page for your user pool, under App integration, choose App client settings. Then do the following:
   Under Enabled identity providers, select the Auth0 and Cognito User Pool check boxes.
   For Callback URL(s), enter a URL where you want your users to be redirected after logging in. For testing, you can enter any valid URL, such as https://www.amazon.com.
   For Sign out URL(s), enter a URL where you want your users to be redirected after logging out. For testing, you can enter any valid URL, such as https://www.amazon.com.
   Under Allowed OAuth Flows, be sure to select at least the Implicit grant check box.
   Under Allowed OAuth Scopes, be sure to select at least the email and openid check boxes.
2. Choose Save changes.

For more information, see App client settings terminology.

Test the login endpoint

1. Enter this URL in your web browser: https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/login?response_type=token&client_id=<yourClientId>&redirect_uri=<redirectUrl>
   Note: Replace yourDomainPrefix and region with the values for your user pool. Find them in the Amazon Cognito console on the Domain name tab of the management page for your user pool.
   Replace yourClientId with your app client's ID, and replace redirectUrl with your app client's callback URL. Find them in the Amazon Cognito console on the App client settings tab of the management page for your user pool.
   For more information, see How do I configure the hosted web UI for Amazon Cognito? and Login endpoint.
2. Choose Auth0.
   Note: If you're redirected to your app client's callback URL, you're already logged in to your Auth0 account in your browser. The user pool tokens appear in the URL in your web browser's address bar.
3. On the login page for your Auth0 application, enter the email and password for the test user you created.
4. Choose Log in.

After you log in, you're redirected to your app client's callback URL. The user pool tokens appear in the URL in your web browser's address bar.

Related information

Integrating third-party SAML identity providers with Amazon Cognito user pools

SAML user pool IdP authentication flow

How do I set up a third-party SAML identity provider with an Amazon Cognito user pool?