Cognito SAML Sign-In with Microsoft Entra ID and Amplify

Configure SAML sign-in between an Amazon Cognito user pool and Microsoft Entra ID, then use it from a Next.js application with Amplify.

Takahiro Iwasa

2023-12-17

6 min read

Amazon Cognito user pools support SAML identity providers. This example federates a user pool with Microsoft Entra ID and adds the resulting hosted UI sign-in flow to a Next.js application with AWS Amplify.

ℹ️ Note

Microsoft renamed Azure Active Directory (Azure AD) to Microsoft Entra ID in 2023. See the official page for details.

The following diagram from the official documentation shows the SAML federation flow between Cognito and an external identity provider.

Configuring the Backend

Creating the Microsoft Entra Enterprise Application

Open the Azure portal and go to Microsoft Entra ID.

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.

On the SAML setup page, copy the App Federation Metadata URL for the Cognito configuration.

Creating the Cognito User Pool

Create a CloudFormation template:

Attribute mapping (lines 33–35): Map Cognito attributes to the SAML claim names configured under Attributes & Claims in Microsoft Entra ID. The linked protocol reference lists the standard claim URIs.
- https://learn.microsoft.com/en-us/entra/identity-platform/single-sign-on-saml-protocol
OAuth scope (line 51): The aws.cognito.signin.user.admin scope allows the Amplify application to retrieve user attributes with the access token.
- 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 Microsoft 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 Microsoft Entra ID application
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:

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 the Microsoft Entra ID SAML Configuration

In the Cognito console, find the user pool ID and Cognito domain prefix.

Open the enterprise application’s SAML settings in Microsoft Entra ID.

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 Attributes & Claims to match the attribute mapping in the Cognito identity provider.

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

Create a Microsoft Entra ID user to test the integration.

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.

Review the settings and create the user.

Assigning the User to the Application

After creating the user, assign the account to the enterprise application.

Select the my-cognito-app enterprise application.

Click Assign users and groups.

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

Building the Frontend

Creating the 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 to the project directory and install AWS Amplify:

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

Creating the Environment 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 the 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 through Microsoft Entra ID, the application displays the user’s attributes.

Verify that the federated user was created in the Cognito console.

ℹ️ Note

If the user is not assigned to the enterprise application in Microsoft Entra ID, sign-in returns the following error:

Cleaning Up

Delete the stack once finished:

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

Manually delete the enterprise application and any test users in Microsoft Entra ID.

Conclusion

SAML federation between a Cognito user pool and Microsoft Entra ID allows a user to sign in to the Next.js application through the Cognito hosted UI and access mapped attributes with Amplify.

The Entity ID and Reply URL registered in Microsoft Entra ID must exactly match the Cognito user pool ID and domain prefix. The Cognito attribute mapping must also use the claim URIs sent by the enterprise application.

Creating a user does not grant access to the enterprise application. If an otherwise valid user cannot sign in, check the Microsoft Entra application assignment first.