WorkOS Docs Homepage
Migrations

Migrate from AWS Cognito

Learn how to migrate users to WorkOS from AWS Cognito.

The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we’ll walk through the steps to export, and then import your users from AWS Cognito.

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.

User data in an AWS Cognito User Pool can be exported using the AWS CLI’s list-users command.

To retrieve the first page of results, use the command:

List users using the Cognito CLI

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

export-aws-cognito-users.sh

After obtaining your user data from Cognito, it’s time to import them into WorkOS, mapping attributes from the AWS Cognito User format to WorkOS API parameters.

Example AWS Cognito list-users response object

Using the WorkOS Create User API, you can create a corresponding record in WorkOS for each exported user. Use the following mapping from the AWS Cognito object to parameters in your WorkOS Create User API calls:

AWS CognitoWorkOS API
emailemail
emailVerifiedemail_verified
given_namefirst_name
family_namelast_name

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

It’s important to have a strategy for triggering password resets after importing your users into WorkOS. You may want to ask users to reset their password the next time they attempt to sign in, or proactively send them password reset emails.

In either case, you can trigger the password reset flow by using the WorkOS Send Password Reset Email API.

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.