Descope Auth0 Migration Guide without passwords image.

Introduction

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.

This guide covers how to migrate your Auth0 users to Descope. 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.

Prerequisites

There are some prerequisites you will want to ensure you have leading up to the 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 you need to create within Descope to assist you with the migration. The below outlines the machine names of the attributes to create 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.
  1. (Optional) If you would like to migrate passwords, open a ticket with Auth0 support to request an export of your user's password hashes.
  2. (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.

Running the Migration Script

Note: The migration tool source code can be found on GitHub

Configure Local Environment


  1. Clone the Repo:
git clone git@github.com:descope/descope-auth0-migration.git
  1. Create a Virtual Environment
python3 -m venv venv
source venv/bin/activate
  1. Install the Necessary Python libraries
pip3 install -r requirements.txt
  1. 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

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 --from-json ./path_to_user_export.jso --with-passwords ./path_to_exported_password_users_file.json

Dry run without passwords: python3 src/main.py --from-json ./path_to_user_export.jso

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

Live run without passwords: python3 src/main.py --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 --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

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

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_%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
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_%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

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.

Post Migration User Experience

Once you have migrated your users to Descope, you can define your user's login experience. Utilizing the freshlyMigrated custom user attribute, you can define a path for your user.

An example of using the freshlyMigrated attribute within a Descope flow conditional.

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.

An example of setting the freshlyMigrated attribute to false within flows.