18 Sep, 2019

Local Account Linking

  • Johann Nallathamby
  • Director - Solutions Architecture - WSO2


In the article Identity Management Solution Patterns, we took a look at some of the reasons why organizations may need to continue to manage some parts of a digital identity under specific applications or services (relying parties or RPs), even if they are utilizing a centralized identity management system. In such cases, an important requirement is to establish the link between these related digital identities.

Local account linking refers to linking multiple digital identities that are used to represent a single physical identity across multiple applications and services, in the identity and access management (IAM) system they are presented in.

Implicit and Explicit Linking

Local account linking can be classified into the following two types:

  1. Implicit linking
  2. Implicit linking refers to a visible linkage that exists between digital identities across relying parties. Examples of implicit linking are using the same unique user identifier across relying parties or having the same unique claim value across relying parties. This is mostly the case in organizations that started with a centralized IAM in a greenfield adhering to IAM design best practices, or for new users on-boarded after the introduction of a centralized IAM.

  3. Explicit linking
  4. Explicit linking is required when there is no visible linkage to the naked eye, between digital identities across different relying parties in an organization. This is mostly the case in organizations that have been operating identity silos. In other words, the purpose of explicit linking is to bridge identity silos.

Account Linking vs. Account Merging

When digital identities are linked in the IAM system, all the linked identities will continue to be presented as logically distinct identities to its relying parties. This means that each identity’s credentials, profiles, groups, relationships, and entitlements continue to be managed separately.

Basic account linking can be augmented with “credential unification” where a “unified credential” is designated as the only active credential going forward. This credential may be newly created or an existing credential may be promoted as the unified credential while all other credentials may be deprecated.

In contrast to account linking, in “account merging” organizations try to merge existing digital identities and come up with one designated “unified identity”, which will be used to access relying parties going forward. This means that from the point of view of relying parties there is only one identity that is known to exist for the physical identity. When building a unified identity, existing information is captured from all existing identities. The unified identity could be pre-built and managed or it could be built on-the-fly during runtime access. In some cases, conflict resolution may be needed to resolve conflicting values for attributes and/or entitlements of the user. This could be configured to happen automatically or manually. Manual methods may involve self-service resolution or assigning a task to an administrator to resolve it. With manual conflict resolution, however, unified identities cannot be built on-the-fly.

However, in most instances, account linking and account merging work in tandem. Where unified identities are used to login to the IAM system, they are also used to access newly on-boarded relying parties, while the corresponding linked identities continue to be used to access existing relying parties due to the difficulty in migrating their existing internal data.


The main motivation behind local account linking is that the user experience and security can be improved knowing that all these digital identities belong to the same physical identity. For example:

  1. Administrators can manage linked identities better.
  2. Get a 360 degree view of the end user with a linked digital identity.
  3. With credential unification:
    • Login using one set of credentials to all relying parties.
    • Login using one identity to the end user portal and manage all the linked identities from there by switching between different identities.
    • Password policies, account locking, etc. can be handled in a more meaningful way.
  4. With account merging end user experience is drastically improved by having to self-manage only one identity.

In addition to the above reasons, another scenario of motivation for local account linking is where the credentials and attributes of a single identity may be separated into their dedicated stores. We call them “credential stores” and “attribute stores” respectively. In such cases, linking up the matching identities across these stores becomes a mandatory requirement. This is more of a technical design requirement in IAM rather than a problem that needs to be solved by IAM. Local account linking could be seen as a viable approach to solve this requirement as well.

The same requirement can be extended further to multiple credential stores and multiple attribute stores per identity, where each of them may be designated to a relying party.

Yet another scenario for motivation is with one credential store and multiple attributes stores per identity. This could happen due to an account merging scenario where the unified identity will be built on-the-fly. The new requirement could be that users will start logging in using the unified credential, however, the linked relying party-specific identity needs to be presented to the requested service.

And the final scenario for motivation is with multiple credential stores and one attribute store per identity. This could happen due to an IAM transition where user attributes were migrated to one store, however, credentials couldn’t be migrated due to the level of complexity. So credentials continue to be managed in separate stores. The new requirement could be that users need to be able to continue logging in with their relying party-specific identities, while attributes are always picked from the unified identity.

Linking Methodologies

Now let’s explore some common approaches that are used for local account linking - however, this article does not seek to provide intricate details on how each of these approaches can be implemented. These approaches can be broadly categorized into two areas:

  1. Admin initiated
  2. Self-serviced

Preference towards these approaches are equally divided.

Admin Initiated

Admin initiated approaches are popular because in a good amount of cases, an implicit link is identifiable within a known environment and therefore end user involvement is not needed for linking. Plus, admin initiated linking has the advantage of being carried out in bulk for multiple users.

The type of identities in a linked pair could include either a unified identity and a relying party-specific identity or two relying party-specific identities. Linking could also happen either when the identity is being provisioned or after it has been provisioned to the IAM system. For example, if identity synchronization happens through SCIM2 API in the IAM system, then it can be considered a new identity provisioning flow. If identity synchronization happens through data-level replication then it should be considered an existing identity in the IAM system. Based on these criteria we can further divide admin initiated local account linking into the following 3 scenarios:

  • Both unified identity and relying party-specific identity being provisioned and linked at the same time.
  • Unified identity is being provisioned and linked to existing relying party-specific identity.
  • Both unified identity and relying on party-specific identities already exist and are being linked.

In admin initiated linking flows, whenever the unified identity is created for the purpose of login, a credential reset flow has to be initiated for the user to be able to set his own credential and use that as the new login.


Self-serviced approaches are popular with explicit linking scenarios and they are generally preferred due to lower administrative overhead. Self-serviced linking can be further divided based on the point at which the identities are linked in the identity lifecycle. Generally there are 3 points in the identity life cycle where this could be done:

  1. Link on self-registration
  2. Just-In-Time linking
  3. Link from self-service portal

Link on Self-registration

It is common to introduce a self-registration portal when a unified identity is being introduced to the system. At the point when users create their unified identity, they may also be able to link their existing relying party-specific identities to that. It is also recommended to lock down any registrations capabilities in other relying parties and have it open only for unified identities in the IAM system so that moving forward users are not able to create relying party-specific identities.

Just-In-Time linking

This is the most popular approach among the 3 self-serviced approaches, due to the simplified user experience provided. Just-In-Time linking refers to linking the unified identity to the relying party-specific identity, on the first login with the relying party identity.

Link from self-service portal

Users who have existing unified identities can login to the self-service user portal and link their relying party specific identities.

To improve the user experience of local account linking, it may be a good idea to build intelligence into the self-service flows above to detect a possible local account linking scenario and suggest it to the user, so that the user can decide whether to proceed with linking or not. For example, suggestions can be based on a combination of one or more matching claims such as unique email addresses or mobile numbers.

Identity Proofing

In all three self-serviced linking approaches we discussed above, there is an important requirement for the user - which is to independently prove ownership of both the identities (s)he is trying to link. This is formally known as “identity proofing”.

In “Link on self-registration”, there is no unified identity as yet to prove ownership. However, the user must still prove ownership of the relying party-specific identities (s)he is trying to link, by authenticating with its credentials.

In “Just-In-Time linking”, the ownership of the relying party-specific identity would have been proven by the fact that the user has used it to login. However, the user must also prove ownership of the unified identity by authenticating with its credentials.

In “Linking from self-service portal”, the ownership of the unified identity would have been proven by the fact that the user has logged in to the self-service portal. However, the user must also prove ownership of the unified identity by authenticating with its credentials.

To authenticate using the relying party-specific identity, users can use their passwords - if passwords have been provisioned when duplicating the relying party-specific identity. If the passwords were not provisioned, you can generate and send a time-constricted one-time-code to a verified address of the user, allowing the user to successfully authenticate once only with the relying party-specific identity for the purpose of account linking.

Linkage Policies

Whichever linking methodologies you choose to use from above, you will essentially use one or more claims of the user and verify that against a policy that has been configured in the IAM system. Note that I am using the term “policy” as an abstract term, to denote one of the several options to determine linkage.

Some examples of linkage policies are listed below:

  1. Link based on a match between one or more independently verified claims in both identities.
  2. Link based on identity proofing of both identities.
  3. Link based on external knowledge (outside the scope of the IAM system).

Login Experience

Once the account linking and/or account merging process has taken place, the login behavior of the centralized IAM system will be different. This difference can be categorized into 3 types:

  1. Account linking with no credential unification: No change in login behavior. Continue to login with and share the relevant relying party-specific identity to the relying party.
  2. Account linking with credential unification, which includes
    • Allowing login only with unified credential and share relying party-specific identity with the relying party.
    • Allowing login with unified credentials as well as with relying party-specific credentials for some time, and share relying party-specific identity with the relying party.
  3. Account merging: Login with and share unified identity to the relying party.

In (2a) and (3) above, a new identity has to be in place in the new IAM system before logging into any relying party. Selection of the identity that needs to be presented to the relying party can be based on user input or configuration. The login user interface for each relying party should be designed to reflect a consistent experience to the end user, so that it is not confusing as to which credentials to use. As the end user is dealing with multiple sets of credentials, the login user experience should be clear enough for the end user to understand.


This article provides a high-level discussion of the different approaches on how multiple digital identities that are used to represent a single physical identity across multiple applications and services are linked together in the IAM system they are presented in. WSO2 Identity Server is one such open source IAM product, distributed under the Apache 2.0 license. Possessing a powerful identity management framework, WSO2 Identity Server has the ability to play the role of a centralized identity provider and is able to support all the approaches for local account linking discussed in this article.


About Author

  • Johann Nallathamby
  • Director - Solutions Architecture
  • WSO2