This repository includes a Python utility for migrating your Cognito users to Descope.
This tool will automatically fetch Cognito user groups and custom attributes defined in your user pool with the boto3 client SDK. Roles in Descope will be created corresponding to the name of a Cognito user group, and all users that are assigned to a specific user group, will also be created in Descope and assigned to that new role as well. Users will also have all of their custom attributes in Descope, as they currently do in Cognito.
⚠️ Note: Cognito does not support the export of hashed passwords, therefore you'll need to create temporary passwords for these users and they will have to be reset by each individual user when they sign in with Descope for the first time.
- Clone the Repo:
git clone https://github.com/descope/descope-cognito-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
You can change the name of the .env.example file to .env to use as a template.
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>"
DESCOPE_PROJECT_ID="<Your Descope Project ID>"
DESCOPE_MANAGEMENT_KEY="<Your Descope Management Key>"
a. 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 and update your .env file.
Both can be found after an Access Key is created:
Note: The Secret Access Key itself will be permanently hidden once first generated.
b. Cognito User Pool ID: This can be found in the AWS Cognito console.
c. Descope Project ID and Management Key: Obtain these from your Descope account under Project Settings and Management Keys.
⚠️ Note: Make sure that you've created all of your custom attributes manually in the Descope Console, otherwise custom attributes will not be transferred over from Cognito. The tool should ask you this question before running the migration.
To migrate your Cognito users, execute the script with the path to the password hash export file:
python3 src/main.py
The output will include the responses of the created users within Descope:
User successfully created
2023-12-04 13:10:48,735 - INFO - Found credentials in environment variables.
2023-12-04 13:10:49,766 - INFO - User gaokevin successfully created in Descope with Cognito User ID 3c50e5ad-c340-4b48-945a-3cda903c2ca1
2023-12-04 13:10:50,830 - INFO - User gaokevin successfully associated with role TestGroup
2023-12-04 13:10:50,832 - INFO - Migration process completed.
...
Unit testing can be performed by running the following command:
python3 -m unittest tests.test_migration
For any issues or suggestions, feel free to open an issue in the GitHub repository.
This project is licensed under the MIT License - see the LICENSE file for details.