Configure Automatic Migration from Your Database

After you create a database connection in the Dashboard, you enable user migration for that database and create custom scripts to determine how the migration happens.

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.

1. Go to Auth0 Dashboard > Authentication > Database and select the database to view.

2. Select the Custom Database view, and toggle on Use my own database.

   

3. Select the Settings view, toggle on Import Users to Auth0, and select Save.

   

Select the Custom Database view, and locate Database Action Scripts.

• Login: Executes each time a user who is not found in the Auth0 database attempts to log in. Verifies that the user exists in the legacy database without re-prompting the user for their password.

• Get User: Executes following any of these actions:

  • A user attempts to sign up

  • A user clicks on valid password change confirmation link

  • The Management API receives a call to the Update a User's Email or Username or Create User endpoint.

If a user who has not been migrated 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 for this user will be performed directly in Auth0. You may see unexpected behavior if you return differing user profiles in the Login and Get User scripts.

After you've enabled migration, you can verify the users that have migrated by doing one or both of the following tasks:

1. Use the Management API List or Search Users endpoint.

2. Go to Auth0 Dashboard > User Management > Users, and review the list of users.

Once all your users are in the Auth0 database, you are ready to convert the database connection so that it uses only users stored in Auth0:

1. Go to Auth0 Dashboard > Authentication > Database, and select the database to view.

2. Select the Custom Database view, and locate Database Action Scripts.

3. Update the Login script:

   function login (email, password, callback) {
     return callback(null, null);
   }

   Was this helpful?

   Yes /No

4. Update the Get User script:

   function getByEmail (email, callback) {
     return callback(null, null);
   }

   Was this helpful?

   Yes /No

By doing this, you are changing the Login and Get User Database Action Scripts to no operation (no-op) functions, which makes your database connection behave like a non-custom database connection.

After you have verified that the migration is complete, you can disconnect your legacy database (not the Auth0 database). If you modified the scripts to no-op functions as instructed above, Auth0 will not try to connect to your legacy database.

1. Keep Import Users to Auth0 (in the Settings view) enabled.

2. Configure rules to execute other functions when a user authenticates to your application.

The most common error message that you may encounter when importing users from a legacy database to an Auth0 custom database is "The user already exists."

When a user is imported, a partial user state is first created on the Auth0 end to make this migration possible. If you delete this user from the Auth0 connection then later recreate the user, you may receive this error. In addition, the Get User script is called on user creation. If you attempt to create a new user in the Auth0 custom database connection and the user already exists in your external database, you will receive this error.

First, check the console.log() statements with the Real-time Webtask Logs extension.

If you are unable to create a user in either your legacy database or Auth0:

• Find the user in your legacy database and delete accordingly. If the partial user state is in Auth0, use the Auth0 Management API Delete a User or Delete a Connection User endpoint.

• Confirm that Import Mode is disabled, then configure the Create Action Script.

If you are unable to delete a user:

• If Import Mode is enabled on legacy database, use the Management API Delete a User or Delete a Connection User endpoint. Confirm that the user does not exist in your legacy database, then recreate the user.

• If Import Mode is not enabled, configure the Delete Action Script. Confirm that the user does not exist in your legacy database, then recreate the user.

• Bulk User Imports
• User Import / Export Extension