fix: correct Auth0 export users script and update documentation #2330

wassimoo · 2025-10-27T10:34:38Z

Changes

Script Fixes (`0-get-auth0-user-data.sh`)

Added error handling and validation for environment variables.
Fixed connection_id string interpolation bug.
Improved polling logic with proper error states handling.
Better user feedback with clear success/error messages.

Documentation Improvements (`auth0.mdx`)

Restructured content into three clear phases:
- Prepare Auth0 data.
- Configure Ory project.
- Import users to Ory.
Added prerequisites section with all requirements upfront.
Added tip box for finding project/workspace IDs.
Clarified file outputs: script creates AUTH0_USERDATA.json automatically.
Enhanced post-migration section with verification and testing steps.

Impact

Prevents silent script failures with proper error handling
Makes migration guide easier to follow with logical phase structure

Checklist

I have read the contributing guidelines and signed the CLA.
I have referenced an issue containing the design document if my change introduces a new feature.
I have read the security policy.
I confirm that this pull request does not address a security vulnerability.
If this pull request addresses a security vulnerability,
I confirm that I got approval (please contact [email protected]) from the maintainers to push the changes.
I have added tests that prove my fix is effective or that my feature works.
I have added the necessary documentation within the code base (if appropriate).

CLAassistant · 2025-10-27T10:34:45Z

All committers have signed the CLA.

vinckr

Nice!
looks pretty good already, I would do a test of the script and left some comments on style.

I think the numbered list here don't add anything and in general would be better without.
there are 2 steps only anyway so its not that hard to navigate and just looks confusing in the ToC (see screenshot below).

So please remove the Phase X parts and numbered list in headings.

also in line with the style guide: "Avoid using symbols and special characters in headings."

docs/migrate-to-ory/auth0.mdx

unatasha8 · 2025-10-29T22:53:41Z

docs/migrate-to-ory/auth0.mdx

+   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.


Suggested change

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

This script creates `AUTH0_USERDATA.json` in your current directory and contains all the exported user data.

unatasha8 · 2025-11-08T03:18:14Z

docs/migrate-to-ory/auth0.mdx

+- **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


You should link to here for create project: docs/migrate-to-ory/migrate/create-project

unatasha8 · 2025-11-08T06:41:35Z

docs/migrate-to-ory/auth0.mdx

+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


Suggested change

If you get your users' password hashes and import them to Ory, users can log in to their accounts using the same credentials they

- 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. For more information, see [Bulk identity migration](../migrate-to-ory/migrate/migrate-strategies#bulk-identity-migration).

unatasha8 · 2025-11-08T06:45:09Z

docs/migrate-to-ory/auth0.mdx

+[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


Suggested change

used before the migration. If you can't get users' password hashes, you can still import Auth0 user accounts to Ory and migrate

- 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). For more information, see [Graceful identity migration](../migrate-to-ory/migrate/migrate-strategies#graceful-identity-migration).

unatasha8 · 2025-11-08T06:46:08Z

docs/migrate-to-ory/auth0.mdx


 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).


Suggested change

them using a [Password migration hook](../kratos/manage-identities/25_import-user-accounts-identities.mdx).

… reference

unatasha8 · 2025-11-13T19:31:04Z

docs/migrate-to-ory/auth0.mdx


-## Export password hashes
+- Auth0 account with admin access to export user data
+- Ory account and CLI installed


Suggested change

- Ory account and CLI installed

- Ory account with an Ory project already created - See [creating a project](docs/migrate-to-ory/migrate/create-project.mdx) for instructions

We repeat the Ory CLI tool below in the Required tools section.

unatasha8 · 2025-11-13T19:46:08Z

docs/migrate-to-ory/auth0.mdx

+### 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


Suggested change

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

Access Token and the ID of your connection. You will need this information to export the Auth0 user data, when you run the migration export script.

unatasha8 · 2025-11-13T19:47:11Z

docs/migrate-to-ory/auth0.mdx

+
+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


Suggested change

inspect the script

You can inspect the export script

unatasha8 · 2025-11-13T19:50:56Z

docs/migrate-to-ory/auth0.mdx

+
+### 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


Suggested change

To create a [bulk user export](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports), you need a Management API

To create a [bulk user export](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports), you need the Management API

unatasha8 · 2025-11-13T20:16:12Z

docs/migrate-to-ory/auth0.mdx

 ## 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.
+### Configure environment variables


Suggested change

### Configure environment variables

### Set environment variables

Changed to keep it consistent with previous section

unatasha8 · 2025-11-13T22:20:29Z

docs/migrate-to-ory/auth0.mdx

- 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).
+Configure the migration script by exporting the necessary environment variables:


Suggested change

Configure the migration script by exporting the necessary environment variables:

Set necessary environment variables for the import script:

Changed to keep it consistent with previous section

unatasha8 · 2025-11-13T22:29:07Z

docs/migrate-to-ory/auth0.mdx

+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


Suggested change

#### Run export script

### Run export script

Increasing the heading level to match "Run import script" later

unatasha8 · 2025-11-13T22:46:00Z

docs/migrate-to-ory/auth0.mdx

+- Auth0 account with admin access to export user data
+- Ory account and CLI installed
+- Ory project created - See [creating a project](docs/migrate-to-ory/migrate/create-project.mdx) for instructions
+- Required tools:


Add a bullet for the migration scripts. For example: "Export
and import migration scripts."

unatasha8 · 2025-11-13T22:49:22Z

docs/migrate-to-ory/auth0.mdx

-When you export password hashes, none of the involved parties has access to users' plain text passwords.
+1. [Prepare your Auth0 data](#prepare-your-auth0-data): Export user data and password hashes
+2. [Configure your Ory project](#configure-your-ory-project): Set up identity schema for email authentication
+3. [Import users to Ory](#import-users-to-ory): Run the migration script to create users in Ory


Suggested change

3. [Import users to Ory](#import-users-to-ory): Run the migration script to create users in Ory

3. [Import users to Ory](#import-users-to-ory): Run the migration import script to create users in Ory

unatasha8 · 2025-11-13T22:52:31Z

docs/migrate-to-ory/auth0.mdx

+
+#### 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,


Suggested change

The script accounts for all possible metrics you can export in a bulk user export. The bulk user export is a compressed,

The export script accounts for all possible metrics you can export in a bulk user export. The bulk user export is a compressed,

unatasha8 · 2025-11-13T22:53:00Z

docs/migrate-to-ory/auth0.mdx

+   export AUTH0_TOKEN="your_auth0_management_api_token"
+   ```
+
+2. Run the script:


Suggested change

2. Run the script:

2. Run the export script:

unatasha8 · 2025-11-13T22:53:53Z

docs/migrate-to-ory/auth0.mdx

+   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 and contains all the exported user data.


Suggested change

This script creates `AUTH0_USERDATA.json` in your current directory and contains all the exported user data.

This export script creates `AUTH0_USERDATA.json` in your current directory and contains all the exported user data.

wassimoo requested review from aeneasr, piotrmsc, vinckr and zepatrik as code owners October 27, 2025 10:34

github-actions bot added the Needs Triage label Oct 27, 2025

ory-bot assigned wassimoo Oct 27, 2025

vercel bot deployed to Preview October 27, 2025 10:44 View deployment

wassimoo requested a review from unatasha8 October 27, 2025 15:04

github-actions bot removed the Needs Triage label Oct 28, 2025

vinckr requested changes Oct 28, 2025

View reviewed changes

docs/migrate-to-ory/auth0.mdx Outdated Show resolved Hide resolved

docs/migrate-to-ory/auth0.mdx Outdated Show resolved Hide resolved

docs/migrate-to-ory/auth0.mdx Outdated Show resolved Hide resolved

unatasha8 requested changes Nov 8, 2025

View reviewed changes

vercel bot had a problem deploying to Preview November 12, 2025 14:36 Failure

vercel bot had a problem deploying to Preview November 13, 2025 00:18 Failure

wassimoo added 5 commits November 13, 2025 14:25

fix: correct Auth0 export users script and update documentation

bed1c35

docs: auth0 migration guid formatting improvements

889d08c

docs: improve formatting in auth0 migration to follow our style guide.

9a39281

docs: update Auth0 migration guide to correct project link

8044ebe

docs: refine Auth0 migration guide formatting and update project link…

fb8ed63

… reference

wassimoo force-pushed the wassimoo/fix-auth0-migration-and-update-docs branch from e223ec6 to fb8ed63 Compare November 13, 2025 14:10

vercel bot deployed to Preview November 13, 2025 14:13 View deployment

unatasha8 reviewed Nov 13, 2025

View reviewed changes

	This script creates `AUTH0_USERDATA.json` in your current directory containing all exported user data.
	This script creates `AUTH0_USERDATA.json` in your current directory and contains all the exported user data.

	If you get your users' password hashes and import them to Ory, users can log in to their accounts using the same credentials they
	- 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. For more information, see [Bulk identity migration](../migrate-to-ory/migrate/migrate-strategies#bulk-identity-migration).

	used before the migration. If you can't get users' password hashes, you can still import Auth0 user accounts to Ory and migrate
	- 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). For more information, see [Graceful identity migration](../migrate-to-ory/migrate/migrate-strategies#graceful-identity-migration).

	- Ory account and CLI installed
	- Ory account with an Ory project already created - See [creating a project](docs/migrate-to-ory/migrate/create-project.mdx) for instructions

	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
	Access Token and the ID of your connection. You will need this information to export the Auth0 user data, when you run the migration export script.


		### 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

	### Configure environment variables
	### Set environment variables

	Configure the migration script by exporting the necessary environment variables:
	Set necessary environment variables for the import script:

	3. [Import users to Ory](#import-users-to-ory): Run the migration script to create users in Ory
	3. [Import users to Ory](#import-users-to-ory): Run the migration import script to create users in Ory


		#### 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,

	The script accounts for all possible metrics you can export in a bulk user export. The bulk user export is a compressed,
	The export script accounts for all possible metrics you can export in a bulk user export. The bulk user export is a compressed,

	This script creates `AUTH0_USERDATA.json` in your current directory and contains all the exported user data.
	This export script creates `AUTH0_USERDATA.json` in your current directory and contains all the exported user data.

fix: correct Auth0 export users script and update documentation #2330

Are you sure you want to change the base?

fix: correct Auth0 export users script and update documentation #2330

Conversation

wassimoo commented Oct 27, 2025

Related Issue or Design Document

Changes

Script Fixes (0-get-auth0-user-data.sh)

Documentation Improvements (auth0.mdx)

Impact

Checklist

Uh oh!

CLAassistant commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vinckr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Script Fixes (`0-get-auth0-user-data.sh`)

Documentation Improvements (`auth0.mdx`)

CLAassistant commented Oct 27, 2025 •

edited

Loading

unatasha8 Nov 13, 2025 •

edited

Loading

unatasha8 Nov 13, 2025 •

edited

Loading