Cognito Migration Guide

You can migrate from AWS Cognito to Descope in two main ways:

• Full Migration (export users and import into Descope)
• JIT Migration (provision users on sign-in).

You can also use SSO migration for seamless migration of your SSO connections.

AWS Cognito and Descope Terminology

The table below shows how authentication and authorization concepts in AWS Cognito map to Descope.

AWS Cognito organizes users into user pools.

Enterprise IdPs (SAML/OIDC) are external identity providers in that pool. User groups provide basic authorization; advanced authorization requires custom Lambda functions or custom attributes.

If you use Descope Tenants or Descope Roles, you are introducing those models yourself — there is nothing in Cognito to map 1:1 unless you used custom attributes or external systems.

You will have to decide how to translate your setup (e.g. one Descope tenant per Cognito user pool, Cognito groups mapped to Descope roles, etc).

Full Migration

In a full migration you move your users and identity data to Descope and eventually run only on Descope.

After importing users into Descope, you have two options. You can either transition users to passwordless authentication methods (magic link, OTP, passkeys), or require users to reset their password on first sign-in (e.g. using a freshlyMigrated flag to trigger a password-reset step in your flow).

If preserving the existing password experience is critical, consider JIT migration instead.

Getting the Existing User Data

The recommended approach is to use the Descope Migration Tool — either out of the box or modified for your needs. The tool imports users and custom attributes from your Cognito User Pool and, if you use Cognito User Groups, automatically converts them to Descope roles and assigns users to those roles.

For full control over the migration process, you can instead export users from the Cognito API with the boto3 client and build your own import pipeline.

Using the Descope Migration Tool

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:

1. Configure your Cognito User Groups as Roles in Descope (if you use groups, they are converted automatically).
2. 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.
3. Associate all users under specific User Groups with the new roles created in Descope.

Configure Local Environment

1. Clone the Repo:

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

2. Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate

3. Install the Necessary Python libraries

pip3 install -r requirements.txt

4. 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.

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

Exporting Users from the Cognito API

If you would like to have complete control over the migration process, you can export users from the Cognito API yourself.

It's recommended to use the AWS SDK for Python (boto3) or other AWS SDKs to list and export users.

Prerequisites

• Access to your AWS account with permissions to read users from Cognito User Pools.
• An IAM user or role with the cognito-idp:ListUsers permission (or AmazonCognitoPowerUser managed policy).
• Your Descope project ID and a Descope Management Key.
• The Cognito User Pool ID (found in the Cognito console).

Step 1: Set Up AWS SDK

Install the AWS SDK for Python (boto3):

pip install boto3

Configure your AWS credentials. You can either:

• Use the AWS CLI to configure credentials: aws configure
• Set environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
• Use IAM roles if running on EC2, Lambda, or ECS

Step 2: Export Users from Cognito

Use the list_users method to retrieve all users from your Cognito User Pool. This method supports pagination, so you'll need to handle the PaginationToken to retrieve all users.

import boto3
import json
 
# Initialize Cognito client
cognito = boto3.client('cognito-idp', region_name='us-east-1')  # Replace with your region
user_pool_id = 'us-east-1_XXXXXXXXX'  # Replace with your User Pool ID
 
users = []
pagination_token = None
 
# Paginate through all users
while True:
    if pagination_token:
        response = cognito.list_users(
            UserPoolId=user_pool_id,
            PaginationToken=pagination_token,
            Limit=60  # Max 60 per page
        )
    else:
        response = cognito.list_users(
            UserPoolId=user_pool_id,
            Limit=60
        )
 
    users.extend(response['Users'])
 
    # Check if there are more pages
    if 'PaginationToken' in response:
        pagination_token = response['PaginationToken']
    else:
        break
 
print(f"Total users retrieved: {len(users)}")

Key details about this API:

• Pagination: The list_users API returns up to 60 users per page. Use the PaginationToken from the response to retrieve the next page. Continue until no PaginationToken is returned.
• Rate limiting: AWS Cognito enforces request quotas. The ListUsers API has a default limit of 5 requests per second. If you exceed this, you'll receive a TooManyRequestsException. Implement exponential backoff and retry logic.
• User attributes: Each user has an Attributes array containing objects with Name and Value. Standard attributes include email, phone_number, name, etc. Custom attributes are prefixed with custom:.
• User status: The UserStatus field indicates the user's state (CONFIRMED, UNCONFIRMED, FORCE_CHANGE_PASSWORD, etc.).

Example response (abbreviated):

{
  "Users": [
    {
      "Username": "a1b2c3d4-...",
      "Attributes": [
        {"Name": "sub", "Value": "a1b2c3d4-..."},
        {"Name": "email", "Value": "jane@example.com"},
        {"Name": "email_verified", "Value": "true"},
        {"Name": "name", "Value": "Jane Doe"},
        {"Name": "custom:department", "Value": "Engineering"}
      ],
      "UserCreateDate": "2024-01-15T10:30:00Z",
      "UserLastModifiedDate": "2024-03-01T14:20:00Z",
      "Enabled": true,
      "UserStatus": "CONFIRMED"
    }
  ],
  "PaginationToken": "..."
}

Step 3: Export User Groups (Optional)

If you use Cognito User Groups and want to map them to Descope Roles, export the groups and their memberships:

# List all groups in the user pool
groups_response = cognito.list_groups(UserPoolId=user_pool_id)
groups = groups_response['Groups']
 
# For each user, get their group memberships
for user in users:
    username = user['Username']
    user_groups_response = cognito.admin_list_groups_for_user(
        Username=username,
        UserPoolId=user_pool_id
    )
    user['Groups'] = [g['GroupName'] for g in user_groups_response['Groups']]

Step 4: Map Cognito Attributes to Descope

For each user, map the exported attributes:

• Cognito Username or email attribute → Descope loginIds (required; unique per user).
• Cognito name attribute → Descope name.
• Cognito given_name → Descope givenName.
• Cognito family_name → Descope familyName.
• Cognito email → Descope email.
• Cognito phone_number → Descope phone.
• Cognito email_verified → Descope verifiedEmail.
• Cognito phone_number_verified → Descope verifiedPhone.
• Custom attributes (custom:*) → Descope custom attributes (create the corresponding custom attribute definitions in Descope first).
• Cognito User Groups → Descope roleNames (map group names to Descope role names).

Build a JSON array in the format expected by Descope (see user format guide).

Example mapping code:

def map_cognito_user_to_descope(cognito_user):
    """Map Cognito user to Descope format"""
    # Helper to get attribute value
    def get_attr(name):
        for attr in cognito_user.get('Attributes', []):
            if attr['Name'] == name:
                return attr['Value']
        return None
 
    email = get_attr('email')
    phone = get_attr('phone_number')
 
    descope_user = {
        "loginIds": [email] if email else [cognito_user['Username']],
        "email": email,
        "phone": phone,
        "name": get_attr('name'),
        "givenName": get_attr('given_name'),
        "familyName": get_attr('family_name'),
        "verifiedEmail": get_attr('email_verified') == 'true',
        "verifiedPhone": get_attr('phone_number_verified') == 'true',
        "customAttributes": {},
        "roleNames": cognito_user.get('Groups', [])
    }
 
    # Map custom attributes
    for attr in cognito_user.get('Attributes', []):
        if attr['Name'].startswith('custom:'):
            attr_name = attr['Name'].replace('custom:', '')
            descope_user['customAttributes'][attr_name] = attr['Value']
 
    # Add migration flag
    descope_user['customAttributes']['freshlyMigrated'] = True
 
    return descope_user
 
# Map all users
descope_users = [map_cognito_user_to_descope(u) for u in users]

Step 5: Import Users into Descope

Use the Descope Management API to import users:

• Single user: Create User — POST /v1/mgmt/user/create
• Batch: Batch Create Users — POST /v1/mgmt/user/create/batch (see rate limits here)

Example batch import code:

import requests
 
DESCOPE_PROJECT_ID = 'your-project-id'
DESCOPE_MANAGEMENT_KEY = 'your-management-key'
 
def import_users_to_descope(users):
    """Import users to Descope using batch API"""
    url = 'https://api.descope.com/v1/mgmt/user/create/batch'
    headers = {
        'Authorization': f'Bearer {DESCOPE_PROJECT_ID}:{DESCOPE_MANAGEMENT_KEY}',
        'Content-Type': 'application/json'
    }
 
    # Batch in groups of 100 (API limit)
    batch_size = 100
    for i in range(0, len(users), batch_size):
        batch = users[i:i + batch_size]
        response = requests.post(url, json={'users': batch}, headers=headers)
 
        if response.status_code == 200:
            print(f"Successfully imported batch {i//batch_size + 1}")
        else:
            print(f"Error importing batch: {response.text}")
 
import_users_to_descope(descope_users)

When importing, you'll need to make sure all loginId values you import are unique per user.

Optionally set a custom attribute freshlyMigrated to true for post-migration flows (see Post-Migration Verification). You can also set verifiedEmail and verifiedPhone to true if these were already verified in Cognito, so users are not asked to re-verify.

Once the users are imported, you can verify them in the Descope Users list and test sign-in with a few migrated users.

JIT Migration

With Just-In-Time (JIT) migration, you do not bulk-export users. Users are provisioned in Descope when they sign in. This approach lets you migrate users gradually without downtime and without needing to coordinate a bulk import.

AWS Cognito does not expose user password hashes, so your JIT architecture depends on whether you want to preserve the password sign-in experience or transition to passwordless. The two main approaches are described below.

Using Cognito USER_PASSWORD_AUTH with a Generic HTTP Connector

Use this approach if you want to keep passwords working while ensuring that all traffic flows through Descope. Descope collects the username and password, a Generic HTTP Connector calls Cognito's InitiateAuth API with the USER_PASSWORD_AUTH flow to verify the credentials, and on success the flow provisions (or updates) the user in Descope.

1. Configure your Cognito User Pool and App Client

In Cognito, make sure your User Pool and App Client are configured for the username/password flow:

• User pool attributes (User Pool):
  • UsernameAttributes: include email (or phone_number) so users can sign in with that identifier.
  • AutoVerifiedAttributes: include email so Cognito automatically sends verification emails.
  • VerificationMessageTemplate / EmailConfiguration: configure how Cognito sends verification emails (for example, DefaultEmailOption: CONFIRM_WITH_LINK and EmailSendingAccount: COGNITO_DEFAULT).
• App client settings (User Pool Client):
  • SupportedIdentityProviders: include COGNITO.
  • ExplicitAuthFlows: include at least ALLOW_USER_PASSWORD_AUTH and ALLOW_REFRESH_TOKEN_AUTH.
  • Remove OAuth-only settings you no longer need (resource server, OAuth scopes, and GenerateSecret if you are not using client credentials).

With this configuration, Cognito can accept username/password credentials via the USER_PASSWORD_AUTH flow.

2. Configure a Generic HTTP Connector to call Cognito

Create a Generic HTTP Connector in Descope to call the Cognito InitiateAuth API:

• Base URL: https://cognito-idp.<region>.amazonaws.com (for example, https://cognito-idp.us-east-1.amazonaws.com).
• Headers:
  • Content-Type: application/x-amz-json-1.1
  • X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
• Method: POST
• Body (template):

{
  "ClientId": "<COGNITO_APP_CLIENT_ID>",
  "AuthFlow": "USER_PASSWORD_AUTH",
  "AuthParameters": {
    "USERNAME": "{{form.email}}",
    "PASSWORD": "{{form.password}}"
  }
}

You can parameterize ClientId or the region with connector variables or environment-specific configuration if needed.

3. Build the JIT flow in Descope

In your Descope Flow:

1. Check if the user already exists in Descope
   • At the start of the flow, use a Condition on user.loginIds (or an equivalent indicator) to see if the user is already known to Descope.
   • If user.loginIds is not empty (user already exists), you can route them through a normal Sign In / Password or passwordless path in Descope and skip Cognito entirely.
2. Collect credentials for new / unknown users
   • If user.loginIds is empty (new to Descope), show a Screen that collects email and password (for example, form.email and form.password).
   • After the screen, call the Cognito InitiateAuth endpoint via the Generic HTTP Connector configured above to verify the password against Cognito.
3. Branch on Cognito result
   • On success (for example, HTTP 200 with an AuthenticationResult), treat this as either:
     • An existing Cognito user with a correct password, or
     • A brand-new Descope user you are onboarding.
       In both cases, use the Sign Up / Password action in Descope to create the user (or idempotently ensure they exist) with the provided email and password, mapping any needed attributes and roles. Subsequent sign-ins can then go directly through Descope without calling Cognito again.
   • On failure (Cognito returns an error or non-200), route the user to a Reset Password / Passwordless path:
     • For example, send a magic link or OTP, or force a password reset in Descope before allowing access.
4. Complete the flow
   • After successful Sign Up / Password or passwordless recovery, continue the flow as a normal Descope sign-in (issue a Descope session token, set any freshlyMigrated flags, etc.).

Over time, as users sign in via Descope and are provisioned with a Descope password (or passwordless method), you can gradually stop calling Cognito for those users.

Example Cognito API response:

Using Cognito as a Custom OIDC Provider

Use this approach if you are transitioning to passwordless authentication or are okay with requiring users to reset their password on first sign-in.

You configure your AWS Cognito User Pool as a custom OAuth provider in Descope, so users authenticate through the standard Cognito sign-in experience (including Hosted UI) and are provisioned in Descope automatically on first sign-in.

How it works:

1. Configure Cognito in Descope - In Descope, add AWS Cognito as a custom OIDC provider.
   • Use your Cognito User Pool domain (e.g. https://your-domain.auth.us-east-1.amazoncognito.com)
   • Set the app client ID and secret from your Cognito User Pool
   • Configure the OIDC endpoints (Cognito follows standard OIDC discovery at https://your-domain.auth.region.amazoncognito.com/.well-known/openid-configuration)
2. Add OIDC sign-in to your flow - In your Descope flow, add a Sign Up or In / OAuth step that redirects users to AWS Cognito. They will then sign in through Cognito as usual (including MFA, if enabled).
3. User is provisioned in Descope - After Cognito authenticates the user, it returns an ID token with claims (email, name, custom attributes). Descope provisions the user and maps those claims to Descope user attributes, then issues a Descope session token.

Once a user has been provisioned in Descope, subsequent sign-ins can go directly through Descope, controlled via a condition in your flow.

SSO Migration

If your AWS Cognito setup includes SSO (SAML/OIDC) for organizations or partners, you can migrate those configurations to Descope without forcing admins to re-configure their IdPs.

Descope can consume the existing IdP response and complete authentication so end users keep a seamless experience. For the full process—implementing SSO with Descope, setting up tenants, DNS redirect, and testing—see SSO Migration.

AWS Service Integration

If you use other AWS services that rely on Cognito tokens (API Gateway, AppSync, Lambda authorizers), you'll need to configure them to accept Descope tokens after migration.

Transitioning to AWS JWT Authorizers

This is 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.

Using AppSync Endpoints with Descope

This is 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.

Session Validation Strategy

Whether you do a full migration or a JIT migration, plan for a period where both your backend and any API Gateway layer (for example, AWS API Gateway with a Cognito authorizer) may need to accept Descope and Cognito tokens at the same time.

Your backend (and, if applicable, your API Gateway authorizer) should support both token types during the transition:

• Validate Descope session tokens (JWTs) for users who have already migrated or signed in via Descope.
• Validate AWS Cognito tokens for users who still have active Cognito sessions.

Inspect the token (e.g. issuer or kid in the JWT header) to determine the provider, then validate accordingly. This lets you roll out the migration gradually.

For the implementation pattern, see the docs on backend session validation here.

Example dual validation logic (Python):

import jwt
import requests
 
COGNITO_REGION = 'us-east-1'
COGNITO_USER_POOL_ID = 'us-east-1_XXXXXXXXX'
DESCOPE_PROJECT_ID = 'your-project-id'
 
def validate_token(token):
    """Validate token from either Cognito or Descope"""
    # Decode header to check issuer
    header = jwt.get_unverified_header(token)
    decoded = jwt.decode(token, options={"verify_signature": False})
    issuer = decoded.get('iss', '')
 
    if 'amazoncognito.com' in issuer:
        # Validate Cognito token
        return validate_cognito_token(token)
    elif 'descope.com' in issuer:
        # Validate Descope token
        return validate_descope_token(token)
    else:
        raise ValueError('Unknown token issuer')
 
def validate_cognito_token(token):
    """Validate Cognito JWT"""
    # Get Cognito JWKS
    jwks_url = f'https://cognito-idp.{COGNITO_REGION}.amazonaws.com/{COGNITO_USER_POOL_ID}/.well-known/jwks.json'
    jwks = requests.get(jwks_url).json()
 
    # Validate token (simplified - use a library like python-jose in production)
    # ... validation logic ...
    return True
 
def validate_descope_token(token):
    """Validate Descope JWT"""
    # Use Descope SDK or validate manually
    # ... validation logic ...
    return True