Migrate Users to Auth0

Auth0 supports automatic migration of users from a Custom Database Connection to Auth0. By activating this feature, your users are moved to Auth0 the first time they log in after you set up the integration. Your users are not asked to reset their password as a result of the migration.

Notice

Only Enterprise subscription plans include the user migration feature.

Only Developer Pro and Enterprise subscription plans include the ability to connect to an existing store or database via JavaScript running on Auth0's servers for every authentication request.

Click here to learn more about Auth0 pricing plans.

You can read more about database connections and the the options for using several user stores at Database Identity Providers.

The Migration Process

When a user authenticates via a custom database connection marked for import to Auth0, the following process takes place:

Auth0 authenticates migrated users against the Auth0 database. If the user has not been migrated, Auth0 executes your custom login script and, upon successfully log in, adds the user to the Auth0 database. Subsequent logins results in the user's credentials retrieved from Auth0, not your custom database.

New users are automatically added to the Auth0 database..

NOTE: Auth0 can only assist users in the Auth0 database with password reset.

Enable Automatic Migration

1. Create a Custom Database

You can create a new database connection in the Connections > Database section of the Dashboard.

On the Custom Database page, enable the Use my own database option:

2. Turn on Automatic Migration

On the Settings page for your database, enable the Import Users to Auth0 option:

3. Configure the Database Action Scripts

On the Custom Database page, under Database Action Scripts, you will see the Login and GetUser scripts you need to configure.

These custom scripts are Node.js code that run in the tenant's sandbox. Auth0 provides templates for most common databases, such as: ASP.NET Membership Provider, MongoDB, MySQL, PostgreSQL, SQLServer, Windows Azure SQL Database, and for a web service accessed by Basic Auth. For more information on implementing these scripts, see Authenticate Users with Username and Password using a Custom Database.

The Login script executes each time a user that is not found in Auth0 database attempts to log in. It verifies that the user exists in the legacy database without prompting the user for their password again.

The Get User script executes following any of these actions:

Passwords for Un-Migrated Users

If an un-migrated user confirms a password change, their user profile will be created in Auth0 with the new password. This user profile will contain all the information returned in the Get User script. All subsequent logins of this user will be performed in Auth0 directly.

You may see unexpected behavior if you return differing user profiles in the login and get_user scripts.

4. Complete the Migration

After you've enabled migration, you can verify the users that have migrated by:

Once all your users are in the Auth0 database, you are ready to turn off the import users feature and convert the database to Auth0.

  1. Go to your custom database connection on the Dashboard.

  2. Update the Login Database Action Script to the following:

function login (email, password, callback) {
  return callback(null, null);
}
  1. Update the Get User Database Action Script to the following:
function getByEmail (email, callback) {
  return callback(null, null);
}

By doing this, you are changing the Login and Get User Database Action Scripts to NO-OP functions.

At this point, you can disconnect your legacy database (not the Auth0 database). Your rules will then force users to use the new database workflow.