Cognito Migration Guide

Migrating your AWS Cognito users to Descope can be a smooth process with the right guidance. This guide provides detailed steps for a seamless transition.

There are two ways you migrate to Descope from Cognito. You can either do a Full Migration or a Hybrid Migration.

Full Migration - You completely move off of Cognito to Descope, no longer using your Congito user pool or pre-configured lambda triggers in any way.
Hybrid Migration - You still rely on Cognito to protect your API Gateway, AppSync, etc. but you will authenticate your users with Descope (as a federated IdP).

This documentation will cover both of these migration options. If you want to continue with the Hybrid Migration, complete the first step under Full Migration first, and then skip to the end of the document.

Full Migration

If you desire to completely move away from Cognito, the Full Migration option is the one for you. Otherwise, complete Step 1 under the Full Migration guide and then skip to the Hybrid Migration section.

Prerequisites

Ensure you have the following before starting:

Access to your AWS account with permissions to manage Cognito.
Familiarity with your current AWS Cognito setup.
Basic understanding of AWS Lambda and the boto3 SDK for the user data export.

1. Importing Users from Cognito

AWS Cognito doesn't provide a direct feature to export user data. However, you can use the Descope Migration Tool to handle much of the work for you. Migrations can differ wildly depending on the specific identity implementation required. However, this tool acts as a template for which you can edit, depending on your needs.

It contains the boto3 SDK initialization, and the basic user/groups import functionality into Descope.

This tool will perform the following actions:

Configure your Cognito User Groups as Roles in Descope
Import all of your users from the AWS User Pool defined in the environment variables of the script, including custom attributes defined in the user pool
Associate all users under specific User Groups, with the new roles created in Descope

Note

If you want to also import multiple user pools into specific Tenants, which is a common ask, you can modify the source code of the tool to handle this. Please refer to our Python SDK documentation on how to implement this.

Once you've migrated all of your users, then if you want to continue to use other AWS services, you'll need to configure AWS JWT Authorizers to work with the Descope JWT Tokens created by our SDKs.

Configure Local Environment

Clone the Repo:

git clone git@github.com:descope/descope-migration.git

Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate

Install the Necessary Python libraries

pip3 install -r requirements.txt

Setup Your Environment Variables

a. Descope project ID: Can be found here.

b. Descope Management Key: If you do not already have one stored, you can create one here.

c. Access Key ID and Secret Access Key: Obtain your Access Key ID and Secret Access Key by following the steps outlined on the AWS Guide. Both can be found after an Access key is created.
The Secret Access Key itself will be permanently hidden once first generated.

d. Cognito User Pool ID: This can be found in the AWS Cognito console.

You can change the name of the .env.example file to .env to use as a template. Then populate with the items generated above

DESCOPE_PROJECT_ID="<Your Descope Project ID>"
DESCOPE_MANAGEMENT_KEY="<Your Descope Management Key>"
AWS_ACCESS_KEY_ID="<Your AWS Access Key>"
AWS_SECRET_ACCESS_KEY="<Your AWS SECRET ACCESS KEY>"
COGNITO_USER_POOL_ID="<YOUR USER POOL ID>"

Running the Migration Script

You can use the -v or --verbose flags to enable more detailed output. This works for both live and dry runs, providing you with additional information.

Dry Run:

python3 src/main.py cognito --dry-run

The output would appear similar to the following:

=================== User Migration =============================
Cognito Users found 2
Would try to migrate 2 Users
=================== User Group Migration =============================
Cognito User Groups found 2
Would try to migrate 2 User Groups

Live Run:

python3 src/main.py cognito

The output would appear similar to the below and a log file will be generated in the form migration_log_cognito_%d_%m_%Y_%H:%M:%S.log.

=================== User Migration =============================
Cognito Users found 2
Successfully migrated 2 users
=================== User Group Migration =============================
Cognito User Groups found 2
Successfully migrated 2 groups

2. Transitioning to AWS JWT Authorizers (Optional, and only needed for Full Migration approach)

This is only necessary if you want to continue to use Descope with API Gateway. You can configure AWS JWT Authorizers as detailed in AWS JWT Authorizer with Descope KB article.

3. Using AppSync Endpoints with Descope (Optional, and only needed for Full Migration approach)

This is only necessary if you want to continue to use Descope with GraphQL endpoints and AppSync. A detailed guide on how to implement this can be found in our AppSync Authorizer KB article.

3. Testing and Finalizing Migration

Once all of these have been completed, it's a good idea to perform comprehensive testing to ensure all functionalities are working as expected, and your user migration went smoothly.

Congratulations, you've fully migrated to Descope! If you're doing the Hybrid Migration approach, you can read on to the next section of this documentation.

Hybrid Migration

The Hybrid Migration option is great if you want to retain the use of your Cognito user pool, while also using Descope as your authentication service. This is useful if you want to continue to use the Amplify SDK in your app natively or if you want to retain the ability to protect your API Gateway or AppSync endpoints with your pre-defined AWS roles/permissions.

1. Integrating Descope as an Identity Provider

Assuming you've already followed the Step 1 under Full Migration above, you should already have all of your users in Descope. After successfully importing the user data from Cognito, you can proceed with configuring Descope as an external identity provider.

To do this, follow the guide on configuring it as an external identity provider for Cognito.

2. Testing and Finalizing Migration

Once you configured Descope as an external identity provider and built your pre-auth lambda trigger, you should be able to now login like you normally would with Cognito, using Descope Flows. All of the user information, tokens in the frontend, etc. will be Cognito-based, so you won't have to worry about using JWT Authorizers or changing your backend infrastructure in any way.

Post Migration Verification

Once you have migrated your users to Descope, you can define your user's login experience. Utilizing the freshlyMigrated custom user attribute, you can define a path for your user.

You can then go down different paths from this conditional within the flow. If you'd like to verify the user's email or phone, you can, and then proceed with adding passwords (or forcing update of password if you migrated passwords) and passkeys.

Then after defining the user's experience, you will need to update the user's properties setting the freshlyMigrated attribute to false.

Was this helpful?

On this page