Configure your Database connection to automatically migrate your users from an external user store to Auth0 with custom database action scripts.
If you try to use more than one migration method (for example, automatic migration then bulk user import), you may encounter a DUPLICATED_USER error. This error indicates that the user exists in Auth0’s internal user store but not in your tenant. To correct this error, delete the user with the Auth0 Management API Delete a Connection User endpoint and then re-attempt the import.

​
Configure Database connection as custom

Create a Database connection, and then set it to custom.
  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.
    Auth0 Dashboard Authentication Database Connection Custom Database Settings Use Own Database Enabled
  3. Select the Settings view, toggle on Import Users to Auth0, and select Save.

​
Configure Database Action Scripts

Select the Custom Database view, and then locate Database Action Scripts.
Dashboard Authentication Database Connection Custom Database tab Database Action Scripts

​
Login

The Login script executes each time a user who is not found in the Auth0 attempts to log in. It verifies that the user exists in the external user store without reprompting the user for their password.

​
Get User

The Get User script executes after any of the following scenarios:
  • A user initiates signup attempt.
  • A user initiates a change password flow.
  • A user enters their login identifier when using Identifier First + Biometrics.
  • The Update a User’s Email or Username or Create User endpoint is called.
If a user who has not been migrated confirms a password change and logs in successfully, their user profile will be created in the Auth0 with the new password. This user profile contains all the data returned in the Get User script. All subsequent logins for this user will be performed directly in Auth0.

​
Verify user migration is complete

Verify that all users have been migrated to the Auth0 user store using the or the Auth0 Management API.
  1. Go to Auth0 Dashboard > User Management > Users, and review the list of users.
  2. Use the Management API List or Search Users endpoint.

​
Disconnect external user store

Reconfigure the Database Action Scripts as no operation functions. This will prevent Auth0 from reaching out to your external user store to authenticate users.
Make sure to leave the Import Users to Auth0 option turned on. If you turn this option off Auth0 will only use the scripts to authenticate and perform other user actions instead of using the users that were imported locally.
  1. Go to Auth0 Dashboard > Authentication > Database, and then select your Database connection.
  2. Switch to the Custom Database view, and then locate Database Action Scripts.
  3. Update the Login script. 
    function login (email, password, callback) {
  return callback(null, null);
}
  4. Update the Get User script. 
    function getByEmail (email, callback) {
  return callback(null, null);
}

​
Troubleshoot user migration issues

If you encounter any issues with automatic migration, first read Custom Database Connection and Action Script Best Practices.

​
User already exists

The most common scenarios when you may encounter this issue:
  • You delete a user from your Database connection and then try to recreate the user.
  • You attempt to create a new user on your Database connection when the user already exists in your external user store.
  • A user’s migration process was interrupted.
During the user migration process, Auth0 first creates a partial user profile in an internal user store, and then creates a full user profile on your Database connection. If an issue occurs that prevents this full user profile from being created, you may encounter the The user already exists error. You can usually resolve this issue by deleting the user from the Database connection, deleting the user from the internal user store, and then reattempting the migration process.
  1. Check the console.log() statements with the Real-time Webtask Logs extension.
  2. Delete the user with the Management API Delete a User endpoint.
  3. Delete the user with the Management API Delete a Connection User endpoint.
  4. Instruct the user to log in or change their password to reattempt migration.

​
Missing metadata

If a user is interrupted during the login or change password flow that initiates the migration process, Auth0 may not be able to transfer their metadata (user_metadata or app_metadata) along with their other profile data. You can mitigate this scenario by creating an Action that verifies the user’s profile is missing metadata, retrieves it from the external use store, and then stores it in Auth0.

​
Learn more