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:
foreign
local
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.
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.
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.
A link will result in a conceptual database entry in the following form:
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.
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:
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:
facebook-domain
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:
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.
facebook
use-linked-account-as-main-account
Fig. 125 Example Linking with Facebook in Reverse
The resulting link will still look the same, facebook is still the foreign account:
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.
After a link has been created, it can be resolved. This is the operation where we lookup the link, and replace the logged in username with the main account’s username.
In the example with Facebook, it may be useful to let the user login with Facebook in the future, but replace the username after login with the local account’s username, so that all internal services can operate as usual without having to deal with knowing about social logins like Facebook. This is called resolving an account link.
To resolve an account, another action is used: Resolve Account Link. Apply this to the foreign authenticator (Facebook in the example) and use the same linking account manager as when creating the link:
Fig. 126 Example Resolve Link
To configure link resolution, add a resolve action on the authenticator configuration:
Fig. 127 Resolve Link configuration on the Facebook authenticator
There is no need to set the action as sso action, since the resolved username will be the username stored in the SSO session. So when the user comes back it is already resolved.
sso
The resolve configuration is configured to look for links in the facebook-domain using the same account manager as when linking.
Fig. 128 Resolve Link Action configuration
It’s possible to pass in the original username as well when resolving links as additional attributes in the authentication result.
In many cases it’s not necessary to resolve the link. Instead it might be desired to simply list the available links for the local account and pass those on in the authentication result. A good example could be in an organization that has merged several legacy accounts into a single global account. Then it might be of interest to still pass along the legacy accounts in the authentication result when logging in using the global account.
Fig. 129 Lookup Links Action
Lookup links does not replace the username with the linked account’s username. Instead it’s used to add the available links for the local account.
For more information on how to configure link lookups see Lookup Links Action.
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.
This is one of the most common flow. One local account and one foreign account. The user has already logged in with the foreign authenticator when the action triggers.
Fig. 130 Foreign - Local Link and Lookup
The authenticators are configured as follows:
And the actions are configured as follows:
The resulting link entry will then become:
All use the same account manager.
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.
use-linked-account-as-main-account=true
auto-link-account
Fig. 131 Local Link with Foreign and resolve immediately
All actions use the same account manager.
In this example we link using the local authenticator. The next time the user logs in using facebook we can resolve the link.
Fig. 132 Foreign Link with Local, resolve after next login
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.
Fig. 133 Link two foreign accounts, resolve immediately
It will also result in a new entry in the accounts:
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.
Fig. 134 Link two foreign acounts, resolve on next login
Tip
You can also configure the resolve action as an sso action if the user remains logged in with GitHub but resolution is desired.
resolve