How To: Federated Account Linking

Introduction

This article provides an introduction to federated account linking, which refers to linking the digital identifiers of an identity in multiple federated identity providers to a digital identifier of the same identity in the resident identity provider. Federated account linking is one of the key requirements under federated identity management. The digital identifier in the resident identity provider is also known as the local identifier.

I will explore some common approaches that are used for federated account linking - however, this article does not seek to provide intricate details on how each of these approaches can be implemented. As you continue to read this article, you may be able to draw parallels with approaches on how password resets or email account confirmations are performed in most identity and access management (IAM) products.

These approaches can be broadly categorized into two areas:

1. Admin initiated
2. Self-serviced

Of the two approaches, self-serviced approaches are generally more popular due to lower administrative overhead.

Admin Initiated

Admin initiated linking can be further divided based on the point at which the accounts are linked in the user lifecycle. Generally there are 2 points in the user life cycle where this could be done:

1. At the point of account provisioning by the administrator
2. Admin-initiated account linking for existing accounts in resident identity provider

Admin initiated linking has the advantage of being carried out in bulk for multiple users as well. This can be a useful technique for forcing all users to follow the linking process at the initial commissioning of a system or request the remaining users to follow the linking process before an old system is decommissioned.

Self-serviced

Similar to admin initiated linking, self-serviced linking can be further divided based on the point at which the accounts are linked in the user lifecycle. Generally there are 3 points in the user 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

Although this technique is commonly followed in customer identity and access management (CIAM), it is sometimes useful in workforce IAM as well. For example, imagine a new application is introduced to the organization’s ecosystem that your workforce is allowed to access. However, if this introduction requires an account to be provisioned in the application, a self-registration process may be prefered in order to avoid the administrative overhead of provisioning new accounts for the existing workforce.

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 on the first login from the respective federated identity provider. This is used in both CIAM and workforce IAM.

Link from self-service portal

In this case, existing account holders can login to the user portal and link their federated accounts. Usually this technique is used as an optional step to gather additional information about the user to enrich the user’s profile, and not to determine access to an application. This is a common technique in social connect use cases of CIAM.

Proving Ownership

In all three self-serviced linking approaches we discussed above, there is an important requirement for the user - which is to prove ownership of both local and federated accounts that he/she is trying to link. This is formally known as identity proofing.

Link on self-registration: there is no local account as yet to prove ownership. However, the user must still prove ownership of the respective federated account he/she is trying to link, by initiating a federated login flow.

Just-In-Time Linking: for existing accounts, the ownership of the federated account would have been automatically proven by the federated login flow. However, the user must also prove ownership of the respective local account by authenticating to the resident identity provider using the local account.

Linking from self-service portal: by logging into the self-service portal, the user automatically proves the ownership of the local account. Yet the user must also prove ownership of the respective federated account by initiating a federated login flow.

To authenticate using the local account, users can use their passwords - if passwords have been provisioned in the local account. If the use case does not require password provisioning, 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 local account for the purpose of account linking.

Linkage Policies

Whichever approach you choose to use from above, you will essentially use one or more claims of the user provided from the federated identity provider and verify that against a policy that has been configured in the resident identity provider. Note that I am using the term “policy” as an abstract term, to denote one of the several options to determine linkage. Also it is advisable to use a set of immutable claims for the linking. Choosing mutable claims has the possibility of losing the linkage, if the value of the claim is modified in the federated identity provider without notifying the resident identity provider.

Some examples of linkage policies are listed below:

1. Link based on a match between one or more verified claims asserted by the federated identity provider and independently verified claims by the resident identity provider
2. Link based on the combination of one or more verified claims asserted by the federated identity provider and proving ownership of a local account in the resident identity provider
3. Link based on one or more verified claims asserted by the federated identity provider for Just-In-Time provisioned accounts
4. Link based on external knowledge (outside the scope of the resident identity provider and federated identity provider)

Claim Verification

Claim verification is an important part of account linking. If the asserted claims are already verified, it makes the linking process much easier. If they are not, then you may have to make sure the claims are first verified in order to link.

Following are some examples of how claim verification is implemented:

1. Initiate a federated authentication flow that returns an assertion with the claims in question along with its verification status
2. Call a HTTP endpoint with user credentials that returns an assertion with the claims in question along with its verification status
3. Trigger a workflow that involves calling into multiple external systems and/or multi-level human approvals for claim verification
4. In some scenarios the claims asserted by the federated identity provider are not guaranteed to be verified. In those cases, it could be the resident identity provider’s responsibility to independently verify the claims before linking the account. These could include email address verification, mobile number verification, etc.

User Experience

In some of the claim verification methods we have observed so far, such as the ones that involve asynchronous user interaction or a long-running workflow, the users do not receive synchronous access to the application. In these cases user experience is important.

A common problem that you would face is that at times the entire provisioning/linking process is not executed in one atomic step. In such cases, it is important to provide a self-service capability for the user to trigger the linking process from outside of the provisioning process as well. A common way of achieving this is by using email communication. For example, if the linking has to follow a federated authentication flow, once the user account has been provisioned to the resident identity provider, you can keep the account status as locked, and send a federated account claim verification link to the user’s provided email address. Clicking this link will initiate a federated authentication flow with the federated identity provider, that brings back some verified claims in a assertion which can be used to link the accounts and automatically log the user into the originally intended application.

Another problem you could encounter when using workflows is if the user is informed about the outcome of the account provisioning/linking workflow and allowed to complete the process to gain access to the application he/she originally intended to use. In such cases, email communication can be useful.

Since the verification process may take anything from a few minutes to a couple of days, depending on the use case, it is best to show an informative message to the user in the user interface saying that, a request (account provisioning/linking/verification) has been submitted, and on successful processing of the request, he/she will receive an email with further instructions to the email address provided.

For any kind of links or codes sent to a user’s email address or mobile phone number, there also needs to be a self-service capability for the user to request resending the link or code - in case the previous one has expired or the user has accidentally deleted the message or the message has not arrived at all due to a networking failure.

When the use case requires multiple claims to be verified, such as ownership of a federated account and email address, they can be combined and executed in a single step in the process, instead of sending two separate messages. You need to make sure that there is at most only one asynchronous interaction needed in the process.

If account linking has to be enforced in order to gain access to an application, the login step could function as a claim verification checkpoint to handle this. At this point, users can be requested to verify claims in order to link their federated accounts before proceeding with the login process.

Summary

This article provides a high-level discussion of the different approaches on how federated accounts could be linked to local accounts at the resident identity provider. WSO2 Identity Server (IS) is one such open source IAM product, distributed under the Apache 2.0 license. Possessing a powerful identity management and identity federation framework, WSO2 IS has the ability to play the role of the resident identity provider as described in this article, and is able to support all the approaches for federated account linking we’ve discussed in this post.