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.

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.

• 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

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"
    ]
  },
  ...
}

{
  "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"
    ]
  },
  ...
}

{
  "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"
    ]
  },
  ...
}

Note that:

• The user_id and all other main profile properties continue to be those of the primary identity

• The first identity in the user.identities array is the primary identity

• The secondary account is now embedded in the user.identities array of the primary profile

• The attributes of the secondary account are placed inside the profileData field of the corresponding identity inside the array

• The user_metadata and app_metadata of the primary account have not changed

• The user_metadata and app_metadata of the secondary account are discarded

• There 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 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

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.

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.

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.

To learn more about how to implement user-initiated account linking in a Regular Web Application, read Server-Side Account Linking.

• Link User Accounts
• Unlink User Accounts
• User-Initiated Account Linking: Client-Side Implementation
• User Account Linking: Server-Side Implementation