How to migrate AWS Cognito user pool to another AWS account. No password change.

Introduction

AWS Cognito provides a comprehensive set of authentication, authorization, and user management features, making it a popular choice for many modern applications. When migrating AWS Cognito to a different AWS account, it’s essential to ensure a seamless transition without impacting the user experience or compromising security.

This tutorial is also published on our YouTube channel. You can follow the video tutorial below.

Prerequisites

• Aws account

• Aws account with admin access and IAM full access

• Basic understanding of AWS, AWS Cognito, lambda, Roles, and policy

Intended audience

• Engineer

Procedure

Follow these steps to use the migration Lambda function

5.1 Create a new user pool client app in the old user pool This client must have the OAuth flow ALLOW_ADMIN_USER_PASSWORD_AUTH enabled

First, log into your AWS account of the existing Cognito user pool, which we consider the source

After login, navigate to the Cognito user pool and select the user pool you wish to migrate

You will see the user pool overview. Select the ‘App integration’ menu below the image that looks like

Below, at the end, you will see the ‘App client list’ section. Click on the ‘Create app client’ menu in the top right corner

Mention the app client name as you prefer

Authentication flows section select the Allow_ADMIN_USER_PASSWORD_AUTH

In the ‘Hosted UI settings’ section, for ‘Allowed callback URLs’, we specified ‘localhost’ for testing purposes. Feel free to provide any URL you prefer. We’ll leave the other details as the default

Click on Create app

After creating the app client, please note down the client app ID and user pool ID. We will configure these in the Lambda environment later

5.2 Create a new user pool that allows triggering user migration. Ensure these clients use the OAuth flow with ‘USER_PASSWORD_AUTH’ enabled

In the destination account, create a new Cognito user pool to migrate existing users

Log in to the destination account, navigate to the Cognito service, and click on ‘Create user pool’

In the Cognito user pool sign-in options, we select both ‘username’ and ’email’. You can choose the options as per your preference, Click next

For MFA enforcement, we select ‘No MFA’. For other details, we’ll leave them as default, and then click ‘Next

Configure sign-up experience section,we’ll leave them as default, and then click ‘Next

We select the email provider option send  email with Cognito and click next

We mention the user pool ‘desapp’. You can mention it as you prefer

In the ‘Hosted authentication pages’ section, select ‘Use the Cognito hosted UI’, In the ‘Domain’ section, we mentioned the domain as ‘desdemo’

We mention the App client name ‘desapp’, You can mention it as you prefer and call back URL we provide localhost. you can provide any URL you prefer

In the ‘Advanced app client settings’, under ‘Authentication flows’, select ‘ALLOW_USER_PASSWORD_AUTH’

For other details, we’ll leave them as default, and then click ‘Next

finally, click on Create User pool

5.3 Creating the lambda function and Lambda execution role

In the destination AWS account, create a new AWS Lambda function. This function will be responsible for initiating the migration process and executing the necessary API calls to replicate the user data from the source account

Navigate to Lambda and click on ‘Create Function’

We mention the function name ‘usermigration’. In the runtime section, select ‘Node.js 16’, then click on ‘Create Function’

After creating the Lambda function, select the ‘Permissions’, then choose the role name that was created

It will take you to the Lambda execution role

You need to attach the ‘AmazonCognitoPowerUser’ policy and create an inline policy for ‘sts-assume’. You can reference the script below

Please note that the ARN will contain the Account ID of the source account. You need to replace it with your own

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": [
"arn:aws:iam::384834573830:role/crossaccountcognito"
]
}
]
}

5.4 Download the lambda source code and upload it

You can download the lambda migration source code from this link: https://github.com/Niyaz07/cognito-migration-lambda-fn

To upload it

Navigate to the lambda function we created in the previous step. Select ‘Upload from’, click the .zip file to upload it, and then save

5.5 Creating the User Migration trigger executes a Lambda function

Navigate to the newly created Cognito user pool and select the user pool name

Select the user pool properties and add a lambda trigger.

Trigger type select sign-up and sign-up option select the migrate user trigger

Select the lambda function that we created in the previous steps

Click on add lambda trigger

5.6 The cross-account role for the old user pool should allow ‘AmazonCognitoPowerUser’ actions and trust the execution role of the lambda function in the destination account

Configuring Cross-Account IAM Roles

Create an IAM role in the source account that allows the Lambda function in the destination account to assume this role. This will enable the Lambda function to access AWS Cognito resources in the source account

login into the source account of aws and navigate through the IAM, create a new role and select the AWS account, an Aws account section select another aws account provide your destination account id, permission policy select AmazonCognitoPowerUser

Specify the name we provided in previous steps in the Lambda execution role’s STS-assume policy under the resource ARN

Note: Please ensure you provide the cross-account role name we created in the STS-assume policy under the resource ARN as previously given

After creating the cross-account role, select that role

Edit the trust policy, you can reference the script below

Note: You need to replace the AWS field with your Lambda execution ARN. In this example, we provide the Lambda execution ARN which we created in the previous step

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::521503820723:role/service-role/usermigration-role-qj7yr2q6"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "externalcognito"
}
}
}
]
}

Please note down the external ID value and the role ARN of the cross-account. We will configure the Lambda environment later

5.7 Configure the environment variables in the Lambda function of the destination account

Log in to the destination account and navigate to the Lambda function that we created in the previous steps

Go to the configuration menu, select the environment variables, and provide the noted values in the environment

Note: OLD_CLIENT_ID = <your-client-id >,OLD_EXTERNAL_ID = externalcognito, OLD_ROLE_ARN = <your-role-arn> , OLD_USER_POOL_ID = <your-pool-id>

5.8 Testing and Validation

The User Migration trigger executes a Lambda function whenever a user isn’t found in the User Pool during login. so, Cognito will automatically create the user in the new User Pool

To migrate the users, we need to access the new user pool’s URL endpoint

Note: You need to provide your Cognito domain, app client ID, and callback URL of the destination Cognito user pool

kindly reference below the endpoint

https://<your domain>/oauth2/authorize?response_type=code&client_id=<your app client id>&redirect_uri=<your callback url>

Access the endpoint URL in your browser, it will take you to the sign-in page

log in with the same old user credentials of the source account cognito user

Click ‘Sign In’; it will sign in through the newly created user pool

After signing in, navigate to the newly created user pool in the destination account, where you can see the signed-in user generated in the new user pool