Account Linking

Account Linking is the task of binding a foreign account to a local account. A very common scenario is to link a social account such as Facebook with a local account stored in the database, but there are many more scenarios where account linking is useful:

  • Linking legacy accounts with a new account when merging organizations
  • Linking cloud-based accounts with each other using a local account as the common identifier
  • Linking social accounts for ease of login

Important

When linking accounts, it’s important that the identifier used to create the link is considered globally unique in the linking context. If there is a risk that the username used to link may change in the foreign account, there is a chance that users may take over links. If the foreign account cannot produce a globally unique identifier, then linking should not be performed.

Basic Concepts

Linking is done using a linking account manager. This is an account manager that points to a data source where the local account exists. If there is no local account for any reason, see the Common Linking Flows section.

../../_images/account-manager.svg

Fig. 123 Account Manager Referencing Local Accounts

It’s important to get familiar with the concepts of local and foreign accounts, since they help when understanding how the links are created.

  • Local Account : An account stored and accessed by the Linking Account Manager
  • Foreign Account: An account not stored locally, or not referenced by the Linking Account Manager

A link will result in a conceptual database entry in the following form:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe@social.com example-domain

Later when logging in with the foreign account it is possible to resolve the link by doing a lookup of foreign-username + foreign-domain.

So if johndoe@social.com would login again, we could configre a resolver to look for the username using example-domain and retrieve ABCDE-12345.

It is also possible to do a lookup. When account ABCDE-12345 logs in again; a lookup can find all links available for that user and add it to the authentication attributes.

Note

Depending on datastore the resolve operation may not be available. See Account and Credential Management for details of operations supported by each datastore type

Linking is performed when the linking action (Auto Link Accounts) is triggered. It uses the following data to determine if a link can be created:

  1. The user of the authenticator the action is configured on.
  2. The previously authenticated sessions.
  3. The account domain to look for in the authenticated sessions.

Example of Linking with Facebook

Say we want to link a social account such as Facebook with a local account. There are many ways to do this which will be explained in Common Linking Flows but here is a basic example:

  1. The user logs in with a Facebook authenticator configured with the account domain facebook-domain.
  2. Later the user logs in with an HTML form authenticator configured with the linking action.
  3. The action finds the facebook-domain session in the authenticated sessions, and creates a link using the linking account manager
../../_images/example-of-linking-with-facebook.svg

Fig. 124 Example Linking with Facebook

The HTML Form authenticator and the Link action are both using the same account manager. This makes the HTML Form user a local user. The resulting link will look as follows:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe-facebook-id123 facebook-domain

Example of Linking with Facebook as Second authenticator

In the above example Facebook was the first authenticator and the foreign account. However it is also possible to reverse the flow. If the linking action is placed on the facebook authenticator instead. Facebook is still considered to be the foreign account, so we can no longer treat the authenticator that the action is placed on as the local account. Therefore we must reverse the linking process. There is a setting on the linking action called use-linked-account-as-main-account (see the configuration reference for more details). This means that the account found in the authenticated sessions is the local account and the account that the action is placed on is the foreign account. The Linking account manager is still configured the same way.

../../_images/example-of-linking-with-facebook-as-second-authenticator.svg

Fig. 125 Example Linking with Facebook in Reverse

The resulting link will still look the same, facebook is still the foreign account:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe-facebook-id123 facebook-domain

Note

When using use-linked-account-as-main-account the linking domain is the domain of the first authenticator (html-form-domain), but the linked foreign-domain is the domain configured on the second authenticator (facebook-domain). This is because of the reverse linking.

Common Linking Flows

This section describes some of the common setups and what to consider when configuring them. Many times it’s needed to combine several of these flows in order to cover all possible login flows for your setup.

Linking using the foreign authenticator and resolving immediately

Very similar to the previous flow, but instead the foreign account is used last. In order to setup a correct link we need to reverse the linking using the configuration value use-linked-account-as-main-account=true on the auto-link-account action.

../../_images/linking-using-the-foreign-authenticator-and-resolving-immediately.svg

Fig. 131 Local Link with Foreign and resolve immediately

The authenticators are configured as follows:

Authenticator Account Domain Actions
facebook facebook-domain auto-link-account, resolve-link
html-form local-domain  

And the actions are configured as follows:

Action Linking Domain Other
auto-link-account local-domain use-linked-account-as-main-account = true
resolve-links facebook-domain  

The resulting link entry will then become:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe-facebook-id123 facebook-domain

All actions use the same account manager.

Linking using the local authenticator, resolving on next login with foreign

In this example we link using the local authenticator. The next time the user logs in using facebook we can resolve the link.

../../_images/linking-using-the-local-authenticator-resolving-on-next-login-with-foreign.svg

Fig. 132 Foreign Link with Local, resolve after next login

The authenticators are configured as follows:

Authenticator Account Domain Actions
facebook facebook-domain resolve-link
html-form local-domain auto-link-account

And the actions are configured as follows:

Action Linking Domain Other
auto-link-account facebook-domain  
resolve-links facebook-domain  

The resulting link entry will then become:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe-facebook-id123 facebook-domain

All actions use the same account manager.

Linking two foreign accounts using auto create account

Sometimes there is no local account. Perhaps the users are stored in Active Directory not managed by Curity or all authentication happens via remote identity providers. In this example, we link GitHub with Facebook. In order to create a link we need to auto-create a local account. Before setting up the flow, consider which authenticator should be the local or main account.

../../_images/linking-two-foreign-accounts-using-auto-create-account.svg

Fig. 133 Link two foreign accounts, resolve immediately

The authenticators are configured as follows:

Authenticator Account Domain Actions
facebook facebook-domain auto-link-accounts, resolve-link
github github-domain auto-create-account

And the actions are configured as follows:

Action Linking Domain Other
auto-link-account github-domain use-linked-account-as-main-account = true
resolve-links facebook-domain  
auto-create-account    

The resulting link entry will then become:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe-facebook-id123 facebook-domain

It will also result in a new entry in the accounts:

Account ID Username
ABCDE-12345 johndoe-github-335

All actions use the same account manager.

Linking two foreign accounts using auto create & resolving on next login

The above example treated the GitHub account which was the first authenticator as the main account. It’s of course possible to treat the second authenticator as the main account, and instead put auto-create on that one.

../../_images/linking-two-foreign-accounts-using-auto-create-and-resolving-on-next-login.svg

Fig. 134 Link two foreign acounts, resolve on next login

The authenticators are configured as follows:

Authenticator Account Domain Actions
facebook facebook-domain auto-create-account, auto-link-accounts
github github-domain resolve-link

And the actions are configured as follows:

Action Linking Domain Other
auto-link-account github-domain  
resolve-links github-domain  
auto-create-account    

The resulting link entry will then become:

Local Account ID Foreign Account Username Foreign Account Domain
ABCDE-12345 johndoe-github-335 github-domain

It will also result in a new entry in the accounts:

Account ID Username
ABCDE-12345 johndoe-facebook-id123

All actions use the same account manager.

Tip

You can also configure the resolve action as an sso action if the user remains logged in with GitHub but resolution is desired.