Migrate from Auth0

This guide shows you how to migrate user accounts from Auth0 to Ory. The instructions in this document assume that your Auth0 setup includes a database connection and that the users whose accounts you migrate use emails and passwords as their login credentials.

If your setup is different, you can use this document as a starting point in defining your own migration procedure.

This document takes you through the following steps:

• Exporting password hashes of your Auth0 users
• Creating a bulk export that contains the complete user data
• Importing Auth0 users to Ory using a custom script

Export password hashes

Because password hashes are considered sensitive information, Auth0 doesn't export them as part of the general export process. To get the password hashes and other password-related information, you must create an Auth0 support ticket.

danger

You must be on a paid Auth0 plan to export password hashes. Auth0 makes no commitments about the processing time for this kind of request.

If you get your users' password hashes and import them to Ory, users can log in to their accounts using the same credentials they used before the migration. If you can't get users' password hashes, you can still import Auth0 user accounts to Ory and migrate them using a Password migration hook.

info

When you export password hashes, none of the involved parties has access to users' plain text passwords.

Create Auth0 support ticket

Follow these steps to get the password hashes from Auth0:

1. Go to your Auth0 dashboard and select Get Support.
2. Navigate to Tickets → View All and select Open Ticket.
3. Choose I have a question regarding my Auth0 account and pick the I would like to obtain an export of my tenant password hashes option.
4. Fill in the form and submit the ticket.

Exported password hashes

When Auth0 processes your request, you can download a compressed JSON file that contains user IDs, password hashes, and related information. To get complete user data, you must create a bulk user export.

The file you get has this format:

{"_ID":{"$oid":"60425dc43519d90068f82973"},"email_verified":false,"email":"[email protected]","passwordHash":"$2b$10$Z6hUTEEeoJXN5/AmSm/4.eZ75RYgFVriQM9LPhNEC7kbAbS/VAaJ2","password_set_date":{"$date":"2021-03-05T16:35:16.775Z"},"tenant":"dev-rwsbs6ym","connection":"Username-Password-Authentication","_tmp_is_unique":true}
{"_ID":{"$oid":"60425da93519d90068f82966"},"email_verified":false,"email":"[email protected]","passwordHash":"$2b$10$CSZ2JarG4XYbGa.JkfpqnO2wrlbfp5eb5LScHSGo9XGeZ.a.Ic54S","password_set_date":{"$date":"2021-03-05T16:34:49.502Z"},"tenant":"dev-rwsbs6ym","connection":"Username-Password-Authentication","_tmp_is_unique":true}

Create a bulk user export

To create a bulk user export, you need a Management API Access Token and the ID of your connection. This data is used by the migration script you run to get the user data. You inspect the script here.

Get API Access Token and connection ID

Follow these steps to get the Management API Access Token and connection ID:

1. Go to your Auth0 dashboard and navigate to Applications → APIs.

2. Select Auth0 Management API and go to the API Explorer tab. Copy the displayed token.

   info

   The token is valid for 24 hours. When this time passes, repeat the process to generate a new token.

3. Go to Authentication and navigate to Database.

4. Click the connection for which you want to export user data and copy its ID.

Run the script

To create a bulk user export, run the supplied script. To use it, you must install:

• jq
• Gzip

The script accounts for all possible metrics you can export in a bulk user export. The bulk user export is a compressed, newline-delimited JSON. The process takes some time to complete and the compressed file is downloaded automatically when it's ready.

Follow these steps:

1. Export the required environment variables:

   export AUTH0_DOMAIN="$your_auth0_domain.auth0.com"
   export AUTH0_CONNECTION_ID="$your_auth0_connection_id"
   export AUTH0_TOKEN="$your_auth0_management_api_token"

2. Run the script:

   bash <(curl https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/0-get-auth0-user-data.sh)

Import users to Ory

To import your Auth0 users to Ory, you must create new users in Ory and associate them with the imported data.

• If you import the Auth0 user data from the bulk user export and you have the password hashes, your users can log in with their emails and passwords.
• If you don't have password hashes from Auth0, create new users for the known email addresses and the associated data. In this case, users must create new passwords when they log in to their accounts for the first time. To facilitate this, enable account recovery.

The procedure is performed by running a custom script. To use it, you must install:

• jq
• Gzip

Follow these steps to import Auth0 users to Ory:

1. Create an Ory Network project using Ory CLI:

   ory create project --name "Ory Docs Auth0 Migration Example"
   export ORY_PROJECT_ID='{set to the project ID from output}'

2. Change the identity schema using Ory CLI:

   ory patch identity-config --project <project-id> --workspace <workspace-id> \
      --replace '/identity/default_schema_id="preset://email"' \
      --replace '/identity/schemas=[{"id":"preset://email","url":"base64://ewogICIkaWQiOiAiaHR0cHM6Ly9zY2hlbWFzLm9yeS5zaC9wcmVzZXRzL2tyYXRvcy9pZGVudGl0eS5lbWFpbC5zY2hlbWEuanNvbiIsCiAgIiRzY2hlbWEiOiAiaHR0cDovL2pzb24tc2NoZW1hLm9yZy9kcmFmdC0wNy9zY2hlbWEjIiwKICAidGl0bGUiOiAiUGVyc29uIiwKICAidHlwZSI6ICJvYmplY3QiLAogICJwcm9wZXJ0aWVzIjogewogICAgInRyYWl0cyI6IHsKICAgICAgInR5cGUiOiAib2JqZWN0IiwKICAgICAgInByb3BlcnRpZXMiOiB7CiAgICAgICAgImVtYWlsIjogewogICAgICAgICAgInR5cGUiOiAic3RyaW5nIiwKICAgICAgICAgICJmb3JtYXQiOiAiZW1haWwiLAogICAgICAgICAgInRpdGxlIjogIkUtTWFpbCIsCiAgICAgICAgICAib3J5LnNoL2tyYXRvcyI6IHsKICAgICAgICAgICAgImNyZWRlbnRpYWxzIjogewogICAgICAgICAgICAgICJwYXNzd29yZCI6IHsKICAgICAgICAgICAgICAgICJpZGVudGlmaWVyIjogdHJ1ZQogICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgIndlYmF1dGhuIjogewogICAgICAgICAgICAgICAgImlkZW50aWZpZXIiOiB0cnVlCiAgICAgICAgICAgICAgfSwKICAgICAgICAgICAgICAidG90cCI6IHsKICAgICAgICAgICAgICAgICJhY2NvdW50X25hbWUiOiB0cnVlCiAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicmVjb3ZlcnkiOiB7CiAgICAgICAgICAgICAgInZpYSI6ICJlbWFpbCIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgInZlcmlmaWNhdGlvbiI6IHsKICAgICAgICAgICAgICAidmlhIjogImVtYWlsIgogICAgICAgICAgICB9CiAgICAgICAgICB9LAogICAgICAgICAgIm1heExlbmd0aCI6IDMyMAogICAgICAgIH0KICAgICAgfSwKICAgICAgInJlcXVpcmVkIjogWwogICAgICAgICJlbWFpbCIKICAgICAgXSwKICAgICAgImFkZGl0aW9uYWxQcm9wZXJ0aWVzIjogZmFsc2UKICAgIH0KICB9Cn0K"}]'

3. Export the necessary environment variables:

   export RESERVE_ONLY="false" # Set to "true" if you DON'T HAVE Auth0 password hashes.
   export AUTH0_USERDATA="{path-to-the-json-file-with-bulk-user-export-data}"
   export AUTH0_PWEXPORT="{path-to-the-json-file-with-password-hashes}"

4. Run the script to import users:

   bash <(curl https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/1-create-ory-identities.sh)

5. Check the list of users available in your project to verify if the operation is successful:

   ory list identities --project <project-id> --workspace <workspace-id>