Configure Automatic Migration from Your Database

Configure your Database connection to automatically migrate your users from an external user store to Auth0 with custom database action scripts.

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.

    Dashboard Authentication Database Settings Import User to Auth0

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 email address when using Identifier First + Biometrics.

  • The Management API 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, 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 Auth0 Dashboard 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.

  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);
    }

    Was this helpful?

    /

  4. Update the Get User script.

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

    Was this helpful?

    /

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