Auth0 Migration Guide

It may seem like an uphill battle when it comes to changing your authentication provider; however, with Descope's migration tool, you can rest assured your migration will be a breeze.

There are two ways you migrate to Descope from Auth0. You can either do a Full Migration or a Hybrid Migration.

• Full Migration - You completely move off of Auth0 to Descope, no longer using Auth0 in any way. (Most Common)
• Hybrid Migration - You still use Auth0 but you will authenticate your users with Descope (as a federated IdP).

This documentation will cover both of these migration options. If you want to continue with the Hybrid Migration, complete the first step under Full Migration first, and then skip to Hybrid Migration.

Full Migration

There are various options for migration including the ability to migrate via Auth0 API if you have less than 1000 users, JSON export when you have more than 1000 users, without passwords, and with passwords.

If you desire to completely move away from Auth0, the Full Migration option is the one for you. Otherwise, complete Step 1 under the Full Migration guide and then skip to the Hybrid Migration section.

Prerequisites

Ensure you have the following before starting:

• Access to your Auth0 account with Permissions
• Familiarity with your current Auth0 setup

1. Importing from Auth0

Configure Local Environment

Follow these steps to set up your environment for migration:

1. You will need to have your Auth0 Tenant ID. Your Auth0 Tenant ID can be found in the URL of your Auth0 dashboard. For example, your URL might look something like this: https://manage.auth0.com/dashboard/us/dev-xyz/ within this example, your tenant ID would be dev-xyz.

2. You will need to generate a Auth0 token. You can generate these 24 hour tokens from this location within Auth0.

3. You will need your Descope project ID which can be found here.

4. You will need a Descope Management Key, if you do not already have one stored, you can create one here.

5. The tool depends on a few custom user attributes that will automatically be created for you within Descope to assist you with the migration. The below outlines the machine names of the attributes created within the user's custom attributes section of the Descope console.

   • connection (type: text): This custom attribute will contain the different connection types associated to the user which was migrated from Auth0.
   • freshlyMigrated (type: Boolean): This custom attribute will be set to true during the migration. This allows for you to later check this via a conditional during Descope flow execution, see Post-Migration.

6. (Optional) If you would like to migrate passwords, open a ticket with Auth0 support to request an export of your user's password hashes.

7. (Optional) Due to the Auth0 API limitation for loading users, even with pagination, if you have over 1000 users within Auth0, it is recommended to export a JSON of users if you have more than 1000 users. To export the JSON, follow these steps.

8. Clone the Repo:

git clone git@github.com:descope/descope-migration.git

2. Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate

3. Install the Necessary Python libraries

pip3 install -r requirements.txt

4. Setup Your Environment Variables

You can change the name of the .env.example file to .env to use as a template. Then populate with the items generated within the prerequisites section of this guide.

AUTH0_TOKEN=Your_Auth0_Token // Required, this is generated within Auth0
AUTH0_TENANT_ID=Your_Auth0_Tenant_ID // Required, this is the tenant ID of your tenant within Auth0
DESCOPE_PROJECT_ID=Your_Descope_Project_ID // Required, this is your Descope ProjectId
DESCOPE_MANAGEMENT_KEY=Your_Descope_Project_ID // Required, this is your Descope Management Key

Running the Migration Script

You can use the -v or --verbose flags to enable more detailed output. This works for both live and dry runs, providing you with additional information.

Migrating from JSON Export:

The below is a list of examples of execution flags that are available when migrating from Auth0 using a JSON export with and without passwords.

Dry run with passwords: python3 src/main.py auth0 --dry-run --from-json ./path_to_user_export.jso --with-passwords ./path_to_exported_password_users_file.json
 
Dry run without passwords: python3 src/main.py auth0 --dry-run --from-json ./path_to_user_export.jso
 
Live run with passwords: python3 src/main.py auth0 --from-json ./path_to_user_export.jso --with-passwords ./path_to_exported_password_users_file.json
 
Live run without passwords: python3 src/main.py auth0 --from-json ./path_to_user_export.jso

Migrating with Auth0 API:

Dry Run

You can dry run the migration script which will allow you to see the number of users, tenants, roles, etc which will be migrated from Auth0 to Descope.

With Passwords

python3 src/main.py auth0 --dry-run --with-passwords ./path_to_exported_password_users_file.json

The output would appear similar to the following:

Running with passwords from file: ./path_to_exported_users_file.json
Would migrate 2 users from Auth0 with Passwords to Descope
Would migrate 112 users from Auth0 to Descope
Would migrate 2 roles from Auth0 to Descope
Would migrate MyNewRole with 2 associated permissions.
Would migrate Role with 0 associated permissions.
Would migrate 2 organizations from Auth0 to Descope
Would migrate Tenant 1 with 5 associated users.
Would migrate Tenant 2 with 4 associated users.

Without Passwords

python3 src/main.py auth0 --dry-run

The output would appear similar to the following:

Would migrate 112 users from Auth0 to Descope
Would migrate 2 roles from Auth0 to Descope
Would migrate MyNewRole with 2 associated permissions.
Would migrate Role with 0 associated permissions.
Would migrate 2 organizations from Auth0 to Descope
Would migrate Tenant 1 with 5 associated users.
Would migrate Tenant 2 with 4 associated users.

Live Run

To live migrate your Auth0 users, follow the below examples with and without passwords.

With Passwords

python3 src/main.py auth0 --with-passwords ./path_to_exported_password_users_file.json

The output will include the responses of the created users, organizations, roles, and permissions as well as the mapping between the various objects within Descope. A log file will also be generated in the format of migration_log_auth0_%d_%m_%Y_%H:%M:%S.log. Any items which failed to be migrated will also be listed with the error that occurred during the migration.

Running with passwords from file: ./path_to_exported_users_file.json
Starting migration of 2 users from Auth0 password file
Starting migration of 112 users found via Auth0 API
Still working, migrated 10 users.
...
Still working, migrated 110 users.
Starting migration of 2 roles found via Auth0 API
Starting migration of MyNewRole with 2 associated permissions.
Starting migration of Role with 0 associated permissions.
=================== Password User Migration ====================
Auth0 Users password users in file 2
Successfully migrated 2 users
Created users within Descope 2
=================== User Migration =============================
Auth0 Users found via API 112
Successfully migrated 110 users
Successfully merged 2 users
Users migrated, but disabled due to one of the merged accounts being disabled 1
Users disabled due to one of the merged accounts being disabled ['auth0|653c1bf0398960f19a6d8171']
Failed to migrate 2
Users which failed to migrate:
facebook|122094272078100956 Reason: {"errorCode":"E011002","errorDescription":"Request is missing required arguments","errorMessage":"Missing email or phone","message":"Missing email or phone"}
facebook|10226222057950897 Reason: {"errorCode":"E011002","errorDescription":"Request is missing required arguments","errorMessage":"Missing email or phone","message":"Missing email or phone"}
Created users within Descope 108
=================== Role Migration =============================
Auth0 Roles found via API 2
Successfully migrated 2 roles
Created roles within Descope 2
=================== Permission Migration =======================
Auth0 Permissions found via API 2
Successfully migrated 2 permissions
Created permissions within Descope 2
=================== User/Role Mapping ==========================
Successfully role and user mapping
Mapped 1 user to MyNewRole
Mapped 2 user to Role
=================== Tenant Migration ===========================
Auth0 Tenants found via API 2
Successfully migrated 2 tenants
=================== User/Tenant Mapping ========================
Successfully tenant and user mapping
Associated 5 users with tenant: Tenant 1
Associated 4 users with tenant: Tenant 2

Without Passwords

python3 src/main.py auth0

The output will include the responses of the created users, organizations, roles, and permissions as well as the mapping between the various objects within Descope. A log file will also be generated in the format of migration_log_auth0_%d_%m_%Y_%H:%M:%S.log. Any items which failed to be migrated will also be listed with the error that occurred during the migration.

Starting migration of 112 users found via Auth0 API
Still working, migrated 10 users.
...
Still working, migrated 110 users.
Starting migration of 2 roles found via Auth0 API
Starting migration of MyNewRole with 2 associated permissions.
Starting migration of Role with 0 associated permissions.
=================== User Migration =============================
Auth0 Users found via API 112
Successfully migrated 110 users
Successfully merged 2 users
Users migrated, but disabled due to one of the merged accounts being disabled 1
Users disabled due to one of the merged accounts being disabled ['auth0|653c1bf0398960f19a6d8171']
Failed to migrate 2
Users which failed to migrate:
facebook|122094272078100956 Reason: {"errorCode":"E011002","errorDescription":"Request is missing required arguments","errorMessage":"Missing email or phone","message":"Missing email or phone"}
facebook|10226222057950897 Reason: {"errorCode":"E011002","errorDescription":"Request is missing required arguments","errorMessage":"Missing email or phone","message":"Missing email or phone"}
Created users within Descope 108
=================== Role Migration =============================
Auth0 Roles found via API 2
Successfully migrated 2 roles
Created roles within Descope 2
=================== Permission Migration =======================
Auth0 Permissions found via API 2
Successfully migrated 2 permissions
Created permissions within Descope 2
=================== User/Role Mapping ==========================
Successfully role and user mapping
Mapped 1 user to MyNewRole
Mapped 2 user to Role
=================== Tenant Migration ===========================
Auth0 Tenants found via API 2
Successfully migrated 2 tenants
=================== User/Tenant Mapping ========================
Successfully tenant and user mapping
Associated 5 users with tenant: Tenant 1
Associated 4 users with tenant: Tenant 2

2. Testing and Finalizing Migration

Once all of these have been completed, it's a good idea to perform comprehensive testing to ensure all functionalities are working as expected, and your user migration went smoothly.

Congratulations, you've fully migrated to Descope! If you're doing the Hybrid Migration approach, you can read on to the next section of this documentation.

Hybrid Migration

Hybrid Migration is less common with Auth0; however, if you have a specific use case, Descope can be used as your authentication service within Auth0.

1. Integrating Descope as an Identity Provider

Assuming you've already followed the Step 1 under Full Migration above, you should already have all of your users, tenants, permissions, and roles in Descope. After successfully importing from Auth0, you can proceed with configuring Descope as an external identity provider.

To do this, follow the guide on configuring Descope as an external identity provider for Auth0.

2. Testing and Finalizing Migration

Once you configured Descope as an external identity provider, you should be able to now login using Descope Flows. Once all of these steps have been completed, it's a good idea to perform comprehensive testing to ensure all functionalities are working as expected, and your user migration went smoothly.

Post Migration Verification

Once the migration tool has ran successfully, you can check the users, roles, permissions, and tenants for the migrated items from Auth0. Make sure to verify the created items based on the output of the migration tool.

Also, you can define your user's login experience. Utilizing the freshlyMigrated custom user attribute, you can define a path for your user.

You can then go down different paths from this conditional within the flow. If you'd like to verify the user's email or phone, you can, and then proceed with adding passwords (or forcing update of password if you migrated passwords) and passkeys.

Then after defining the user's experience, you will need to update the user's properties setting the freshlyMigrated attribute to false.