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

Log in to the Azure Portal and select "Azure Active Directory" from the homepage

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"

Now map this newly created claim in User Pool to any attribute you want

5. Take a test drive

If you don't have any app to handle the callback, you can clone this simple express server to check the auth response (fail/success)

AWS Cognito provides you a hosted UI using which your users can log in to your app using their Azure Active Directory user account

Click "AzureAD"

It will take you to Sign in page

If successful then it will return you the authorization code, which you need to send to TOKEN endpoint and get the access token

It will also create an entry inside the "Users and group" in the Cognito User Pool

The field/attribute I mapped

Further Reading:

• OpenID Claims
• Customize AWS Cognito's hosted UI