Migrate from AWS Cognito

Learn how to migrate users to WorkOS from AWS Cognito.

Introduction

Migrate your existing user data from AWS Cognito into WorkOS using the AuthKit API. Follow these steps to export and then import your users.

AWS Cognito does not offer exports of user password hashes or MFA keys. This means that your imported users will need to reset their passwords and reconfigure any required MFA.

1. Exporting Cognito user data

Export user data from an AWS Cognito User Pool using the AWS CLI’s list-users command.

Retrieve the first page of results with the following command:

List users using the Cognito CLI

 aws cognito-idp list-users --user-pool-id <your-user-pool> --region <region>

Add the --pagination-token <next-token> argument to paginate subsequent requests:

export-aws-cognito-users.sh

 #!/bin/bash
user_pool_id="<your-user-pool-id>"
region="<your-region>"
output_dir="cognito_exports"
file_index=1

mkdir -p "$output_dir"

export_users() {
  aws cognito-idp list-users --user-pool-id "$user_pool_id" --region "$region" $1 | \
  jq '.' > "$output_dir/users_$2.json"
}

next_token=""
while true; do
  next_token=$(export_users "${next_token:+--pagination-token $next_token}" "$file_index" | jq -r '.PaginationToken // empty')
  [ -z "$next_token" ] && break
  ((file_index++))
done
echo "Export complete."

2. Importing users into WorkOS

Import your user data into WorkOS by mapping attributes from the AWS Cognito User format to WorkOS API parameters.

Example AWS Cognito list-users response object

 {
  "Users": [
    {
      "Username": "22704aa3-fc10-479a-97eb-2af5806bd327",
      "Enabled": true,
      "UserStatus": "FORCE_CHANGE_PASSWORD",
      "UserCreateDate": 1548089817.683,
      "UserLastModifiedDate": 1548089817.683,
      "Attributes": [
        {
          "Name": "sub",
          "Value": "22704aa3-fc10-479a-97eb-2af5806bd327"
        },
        {
          "Name": "family_name",
          "Value": "Mouse"
        },
        {
          "Name": "given_name",
          "Value": "Mickey"
        },
        {
          "Name": "email_verified",
          "Value": "true"
        },
        {
          "Name": "email",
          "Value": "mary@example.com"
        }
      ]
    }
  ]
}

Call the WorkOS Create User API to create a corresponding record for each exported user. Use the following mapping from the AWS Cognito object to WorkOS Create User API parameters:

AWS Cognito		WorkOS API
`email`	→	`email`
`emailVerified`	→	`email_verified`
`given_name`	→	`first_name`
`family_name`	→	`last_name`

Migrated users must reset their passwords before they can sign in.

Triggering password resets

Plan a strategy for triggering password resets after importing users into WorkOS. Ask users to reset their password at next sign-in, or proactively send password reset emails.

Trigger the password reset flow using the WorkOS Send Password Reset Email API.

Other authentication methods

In addition to migrating username and password users to WorkOS, you can migrate users who authenticate using third-party identity providers, such as Google, without re-obtaining access.

Ensure you use the same credentials (i.e. Client ID and Client Secret) in WorkOS as those used for your connection in AWS Cognito.

For OAuth providers, you will need to add WorkOS as an additional Redirect URI. See the Google OAuth integration guide as an example of what this process looks like.