Skip to main content

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.

Prerequisites​

Before you begin, ensure you have:

  • Auth0 account with admin access to export user data
  • Ory account and CLI installed
  • Ory project created - See creating a project for instructions
  • Required tools:
    • jq - Command-line JSON processor
    • Gzip - Compression utility
    • Ory CLI - Ory command-line interface
  • Time estimate: 1-2 hours depending on the number of users

Overview​

The migration process consists of three phases:

  1. Prepare your Auth0 data - Export user data and password hashes
  2. Configure your Ory project - Set up identity schema for email authentication
  3. Import users to Ory - Run the migration script to create users in Ory

Phase 1: Prepare your Auth0 data​

1. Create 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 can 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.

    Token expiration

    The token is valid for 24 hours by default and is configurable.

  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 export script​

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 file. The process takes some time to complete and the compressed file is downloaded automatically when it's ready.

Follow these steps to export the user data:

  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)

    This script creates AUTH0_USERDATA.json in your current directory containing all exported user data.

2. Export password hashes​

Exporting password hashes is optional but recommended. 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.

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.

note

Password hash exports are not available for Auth0's Free subscription tier. You'll need a paid Auth0 plan to request this data.

Create Auth0 support ticket​

Follow these steps to get the password hashes from Auth0. For more information, see the Auth0 documentation on exporting password hashes.

  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.

Download password hashes file​

When Auth0 processes your request, download the compressed JSON file that contains user IDs, password hashes, and related information.

The file you get has this format:

{"_ID":{"$oid":"60425dc43519d90068f82973"},"email_verified":false,"email":"test2@example.com","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":"test@example.com","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}

Phase 2: Configure your Ory project​

1. Set environment variables​

Set your project and workspace IDs as environment variables:

export ORY_PROJECT_ID='{your-project-id}'
export ORY_WORKSPACE_ID='{your-workspace-id}'
Finding your IDs

If you don't have these values, you can retrieve them:

  • Using the CLI: Run ory list projects to see all your projects and their IDs
  • Using the Console: Go to Ory Console, select your project, and find the IDs in the project settings

2. Configure identity schema​

Before importing users, you need to configure your Ory project's identity schema to match your Auth0 setup. Since Auth0 users authenticate with email and password, configure the identity schema to use the email preset.

Update your project's identity schema:

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

Phase 3: Import users to Ory​

1. Configure environment variables​

Configure the migration script by exporting 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}"
Migration Mode
  • Set RESERVE_ONLY="false" if you have password hashes
  • Set RESERVE_ONLY="true" if you don't have password hashes

2. Run import script​

Execute the migration script to import users:

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

You can inspect the script here.

Post-migration steps​

After the import script completes, follow these steps to verify and finalize the migration:

  1. Verify the migration: Check the list of users available in your project to confirm the import was successful:

    ory list identities --project $ORY_PROJECT_ID --workspace $ORY_WORKSPACE_ID

  2. Test user login: Try logging in with a few test accounts to ensure the migration was successful.

  3. Enable account recovery (if migrating without password hashes):

    • Users will need to reset their passwords on first login
    • Ensure account recovery is enabled
    • Communicate this to your users before migration

  4. Communicate with users: Inform your users about:

    • The migration timeline
    • Any actions they need to take (password reset if migrating without password hashes)
    • How to get support if they encounter issues

  5. Monitor the migration: Keep track of user login attempts and any issues that arise during the first few days after migration.