User Account Linking
Auth0 supports the linking of user accounts from various identity providers. This allows a user to authenticate from any of their accounts and still be recognized by your app and associated with the same user profile.
Availability varies by Auth0 plan and login method
Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read Pricing.
Auth0 treats all identities as separate by default. For example, if a user logs in first against the Auth0 database and then via Google or Facebook, these two attempts would appear to Auth0 as two separate users. You can implement functionality to enable a user to explicitly link accounts. In this scenario, the user would log in with an initial provider, perhaps Google. Your application would provide a link or button to enable them to link another account to the first one. The user would click on this link/button and your application would make a call so that when the user logs in with the second provider, the second account is linked with the first.
Advantages of linking accounts
Allows users to log in with any identity provider without creating a separate profile for each
Allows registered users to use a new social or passwordless login but continue using their existing profile
Allows users that registered using a passwordless login to link to an account with a more complete profile
Allows your apps to retrieve user profile data stored in various connections
Precautions
Insecurely linking accounts can allow malicious actors to access legitimate user accounts. Please remain aware of the following:
For both manual and automatic account links, your tenant should request authentication for both accounts before linking occurs.
In addition, every manual account link should prompt the user to enter credentials.
How it works
The process of linking accounts merges two existing user profiles into a single one. When linking accounts, a primary account and a secondary account must be specified.
In the example below you can see how the resulting linked profile will be for the sample primary and secondary accounts.
{
"email": "your0@email.com",
"email_verified": true,
"name": "John Doe",
"given_name": "John",
"family_name": "Doe",
"picture": "https://lh3.googleusercontent..../photo.jpg",
"gender": "male",
"locale": "en",
"user_id": "google-oauth2|115015401343387192604",
"identities": [
{
"provider": "google-oauth2",
"user_id": "115015401343387192604",
"connection": "google-oauth2",
"isSocial": true
}
],
"user_metadata": {
"color": "red"
},
"app_metadata": {
"roles": [
"Admin"
]
},
...
}
Was this helpful?
{
"phone_number": "+14258831929",
"phone_verified": true,
"name": "+14258831929",
"updated_at": "2015-10-08T18:35:18.102Z",
"user_id": "sms|560ebaeef609ee1adaa7c551",
"identities": [
{
"user_id": "560ebaeef609ee1adaa7c551",
"provider": "sms",
"connection": "sms",
"isSocial": false
}
],
"user_metadata": {
"color": "blue"
},
"app_metadata": {
"roles": [
"AppAdmin"
]
},
...
}
Was this helpful?
{
"email": "your0@email.com",
"email_verified": true,
"name": "John Doe",
"given_name": "John",
"family_name": "Doe",
"picture": "https://lh3.googleusercontent..../photo.jpg",
"gender": "male",
"locale": "en",
"user_id": "google-oauth2|115015401343387192604",
"identities": [
{
"provider": "google-oauth2",
"user_id": "115015401343387192604",
"connection": "google-oauth2",
"isSocial": true
},
{
"profileData": {
"phone_number": "+14258831929",
"phone_verified": true,
"name": "+14258831929"
},
"user_id": "560ebaeef609ee1adaa7c551",
"provider": "sms",
"connection": "sms",
"isSocial": false
}
],
"user_metadata": {
"color": "red"
},
"app_metadata": {
"roles": [
"Admin"
]
},
...
}
Was this helpful?
Note that:
The
user_id
and all other main profile properties continue to be those of the primary identityThe first identity in the
user.identities
array is the primary identityThe secondary account is now embedded in the
user.identities
array of the primary profileThe attributes of the secondary account are placed inside the
profileData
field of the corresponding identity inside the arrayThe
user_metadata
andapp_metadata
of the primary account have not changedThe
user_metadata
andapp_metadata
of the secondary account are discardedThere is no automatic merging of user profiles with associated identities
The secondary account is removed from the users list
If you delete the primary account, the secondary account is deleted as well
Metadata merge
Metadata is not automatically merged during account linking. If you want to merge it, you have to do it manually using the Manage API /users/patch_users_by_id
endpoint.
The Auth0 Node.js SDK for APIv2 is also available.
To learn more, read Understand How Metadata Works in User Profiles
Scenarios
There are two different ways of implementing account linking:
User-initiated account linking: allow your users to link their accounts using an admin screen in your app.
Suggested account linking: identify accounts with the same email address and prompt the user in your app to link them.
User-initiated account linking
Typically, account linking will be initiated by an authenticated user. Your app must provide the UI, such as a Link accounts button on the user's profile page.
To learn more about how to implement user-initiated account linking in a Single Page Application, read Client-Side Account Linking. To learn more about how to implement user-initiated account linking in a Regular Web Application, read Server-Side Account Linking.
Suggested account linking
You can find accounts with the same email, and prompt the users to link them. For example, a user can create an account with Google with the user@gmail.com, and then log in with Facebook, with an account linked to the same email.
If that occurs, you can show users the list of available accounts so they can link them, by first authenticating with the account they will be linking to.
You can also use the Account Link Extension to achieve the same outcome.