Migrate from Cognito
Overview
It is a known limitation that AWS Cognito does not include hashed passwords when listing user pool users. This necessitates a password reset flow when migrating users to another platform.
To eliminate the need for a cumbersome password reset flow, Clerk provides a Cognito password migrator that enables your end users to sign in to Clerk using their existing Cognito passwords.
In its barest form, it is simply two fields that you set on a Clerk user
object through
the Backend API.
password_hasher
:awscognito
password_digest
:awscognito#<COGNITO_USER_POOL_ID>#<COGNITO_CLIENT_ID>#<identifier>
Pre-flight checks
In AWS, you will need to ensure that your Cognito user pool has a public client with the ALLOW_USER_PASSWORD_AUTH
auth flow enabled.
You can create a new client for your user pool at any time from the AWS console or through the AWS CLI
One-time upload
For any Cognito user object that you’d wish to migrate, you will need to have an equivalent Clerk user object,
with the password_hasher
and password_digest
fields set.
Below is one method of conducting a batch upload of your Cognito users into Clerk. However, you are not limited to this approach, nor does it impact the migration flow.
Ensure that you are using node >= v20
, and run the following to create a new script directory and project.
Fill in the .env
file with your AWS and Clerk credentials.
The provided script below lists your Cognito user pool users, calls
CreateUser
for each user, and sets the password_hasher
and password_digest
fields.
Run the batch upload script.
Post-upload
Once you have users with the special hasher and digest in your Clerk instance, you will be able to validate the migration behavior.
Validate
We recommend validating the integration by taking a single user whose
Cognito password you know, such as your own, uploading it to Clerk with
the special awscognito
hasher and custom digest, and then attempting to sign in
via your Clerk instance’s managed Account Portal.
If the password is correct, sign in should work seamlessly.
Rollout changes
Up until this point, you were possibly using the Cognito hosted UI for your application’s user sign-in.
With the one-time upload out of the way and integration validated, you should be ready to
update your application to use Clerk’s managed Account Portal or the <SignIn />
component.
Your end users will now be able to sign in to Clerk using their existing passwords without any password reset required.
As users successfully sign in to Clerk, their passwords will be re-hashed, and stored securely. No plaintext passwords are ever stored.
Footnotes
-
CreateUser
has a rate limit rule of 20 requests per 10 seconds. ↩
Feedback
Last updated on