Configure Automatic Migration from Your Database

Account Linking Using Server Side Code

We recently introduced some changes in Account Linking. For all the details see Migration Guide: Account Linking and ID Tokens.

In this tutorial, you will use server-side code to facilitate account linking on a regular web application. Rather than automating the entire account linking process, you're engaging the user and asking them for permission before proceeding. Your code will:

  1. Authenticate the user
  2. Search for and identify users using their email addresses
  3. Prompt the user to link their accounts
  4. Verify and merge metadata
  5. Link the accounts

Additionally, this tutorial will show you how you can unlink accounts at a later time.

You can find sample code for this tutorial in the Auth0 Node.js Regular Web App Account Linking repo on Github.

Configure the scripts

Step 1: Authenticate the user

Start by logging in the user to your application.

The recommended implementation is to use Universal Login. You can find detailed guidance on how to do just that at our Node.js Quickstart.

If you choose instead to embed the Lock widget in your app, you can review the sample code for this tutorial in the Auth0 Node.js Regular Web App Account Linking repo on Github.

If you don't use Lock at all, but call the Authentication API directly, follow our tutorial, Call API Using the Authorization Code Flow.

Verify the migration

Step 2: Search for users with identical email addresses

During the post-login page load, your app invokes a custom endpoint that returns a list of users that could be linked together. This is done using the following code:

To get a list of all of the user records with the same email address, your app calls the Management API's Get Users By Email endpoint using a Management API Access Token with the read:users scope.

Convert the database

If Auth0 returns one or more records with matching email addresses, the user sees the list, as well as the following message prompting them to link the accounts: We noticed there are other registered users with the same verified email address as EMAIL_ADDRESS. Do you want to link the accounts?.

If the user wants to link a given account, they can click Link next to the appropriate account.

Disconnect the legacy database

Step 4: Verify and merge metadata

The user clicking on Link invokes your custom endpoint for account linking. However, before calling linkAccounts, you can verify or retrieve metadata from secondary accounts and merge them into the metadata fields for the primary account. After the accounts are linked, the metadata for the secondary accounts is discarded.

Additionally, when calling linkAccounts, you can select the primary account identity. Your choice will depend on which set of attributes you want to retain in the user's profile.

The following code snippet shows how you can implement both features.

In the example above, you'll notice that the email address is verified a second time. This is to ensure that targetUserId hasn't been tampered with on the client side.

Keep reading

Merging metadata

The following example shows explicitly how the user_metadata and app_metadata from the secondary account gets merged into the primary account using the Node.js Auth0 SDK for API V2.

Once you've found the user accounts, prompted the user to merge the selected accounts, and verified/merged the metadata associated with the primary and secondary identities, you're ready to actually link the accounts.

To link accounts, your app needs to call the Management API's Link a User Account endpoint. You need to call the API using a Management API Access Token with the update:users scope.

Unlinking accounts

If you need to unlink two or more user accounts, you can do so.

First, you need to update the user in session with the new array of identities (each of which represent a separate user account).

Then, call the Management API v2 Unlink a User Account endpoint using an Management API Access Token with the update:users scope.

That's it, you are done!