fix: correct Auth0 export users script and update documentation

wassimoo · wassimoo · commit ccb09559527f · 2025-10-27T11:18:13.000+01:00
diff --git a/code-examples/migrate-to-ory/0-get-auth0-user-data.sh b/code-examples/migrate-to-ory/0-get-auth0-user-data.sh
@@ -1,9 +1,17 @@
 #!/bin/bash
+set -euo pipefail
+
+if [ -z "${AUTH0_DOMAIN:-}" ] || [ -z "${AUTH0_TOKEN:-}" ] || [ -z "${AUTH0_CONNECTION_ID:-}" ]; then
+    echo "Error: Required environment variables not set"
+    echo "Please set: AUTH0_DOMAIN, AUTH0_TOKEN, AUTH0_CONNECTION_ID"
+    exit 1
+fi
+
 job_response=$(
     curl --request POST -s --url "https://${AUTH0_DOMAIN}/api/v2/jobs/users-exports" \
         --header "authorization: Bearer ${AUTH0_TOKEN}" \
         --header "content-type: application/json" \
-        --data '{"connection_id": "'$AUTH0_CONNECTION_ID'", "format": "json", "fields": [
+        --data '{"connection_id": "'"$AUTH0_CONNECTION_ID"'", "format": "json", "fields": [
                 {"name": "user_id"},
                 {"name": "email"},
                 {"name": "email_verified"},
@@ -31,27 +39,46 @@ job_response=$(
 
 job_id=$(echo "$job_response" | jq -r ".id")
 
+if [ -z "$job_id" ] || [ "$job_id" = "null" ]; then
+    echo "Error: Failed to create export job"
+    echo "$job_response" | jq
+    exit 1
+fi
+
+echo "Export job created with ID: $job_id"
+
 poll_job_status() {
     jobstatus=$(curl --request GET -s --url "https://${AUTH0_DOMAIN}/api/v2/jobs/${job_id}" --header "authorization: Bearer ${AUTH0_TOKEN}")
-    state=$(echo $jobstatus | jq -r ".status")
-    echo "jobstate: ${state}"
-
-    if [[ $state == "pending" ]] || [[ $state == "processing" ]]; then
-        echo "${jobstatus}" | jq ".time_left_seconds" | read timeleft
-        if [ -z $timeleft]; then
-            sleep 1
-            echo "polling job state"
+    state=$(echo "$jobstatus" | jq -r ".status")
+    echo "Job state: ${state}"
+
+    if [[ "$state" == "pending" ]] || [[ "$state" == "processing" ]]; then
+        timeleft=$(echo "$jobstatus" | jq -r ".time_left_seconds")
+        if [ "$timeleft" = "null" ] || [ -z "$timeleft" ]; then
+            sleep 5
+            echo "Polling job state..."
         else
-            sleep $timeleft
-            echo "time left: ${timeleft}s"
+            echo "Time left: ${timeleft}s"
+            sleep "$timeleft"
         fi
         poll_job_status
 
-    elif [[ $state == "completed" ]]; then
-        location=$(echo $jobstatus | jq -r ".location")
+    elif [[ "$state" == "completed" ]]; then
+        location=$(echo "$jobstatus" | jq -r ".location")
         curl "$location" --silent --output "AUTH0_USERDATA_nd.json.gz"
         gzip -d -c "AUTH0_USERDATA_nd.json.gz" | jq -s "." >"AUTH0_USERDATA.json"
-        echo "Finished downloading Auth0 user data!"
+        echo "Finished downloading Auth0 user data to AUTH0_USERDATA.json!"
+        
+    elif [[ "$state" == "failed" ]]; then
+        echo "Error: Export job failed"
+        echo "$jobstatus" | jq
+        exit 1
+        
+    else
+        echo "Unknown job state: $state"
+        echo "$jobstatus" | jq
+        exit 1
     fi
 }
-poll_job_status
+
+poll_job_status
diff --git a/docs/migrate-to-ory/auth0.mdx b/docs/migrate-to-ory/auth0.mdx
@@ -13,37 +13,105 @@ 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:
+## Prerequisites
 
-- 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
+Before you begin, ensure you have:
 
-## Export password hashes
+- **Auth0 account** with admin access to export user data
+- **Ory account** and CLI installed
+{/* TODO: change this to refer to new migration guide (docs/migrate-to-ory/migrate/create-project.mdx) */}
+- **Ory project** created - See [creating a project](index.mdx) for instructions 
+- **Required tools**:
+  - [jq](https://jqlang.org/) - Command-line JSON processor
+  - [Gzip](https://www.gnu.org/software/gzip/) - Compression utility
+  - [Ory CLI](../guides/cli/01_installation.mdx) - Ory command-line interface
+- **Time estimate**: 1-2 hours depending on the number of users
 
-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.
+## 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](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports), 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](https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/0-get-auth0-user-data.sh).
+
+#### 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](https://manage.auth0.com/#) and navigate to **Applications** → **APIs**.
+2. Select **Auth0 Management API** and go to the **API Explorer** tab. Copy the displayed token.
+
+   :::warning 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:
+
+   ```shell
+   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:
+
+   ```shell
+   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](#create-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](../kratos/manage-identities/25_import-user-accounts-identities.mdx).
 
-When you export password hashes, none of the involved parties has access to users' plain text passwords.
+:::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
+#### Create Auth0 support ticket
 
-Follow these steps to get the password hashes from Auth0:
+Follow these steps to get the password hashes from Auth0. For more information, see the
+[Auth0 documentation on exporting password hashes](https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/export-data#user-passwords).
 
 1. Go to your [Auth0 dashboard](https://manage.auth0.com/#) 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
+#### Download password hashes file
 
-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.
+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:
 
@@ -52,99 +120,98 @@ The file you get has this format:
 {"_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}
 ```
 
-## Create a bulk user export
+---
 
-To create a [bulk user export](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports), 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](https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/0-get-auth0-user-data.sh).
+## Phase 2: Configure your Ory project
 
-### Get API Access Token and connection ID
+### 1. Set environment variables
 
-Follow these steps to get the Management API Access Token and connection ID:
+Set your project and workspace IDs as environment variables:
 
-1. Go to your [Auth0 dashboard](https://manage.auth0.com/#) and navigate to **Applications** → **APIs**.
-2. Select **Auth0 Management API** and go to the **API Explorer** tab. Copy the displayed token. The token is valid for 24 hours,
-   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.
+```shell
+export ORY_PROJECT_ID='{your-project-id}'
+export ORY_WORKSPACE_ID='{your-workspace-id}'
+```
 
-### Run the script
+:::tip Finding your IDs
 
-To create a bulk user export, run the supplied script. To use it, you must install:
+If you don't have these values, you can retrieve them:
 
-- [jq](https://stedolan.github.io/jq/download/)
-- [Gzip](https://www.gnu.org/software/gzip/)
+- **Using the CLI**: Run `ory list projects` to see all your projects and their IDs
+- **Using the Console**: Go to [Ory Console](https://console.ory.sh/), select your project, and find the IDs in the project settings
 
-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:
 
-   ```shell
-   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. Configure identity schema
 
-2. Run the script:
+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.
 
-   ```shell
-   bash <(curl https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/0-get-auth0-user-data.sh)
-   ```
+Update your project's identity schema:
+
+```shell
+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"}]'
+```
 
-## 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.
+## Phase 3: Import users to Ory
 
-- 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](../kratos/self-service/flows/account-recovery-password-reset).
+### 1. Configure environment variables
 
-The procedure is performed by running a
-[custom script](https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/1-create-ory-identities.sh). To use
-it, you must install:
+Configure the migration script by exporting the necessary environment variables:
 
-- [jq](https://stedolan.github.io/jq/download/)
-- [Gzip](https://www.gnu.org/software/gzip/)
+```shell
+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}"
+```
 
-Follow these steps to import Auth0 users to Ory:
+:::info Migration Mode
 
-1. Create an Ory Network project using Ory CLI:
+- Set `RESERVE_ONLY="false"` if you have password hashes
+- Set `RESERVE_ONLY="true"` if you don't have password hashes 
+:::
 
-   ```shell
-   ory create project --name "Ory Docs Auth0 Migration Example"
-   export ORY_PROJECT_ID='{set to the project ID from output}'
-   ```
+### 2. Run import script
 
-2. Change the identity schema using Ory CLI:
+Execute the migration script to import users:
 
-   ```shell
-   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"}]'
-   ```
+```shell
+bash <(curl https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/1-create-ory-identities.sh)
+```
 
-3. Export the necessary environment variables:
+You can inspect the script
+[here](https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/1-create-ory-identities.sh).
 
-   ```shell
-   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:
+## Post-migration steps
 
-   ```shell
-   bash <(curl https://raw.githubusercontent.com/ory/docs/master/code-examples/migrate-to-ory/1-create-ory-identities.sh)
-   ```
+After the import script completes, follow these steps to verify and finalize the migration:
 
-5. Check the list of users available in your project to verify if the operation is successful:
+1. **Verify the migration**: Check the list of users available in your project to confirm the import was successful:
 
    ```shell
-   ory list identities --project <project-id> --workspace <workspace-id>
+   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](../kratos/self-service/flows/account-recovery-password-reset) 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.
