Account Linking Recipes

When using OAuth and OpenID Connect, authentication works out-of-the-box in a basic way, perhaps via an option for users to register, then sign in with a username and password. This does not provide very cutting edge authentication though, so most companies will want to provide more modern and secure options. You will then need to refine your authentication flows, and enable users to reliably migrate to different authentication methods. This requires an understanding of how user account data is managed by your Identity and Access Management (IAM) system.

User Account Data

User accounts can be created in multiple ways, such as a user registering themselves, an administrator application using System for Cross-domain Identity Management (SCIM) APIs, or by creating an account that exists in another system after the user's first login. The user will then have an initial main account record with fields such as these. Over time the account data can be extended with additional data, including devices associated to the user.

Access Tokens

After authentication, user facing applications will then send access tokens to your APIs, via an API gateway. APIs will then receive a JWT access token. This will contain a subject claim to identify the user, and this value must remain the same, regardless of how the user authenticates:

{
  "jti": "840d6604-74ba-450c-828a-9c2d9978aeec",
  "delegationId": "710317fb-7930-4cd0-8dbe-01c2192e9889",
  "exp": 1665564808,
  "nbf": 1665564508,
  "scope": "openid profile orders_read",
  "iss": "https://c81d-2-26-218-24.eu.ngrok.io/oauth/v2/oauth-anonymous",
  "sub": "642a797c311f0b7aef3db4e0a292bc69b924e6496d1e87aa3b28672c01611da7",
  "aud": "demo-client",
  "iat": 1665564508,
  "purpose": "access_token"
}

Account Linking

When a user authenticates, the primary authentication factor identifies the user. To improve security or user experience, you may decide to give people choices on which primary authenticator factor they use. If a user's main account was created via a username and password login, and they then perform subsequent logins with Google and Microsoft Entra ID, this should result in storage similar to the following:

Rather than duplicate account records, new linked accounts are created. The combination of provider and subject uniquely identifies a user on subsequent logins, in terms of their existing account record. This enables the IAM system to issue the same subject claim in access tokens issued, for use in your APIs. This is an essential behavior, and you should never need to deal with account linking in your application code.

Meeting this requirement requires you to use the extensibility features of your IAM system. In the Curity Identity Server this is done using Authenticators and Authentication Actions. These are composed together to form a workflow that can include both custom data and custom logic. Additional authentication factors can also be used, and these occur after the account has been identified, so do not affect account linking.

Social Logins

The first main account linking use case is often to enable an alternative method of authentication in addition to passwords. This might be a social provider such as Google or Facebook, and the user can be prompted to select their preferred authentication method:

When an existing user first authenticates via Facebook, you need to implement logic to ensure that accounts are linked reliably. A robust way to do this is to involve the user and ask them to prove their identity by their existing authentication method, when first onboarding to a new one. The Account Linking With Social Identity Providers tutorial provides a complete walkthrough of managing this scenario in the Curity Identity Server. This ensures the correct data outcome for existing users, while new users register via the HTML Form:

Federated Logins

You may want to avoid a registration form for new users, if they already exist in another system, such as corporate accounts stored in Microsoft Entra ID. In this case you can simply auto-create the account if required, when the user first signs in, using authentication attributes provided by the external system. Future changes to the primary authentication factor can then be managed in the same way as for social logins. The Account Creation After Login tutorial explains how to implement this flow with the Curity Identity Server.

Dynamic Authentication

To take more complete control over authentication behavior for new and existing users, you can first identify a user with the username authenticator, then look up user account data, then use user attributes to decide which authenticaiton method(s) to use for that user.

This approach is useful when performing migrations, such as the current trend towards passwordless authentication via WebAuthn or passkeys. With the right extensibility, the IAM system should allow users to opt-in to a newer authentication method when it suits them, or to continue using their current authentication method otherwise.

The Migrating to Passkeys tutorial provides a walkthrough of this use case, including an end-to-end code example that can be run on a development computer. The following authenticators and actions are used. The overall flow handles both new and existing users.

Conclusion

Account linking is the process of designing a main account record, while also allowing room for alternative or more cutting-edge authentication methods in future. When evaluating an IAM system, it is therefore recommended to validate early that the correct behavior is supported. In the Curity Identity Server, many built-in actions are provided to enable you to compose authentication workflows in a drag-and-drop manner. You can also go deeper and use Plugins if you need to implement completely bespoke behavior. All of this ensures that you have full control over your identity data, during and after authentication.

Published: 2022-11-02

Gary Archer

Product Marketing Engineer at Curity