Integrate Azure Active Directory (AD) with AWS Cognito User Pool

Earlier I wrote about how you can integrate AWS Cognito into your React App. In this post, I am going to write down the steps that are needed to use Azure Active Directory (AD) with AWS Cognito as a Federated Identity Provider.

I am assuming you already have setup AWS Cognito User Pool (if not then read this first) and your Azure Acccount.

1. Create An Enterprise Application

From the left side, select "Enterprise applications"

Click "+ New application"

Select "Amazon Web Services (AWS)"

Select "Amazon Web Services (AWS)" again, give any name you would like, click "Create"

Once your application has been created, select "Users and groups"

Click "+ Add user"

Select user/group you want to give access to and click "Select"

After selecting users/groups, click "Assign"

ℹ️ Notes: You can’t add users/groups in your active directory from here, rather this step is to give access to your existing active directory users to the application

2. Setup Single Sign On (SSO)

From the application overview page select "2. Set up single sign on"

Select "SAML"

Select "Yes" from the popup (or "No", it really doesn't matter - we will be changing the values eventually)

Before proceeding further, we need to set up "Amazon Cognito domain". To do that, go to your AWS Cognito User Pool and from the left sidebar select "Domain name"

Enter any name you would like to use and click "Save changes" (you may want to check its availability first)

Once the domain name has been set-up. It's time to update SAML configuration from the Azure Active Directory. To do that, click "Edit" from the "Basic SAML Configuration" section

Add "Identifier (Entity ID)" and "Reply URL (Assertion Consumer Service URL)", make them default, delete the old values and click "Save"

Where:

Identifier (Entity ID): urn:amazon:cognito:sp:<user_pool_id>

Reply URL (Assertion Consumer Service URL): <domain_name_with_full_url_from_the_previous_name>

You can get the user pool id from the "General settings" tab in the AWS Cognito User Pool

Once done, download the "Federation Metadata XML" from the "SAML Signing Certificate" section

3. Add Azure Active Directory as a Federated Identity Provider

While being at the AWS Cognito User pool:

Go to "Identity providers"
Select "SAML"
Upload the XML from the previous step
Give it any name (without spaces)
Give some description as "Identifiers" (optional)
Click "Create provider"

After adding Azure Active Directory as Federated Identity Provider (using SAML), you now need to integrate that provider with your app client:

Go to "App client settings"
Check the box against your provider name (in my case AzureAD)
Enter Callback URL(s) - a comma-separated list of URLs to redirect to after login attempt (should be https except for the localhost)
Enter Sign out URL(s) - this is optional
Select "Authorization code grant" as the flow type
Select "phone, email, openid" as "Allowed OAuth Scopes"

Read more about the Authorization Flows and Scopes

4. Attribute mapping and claims

This is the most confusing but important part of the whole setup. Essentially, you need to map all the attributes that are required in your user pool with your Active Directory.
In my case the only required attribute is "email", to map it:

Select "Attribute Mapping" from the bottom left
Click "Add SAML attribute"
Enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email as "SAML attribute", select Email as "User pool attribute" and make sure the capture box is checked
Click "Save changes"

ℹ️ Notes: Technically you are just mapping the fields from Azure Active Directory with AWS Cognito User Pool's attributes. You can add as many claims as you want and use any name (and namespace) you want. To explain it better I am going to map a claim:

From the Active Directory, select "Edit" under "User Attributes & Claims" section

Click "+ Add new claim"

Give any name, enter anything you like in the namespace, select attribute (or select transformation if you want to transform some field - for example, you want to concatenate first and last name of the Azure Active Directory user) and click "Save"