Migrate Users from One Connection to Another Connection

[konrad.sopala]

Last updated: Dec 10, 2024

Overview

This article provides the steps and endpoints required to migrate users from one database connection to another database connection, including the following information:

• User profile data, including email, email_verified, app_metadata, user_metadata and etc
• User password hash
• User’s assigned permissions

Applies To

• Migrating users
• Password Hash

Solution

While there is not a single endpoint that can import or export this information, the following steps provide a way to export and import them in detail.

Export

• Use the Bulk User Export feature to export this information: user profile data, including email, email_verified, app_metadata, user_metadata and etc
  • Specify which fields of the user profile to export, but please note that it is only possible to export in JSON format to export a user profile field that is an object (e.g. user_metadata) or an array (e.g. identities).
• User Password Hash: The user password hash can only be exported by Auth0 via a support ticket.
• User’s assigned permission
  • Export the user’s assigned roles via the Get Users Permission API endpoint

Import

• Combine the user profile data and the user password hash into one JSON file and import them together:
  • Bulk User Imports
  • Bulk User Import Database Schema and Examples
• User’s assigned permissions
  • Use the Assign Permissions to a User management API endpoint to import the user’s assigned permissions

Handling User IDs

• Note that if the user ID is also imported, there will be a duplicate user ID on the two different connections.
  • This can cause issues with endpoints that only take a user ID as an argument, e.g., “Get User by ID,” “Delete a User,” or “Update a User.”
  • Similarly, while two users will appear in user searches for the two connections, attempting to view the profile for either user will tend to show the original user. This can also impact profiles returned in Actions: Duplicate User IDs Resulting in Actions Returning Wrong Profile

There are a few options to handle this scenario:

1. If the user ID is not dependent on remaining the same after migration, for example, if there is no external store linked to the user ID, it would be simplest to remove the user_id from the import file. This will result in a new user ID being generated for the user on the connection targeted for import automatically, which is guaranteed to be unique for the tenant.
2. If the user ID needs to be retained, then include the user ID (removing the “auth0|” prefix) in the import file. Once the import is completed, the connection being decommissioned can be deleted, which will remove the original users, leaving only one user for a given user ID. If working with only a subset of users being migrated, then the “Delete Connection User” endpoint can be used to delete only the user due to being decommissioned, as this can be targeted at the connection level: Delete a connection user
3. Import the user ID but with a prefix denoting it as a migrated user to separate it from the original user account, like in this article: Updating Users with Duplicate user_ids