There are times when a company is using Auth0 for a while and they decide they need to move their tenant to a different region, or a private instance or public from private. Due to the sensitive nature of passwords, Auth0 does not support export and import of passwords. To help facilitate this, here is an example for setting up a migration from one tenant to another in a different region.
It follows the same traditional model that Auth0 uses for migrating from other identity providers such as Parse.
login.js is used to create a custom database pointing to old account.
It uses standard OpenID Connect /token interface to authenticate and receive id_token for customer profile. After
authentication, users are also created in new account's database.
One last thing before we get started to simplify our terminology:
- old account : the account you are migrating from. This is amin02 in the screenshots.
- new account: the account you are migrating to. This is amin01 in the screenshots.
These accounts could be sitting in different locations (US, Europe, Australia) or even in private installations. The steps and screenshots below are for cloud deployment but the same should go for private deployments as well.
Setup consist of two parts: your old account from which you import accounts, and your new account.
Login to your old account in Auth0. Go to management dashboard and follow these steps:
From the left-hand side list, click on Clients link. Then click Create Client box.
Put a name (such as "Migration App") and select Non Interactive Client type.
Migration client app will have its own Domain as well as auto-generated Client ID and Secret.
Let's leave it there for now. We'll come back to grab these values when setting up migration scripts in your new account.
Scroll down in client application settings page. You'll find Client Type and Token Endpoint Authentication Method settings. Change values to:
- Client Type switch to Non Interactive Client
- Token Endpoint Authentication Method becomes active then. Set it to Post
Scroll down further to client settings page. At the bottom of the page you'll find Show Advanced Settings link. Click to open and select Grant Types tab. There's no harm keeping rest of grant types but for this application you must have these two:
- Client Credentials
- Password
For those interested to dig deeper, "Client Credentials" is used to validate user's input
username and password in login.js and "Password" grant type is used to generate a new management API access_token so
get_user.js can invoke search API.
Both endpoints also receive client_id and client_secret for authentication in the body of POST request as
configured in Step 4.
We're done with the client application creation but there's still a few more steps required in old account.
Go back to dashboard and this time click on API section.
This should open up Auth0 Management API client section and its API Audience.
Similar to client Domain, ID and Secret, we'll need the value for Audience URL when configuring the new account scripts.
Click on the Auth0 Management API link and select the Non Interactive Clients tab. Here you'll see list of your client applications. Make sure Migration App is Authorized to call management API. Note if your creation client application has any other name (Step 2), same is shown here.
Management API is pretty powerful and we only need a small subset in order to perform migration task.
Go to Scopes tab and only select read:users.
Go to Rules section of dashboard and click on "Create (Your First) Rule", then select empty rule template. Put the rule name as "add user and app metadata to profile" and copy metadata-rule.js code to editor and Save.
Congratulation, we are done setting up the migration client in your old account which is the bulk of work. The remaining steps need to be done in your new account. You may now logout from your old account and login to new account.
New account is the one we're migrating customer to. As we mentioned in "How Does it Work" section it has its own database that gradually grow as customers login.
To get started let's login to your new account and go Connections >> Database >> Username-Password-Authentication.
Within Database settings page, go to Custom Database tab and enable Use my own database flag.
Once you've enabled the custom database mode, scroll down to Database Action Scripts section. Here you have two tabs. Select Login tab and replace the sample code with the code from login.js, then click Save.
Now switch to Get User tab and copy the code from get_user.js into the box and click Save.
We're almost there with our custom database scripts. Only remaining bit is to scroll further down the page to Settings section. Here we'll add four values from old account setup as Key/Value parameters.
| Key | Sample Value | Description | Setup Step |
|---|---|---|---|
Domain |
amin02.auth0.com |
Domain of Migration App | Step 3 |
Client_ID |
7eph1tcmdmmYZq0znMSYn36BqMTbD6WD |
Client ID of Migration App | Step 3 |
Client_Secret |
Y2aepoy.........6yidAyFz |
Client Secret of Migration App | Step 3 |
Audience |
https://amin02.auth0.com/api/v2/ |
Management API audience of old account | Step 6 |
Connection |
TESTDB |
Connection name in old account |
Last step of configuration is to go back to Settings tab in database settings and Enable Import Users to Auth0 flag. This is critical as it enables Auth0 to collect password and store accounts as customers login.
That's it folks. Now point your applications to new account.
Checkout this quick start for a full run of login and forgotten password flows.
Considering this is an on-demand strategy, migration takes time. It could vary from a few days to months depending on frequency of customers visit. At the end of migration phase, if there are still customers pending, you may decide to either not migrate them or do a bulk Import/Export. Once old Auth0 account is shut down, there is no way to validate non-migrated users' credentials except with their profile migrated, they can use the "Forgotten Password" link to set a new password and continue to use the system if needed.
To achieve this, follow the below steps at the end of migration phase:
- Install Import/Export extension on both old and new accounts
- Export all accounts from old account into default JSON file
- Import JSON file from step 2 into new account using the same extension
- Review results in your mailbox. Fail ones are normal for the migrated users as their email is already registered in new account.
NOTE: Users migrated with bulk import/export step don't have their passwords in the new account. They have to use "Don't remember your password?" link on login page to reset their password.