Account Linking Using Server Side Code
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:
- Authenticate the user
- Search for and identify users using their email addresses
- Prompt the user to link their accounts
- Verify and merge metadata
- 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.
Step 1: Authenticate the user
Start by logging in the user to your application.
If you don't use Lock at all, but call the Authentication API directly, follow our tutorial, Call API Using the Authorization Code Flow.
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:
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.
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.
The following example shows explicitly how the
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.
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).
That's it, you are done!