Linking user accounts

Background

User accounts and sessions can take one of three common forms and potentially a combination of each:

1. All user accounts are completely distinct - This is the most common. A user with multiple accounts needs to log out of their first account in order to log into their second one. Further, the data and identities between each of these accounts is completely separate, there is no overlap, and from both--the users and app's perspectives--these are distinct.
2. Linking user identities - A user has a single account, but that account might be a grouping of multiple identities. Consider the case that a user logs in to your platform both their Google account as well as their Twitter account. These aren't separate users, but they are clearly separate identities. Authress provides a strategy to link these identities so that irrespective of how a user logs in, they are still a single user.
3. Multiple user accounts - A lesser common model, is that your platform and UI can allow users to log into multiple user accounts at the same time. In the UI, the user will see resources from both accounts, although the data in the accounts remains separate. This provides a great experience for users that use the same tool in different contexts such as professionally and personally at the same time.

Distinct user accounts

In Authress, this is the default. Every login and user account is uniquely generated based on the Authress connection such as Login with Google. No further action needs to be taken to enable this functionality.

A user gets unique credentials for this identity, for the specified application from the Authress connection. If the user wishes to have multiple user accounts, they must log out, discarding their current credentials, and fetch new ones by logging in again.

In most circumstances, this is the best choice, especially when a user uses multiple browsers or multiple devices when interacting with this data. Most apps should use this solution.

Linking user identities

(SDK keyword: linkIdentity)

In some cases, users will want to link accounts from multiple identity providers. While this is common in the consumer space with consumer apps, for business applications it is rarely necessary. This is because the user's account is tied to their corporate identity and linking it with a personal login method would not make sense. (In lots of situations it might be against the corporate policy and security posture.) However, in some scenarios they might want to take their data with them. Having the ability to link the user's account to your current business' corporate identity might be exactly the experience your app needs. This is often required to support migrating user account into Authress from external provider.

To link identities, patch the user identities endpoint with the other identity using the user's Authress access token. (Note: performing this action will unlink the data associated with the other account. This is recoverable using the Authress advanced user tools, but in general great care should be taken before linking accounts).

(Application UI) Link a user's multiple identities

import { LoginClient } from '@authress/login';
const loginClient = new LoginClient({
  // Both of these properties can be found and configured at:
  // https://authress.io/app/#/manage?focus=applications
  authressLoginHostUrl: 'https://auth.yourdomain.com',
  applicationId: 'YOUR_APPLICATION_ID'
});

// Then call the `linkIdentity` method
await loginClient.linkIdentity({
  linkIdentity: true,
  connectionId: 'IDENTITY_TO_LINK_CONNECTION_ID',
  redirectUrl: window.location.href
});

The user will be navigated to the specified connectionId, to complete their login. When the user completes the flow started by this authentication call, the original user's identity and the identity attached to this connection will be linked.

Multiple user accounts in the same UI

(SDK keyword: multiAccount)

When a user has multiple user identities each associated with a different user account, a better experience is to enable the user to consume data related to either identity. Linking the identities would not be the correct course of action because there is separate data stored with each one, and those accounts might belong to two different owners. Consider the an account owned by a Corporate IdP and one the user uses privately. A good example of this is a Mail app. Everyone has both personal and professional email inboxes, and these mailboxes are not shared. Unless explicitly set up to be shared with each other, they are separate and distinct accounts.

To handle the multiple user experiences, the Authress Login SDK will generate multiple sessions each with their own user identity and access token.

(Application UI) Enable concurrent user identities

import { LoginClient } from '@authress/login';
const loginClient = new LoginClient({
  // Both of these properties can be found and configured at:
  // https://authress.io/app/#/manage?focus=applications
  authressLoginHostUrl: 'https://auth.yourdomain.com',
  applicationId: 'YOUR_APPLICATION_ID'
});

// This will redirect the user to the specified connection login UI,
// track their session with Authress, and then redirect back to your specified
// redirectUrl. By default we redirect users back to where they started,
// however, usually you’ll want to specify the next location they should go.
await loginClient.authenticate({
  multiAccount: true,
  connectionId: 'SELECTED_CONNECTION_ID', redirectUrl: window.location.href
});

// Once the user returns to your site, you’ll want to get the necessary credentials.
// These should always be fetched by using the token getter:
const userToken = await loginClient.getToken();