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

Resolution

Prerequisite: You must own a domain to set up an AD FS with an Amazon Cognito user pool. If you don't own a domain, then you can register a new domain with Amazon Route 53 or another DNS service.

Create an Amazon Cognito user pool with managed login

Create an Amazon Cognito user pool, and then set up managed login.

Set up an Amazon EC2 Windows instance

Complete the following steps:

1. Launch an Amazon Elastic Compute Cloud (Amazon EC2) Windows instance.
2. Set up an AD FS server and domain controller on the Amazon EC2 Windows instance.

For instructions, see How do I set up AD FS on an Amazon EC2 Windows instance to work with federation for an Amazon Cognito user pool?

Configure AD FS as a SAML IdP in Amazon Cognito

Complete the following steps:

1. Configure a SAML 2.0 IdP in your user pool. You can either paste the metadata document endpoint URL or upload the .xml metadata file.
2. Map SAML IdP attributes to the user profile in your user pool. Make sure to include all required attributes in your attribute map.

Update app client settings

Complete the following steps:

1. Open the Amazon Cognito console.
2. Under Applications, choose App clients. Then, from the list, choose the app client that the user pool setup process generated.
3. Navigate to the Login pages tab, choose Edit, and then choose the following options:
   For Callback URLs, enter a URL where you want to redirect your users after they log in.
   For Sign out URLs, enter a URL where you want to redirect your users after they log out.
   For Identity providers, choose your SAML IdP from the dropdown list.
   For OAuth 2.0 grant types, select the Authorization code grant and Implicit Grant check boxes.
   For OpenID Connect scopes, choose all OIDC scopes from the dropdown list.
   For Custom scopes, select the custom scopes that you configured.
4. Choose Save changes.

For information about app client terminology, see App client settings terms.

Test your setup

Complete the following steps:

1. Enter the following URL in your web browser: https://domainNamePrefix.auth.region.amazoncognito.com/login?response_type=token&client_id=appClientId&redirect_uri=https://www.example.com
2. Open the Amazon Cognito console.
3. In the navigation pane, choose Branding, and then choose your domain.
4. Copy the domain's URL.
   Note: Replace domainNamePrefix.auth.region.amazoncognito.com with your domain URL.
5. In the navigation pane, under Applications, choose App clients. Then, copy your app client ID.
   Note: Replace appClientId with your app client ID.
6. Select your app client, and then choose the Login pages tab.
7. Copy the callback URL that's shown on the Login pages tab.
   Note: Replace https://www.example.com with the callback URL.
8. Enter the modified URL in your browser. Amazon Cognito redirects you to the Cognito authentication page.
9. On the sign-in page, choose your SAML IdP.
10. Choose Sign in with your organizational account, and then enter the username and password for your Active Directory user.
11. Choose Sign in.

Note: When you sign in successfully, AD FS sends a SAML response to Amazon Cognito. Amazon Cognito validates the SAML response. If the SAML response is valid, then Amazon Cognito redirects you to the application page with tokens. If the SAML response is invalid, then Amazon Cognito redirects you to the application page with an error message in the URL. The SAML response must include the NameID attribute. If the SAML response doesn't include this attribute, then federation fails. For information about SAML responses, see View a SAML response in your browser.

Related information

Building ADFS Federation for your Web App using Amazon Cognito User Pools

Configuring your third-party SAML identity provider

SAML session initiation in Amazon Cognito user pools

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

Understanding user pool JSON web tokens (JWTs)