How to Authenticate Users with AWS Amplify, Cognito, and Azure Entra ID

Takahiro Iwasa

12/17/2023

6 min read

Cognito Entra ID Amplify

Cognito user pools provide support for SAML-based identity providers, enabling seamless integration with enterprise identity systems. In this note, we’ll walk through the process of setting up authentication using AWS Amplify, Cognito, and Azure Entra ID.

ℹ️ Note

Azure AD has been renamed to Microsoft Entra ID. For more details, visit the official page.

The authentication workflow involves integrating Cognito with Azure Entra ID via SAML. The following diagram, from the official documentation, visualizes the process.

Building Backend

Creating Azure Entra ID

Open the Azure portal and navigate to the Microsoft Entra ID section.

Select Add > Enterprise application from the menu.

Choose Create your own application and enter a name such as my-cognito-app. Select the option Integrate any other application you don't find in the gallery (Non-gallery).

Go to the Set up single sign on section and choose SAML as the method.

Once the SAML setup page appears, locate and copy the metadata URL. This will be used in the Cognito configuration.

Creating Cognito User Pool

Create a CloudFormation template:

Attribute Mapping (Lines 33-35): The URLs for attribute mapping can be found in the metadata URL retrieved from Azure Entra ID.
- https://learn.microsoft.com/en-us/entra/identity-platform/single-sign-on-saml-protocol
OAuth Scope (Line 51): The scope aws.cognito.signin.user.admin is required for querying user information from frontend applications using Amplify.
- https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html#cognito-user-pools-define-resource-servers-about-scopes

1
AWSTemplateFormatVersion: 2010-09-09
2
Description: Cognito user pool federated with Azure Entra ID
3

4
Parameters:
5
  Domain:
6
    Type: String
7
    Description: Cognito user pool domain
8
  CallbackURLs:
9
    Type: CommaDelimitedList
10
    Default: 'http://localhost:3000/'
11
  LogoutURLs:
12
    Type: CommaDelimitedList
13
    Default: 'http://localhost:3000/'
14
  MetadataURL:
15
    Type: String
16
    Description: SAML metadata url of your Azure Entra ID
17

18
Resources:
19
  CognitoUserPool:
20
    Type: AWS::Cognito::UserPool
21
    Properties:
22
      UserPoolName: cognito-federated-with-azure-entra-id
23

24
  CognitoUserPoolDomain:
25
    Type: AWS::Cognito::UserPoolDomain
26
    Properties:
27
      Domain: !Ref Domain
28
      UserPoolId: !Ref CognitoUserPool
29

30
  CognitoUserPoolIdentityProvider:
31
    Type: AWS::Cognito::UserPoolIdentityProvider
32
    Properties:
33
      AttributeMapping:
34
        email: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
35
        name: 'http://schemas.microsoft.com/identity/claims/displayname'
36
      ProviderDetails:
37
        IDPSignout: true
38
        MetadataURL: !Ref MetadataURL
39
      ProviderName: azure-entra-id
40
      ProviderType: SAML
41
      UserPoolId: !Ref CognitoUserPool
42

43
  CognitoUserPoolClient:
44
    Type: AWS::Cognito::UserPoolClient
45
    Properties:
46
      AllowedOAuthFlows:
47
        - code
48
      AllowedOAuthScopes:
49
        - email
50
        - openid
51
        - aws.cognito.signin.user.admin
52
      AllowedOAuthFlowsUserPoolClient: true
53
      CallbackURLs: !Ref CallbackURLs
54
      LogoutURLs: !Ref LogoutURLs
55
      ClientName: public client
56
      SupportedIdentityProviders:
57
        - COGNITO
58
        - !Ref CognitoUserPoolIdentityProvider
59
      UserPoolId: !Ref CognitoUserPool

Replace <SAML_METADATA_URL> with the metadata URL copied earlier and deploy the stack using the following command:

aws cloudformation deploy \
  --template-file cognito.yaml \
  --stack-name amplify-with-cognito-and-entra-id \
  --parameter-overrides Domain=$(uuidgen | tr "[:upper:]" "[:lower:]") MetadataURL='<SAML_METADATA_URL>'

Updating Entra ID SAML Configuration

Check the User pool ID and the Cognito domain prefix in the Cognito management console.

Open the SAML settings in Azure Entra ID and begin editing.

Use the following values for the SAML configuration. Refer to the official documentation for more details.

Entity ID: urn:amazon:cognito:sp:<your user pool ID>
Reply URL: https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse

Edit the Attributes and Claims to match your application requirements.

Click Add a group claim and select Groups assigned to the application.

To test the integration, create a new user in Azure Entra ID.

Click New user in the Azure portal.

Fill in the required fields (e.g., username and name).

Specify an email address for the user.

Skip the Assignments tab for now.

Finalize the process to create the user.

Assigning User to Application

Once the user is created, assign them to the application.

Select the my-cognito-app enterprise application.

Click Assign users and groups.

Select Add user/group and pick the user you created.

Building Frontend

Creating Application

This example uses Next.js. Generate the app with the following command and options:

npx create-next-app@latest
✔ What is your project named? … amplify-with-cognito-and-entra-id
✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to customize the default import alias (@/*)? … Yes
✔ What import alias would you like configured? … @/*

Change the working directory to the project root and install AWS Amplify with:

cd amplify-with-cognito-and-entra-id
npm i aws-amplify

Creating Dot Env File

Create a .env.local file in the root of your project with the following content. Replace the placeholders with your actual values:

1
NEXT_PUBLIC_USER_POOL_ID=<USER_POOL_ID>
2
NEXT_PUBLIC_USER_POOL_CLIENT_ID=<USER_POOL_CLIENT_ID>
3
NEXT_PUBLIC_USER_POOL_ID_PROVIDER=azure-entra-id
4
NEXT_PUBLIC_OAUTH_DOMAIN=<DOMAIN_PREFIX>.auth.ap-northeast-1.amazoncognito.com

Updating Main Page

Update the src/app/page.tsx file with the following content to configure authentication and display user attributes:

1
'use client'
2

3
import { useEffect, useState } from 'react';
4
import { Amplify } from 'aws-amplify';
5
import { FetchUserAttributesOutput, fetchUserAttributes, getCurrentUser, signInWithRedirect, signOut } from 'aws-amplify/auth';
6

7
Amplify.configure({
8
  Auth: {
9
    Cognito: {
10
      userPoolId: process.env.NEXT_PUBLIC_USER_POOL_ID as string,
11
      userPoolClientId: process.env.NEXT_PUBLIC_USER_POOL_CLIENT_ID as string,
12
      loginWith: {
13
        oauth: {
14
          domain: process.env.NEXT_PUBLIC_OAUTH_DOMAIN as string,
15
          scopes: [
16
            'email',
17
            'openid',
18
            'aws.cognito.signin.user.admin',
19
          ],
20
          redirectSignIn: ['http://localhost:3000/'],
21
          redirectSignOut: ['http://localhost:3000/'],
22
          responseType: 'code',
23
        },
24
      },
25
    },
26
  },
27
});
28

29
export default function Home() {
30
  const [attributes, setAttributes] = useState<FetchUserAttributesOutput>();
31

32
  useEffect(() => {
33
    (async () => {
34
      try {
35
        await getCurrentUser();
36
        const attributes = await fetchUserAttributes();
37
        setAttributes(attributes);
38
      } catch (error) {
39
        await signInWithRedirect({ provider: { custom: process.env.NEXT_PUBLIC_USER_POOL_ID_PROVIDER as string } });
40
      }
41
    })();
42
  }, []);
43

44
  return (
45
    <div className='flex flex-col gap-2 max-w-sm mx-auto my-4'>
46
      <div className='flex gap-2'>
47
        <div>Sub:</div>
48
        <div>{attributes?.sub}</div>
49
      </div>
50

51
      <div className='flex gap-2'>
52
        <div>Name:</div>
53
        <div>{attributes?.name}</div>
54
      </div>
55

56
      <div className='flex gap-2'>
57
        <div>Email:</div>
58
        <div>{attributes?.email}</div>
59
      </div>
60

61
      <button
62
        type="button"
63
        className="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 me-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800"
64
        onClick={() => signOut()}
65
      >
66
        Sign out
67
      </button>
68
    </div>
69
  );
70
}

Testing

Start the development server with:

npm run dev

Open http://localhost:3000/ in your browser. You will be redirected to a sign-in page.

After signing in, you can see the user attributes displayed in the app.

Verify that the user is created in the Cognito management console.

ℹ️ Note

If no users are assigned to the enterprise application in Azure Entra ID, you will encounter the following error:

Cleaning Up

Clean up all the AWS resources provisioned during this example with the following command:

aws cloudformation delete-stack \
  --stack-name amplify-with-cognito-and-entra-id

Manually delete the enterprise application and any created users in Azure.