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 security@ory.com) 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

docs/migrate-to-ory/auth0.mdx

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

docs/migrate-to-ory/auth0.mdx

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

docs/migrate-to-ory/auth0.mdx

unatasha8

Added a bunch of suggestions.

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