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

Last updated: 2019-02-07

I want to use Active Directory Federation Services (AD FS) as Security Assertion Markup Language 2.0 (SAML 2.0) identity provider (IdP) with an Amazon Cognito user pool. How do I set all that up?

Short Description

Amazon Cognito user pools allow sign-in through a third party (federation), including through a SAML IdP such as AD FS. For more information, see Adding User Pool Sign-in Through a Third Party and Adding SAML Identity Providers to a User Pool.

You can set up an AD FS server and domain controller on an Amazon Elastic Compute Cloud (Amazon EC2) Windows instance, and then integrate your setup with your user pool using Amazon Cognito's hosted web UI.

Important: For this resolution, you need a domain name that you own. If you don't own a domain, you can register a new domain with Amazon Route 53 or another Domain Name System (DNS) service.

Resolution

Create an Amazon Cognito user pool with an app client

For more information, see Tutorial: Creating a User Pool and Adding an App Client (AWS Management Console).

Note: When creating a user pool, the standard attribute email is selected by default. For more information about user pool attributes, see Configuring User Pool Attributes.

Set up an EC2 Windows instance

Configure and launch an EC2 Windows instance, and then set up an AD FS server and domain controller on it. For more information, 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 your AD FS server as SAML IdP in Amazon Cognito

For more information, see Creating and Managing a SAML Identity Provider for a User Pool (AWS Management Console) and 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 metadata document endpoint 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 check box for the SAML IdP you configured. For example, ADFS.
    For Callback URL(s), enter a URL where you want your users to be redirected after logging in.
    For Sign out URL(s), enter a URL where you want your users to be redirected after logging out.
    Under Allowed OAuth Flows, select the Authorization code grant and Implicit Grant check boxes.
    Under Allowed OAuth Scopes, select all check boxes.
  2. Choose Save changes. For more information, see App Client Settings Overview.

Test your setup using the Amazon Cognito hosted web UI

  1. Enter this URL in your web browser:
    https://domainNamePrefix.auth.region.amazoncognito.com/login?response_type=token&client_id=appClientId&redirect_uri=https://www.example.com
    Note:
    For the URL, use values from your user pool and app client. Find the domain (including domain name prefix and AWS Region) for your user pool in the Amazon Cognito console on the App integration page. Find the app client ID in App client settings. Replace https://www.example.com with the callback URL for your SAML IdP.
  2. Choose the name of the SAML IdP that you configured. You're redirected to the AD FS authentication page.
  3. Under Sign in with your organizational account, enter the user name and password for your Active Directory user.
  4. Choose Sign in. If sign-in is successful, Amazon Cognito returns user pool tokens and a successful SAML response. For more information on viewing the SAML response, see How to View a SAML Response in Your Browser for Troubleshooting.
    Note:
    When decoded, the SAML response should include the required attribute NameID.