Identity Linking

Users have unique email addresses, because each user’s access to their inbox represents ultimate access to all of their credentials and thus services they control. The User object unifies all of the identities they use so that your application does not have to consider different identity systems.

Identity linking is the process in which WorkOS safely deduplicates various credentials across identity providers to offer a single, unified user interface. It does this by using the email address as the unique identifier and access to the email inbox as the source of truth.

A credential is an authentication method in a specific identity provider. For example, WorkOS offers a password credential for users to authenticate with. In this case, WorkOS is the identity provider and password is the authentication method.

Google OAuth is another credential, where Google is the identity provider and OAuth is the authentication method.

Users may use multiple types of authentication methods based on preference, perhaps because one is more convenient to use on one of their devices, or they simply didn’t remember which method they used in the past.

WorkOS ensures all user emails are unique via an email verification process. By default, email verification is required by all users for authentication to succeed. This ensures that verified users are always returned to your application.

When a user signs in with a new credential for the first time, e.g. they sign in through Google OAuth despite already having a password account, WorkOS will safely attach the new credential to the existing user. This is only performed if WorkOS can verify that the user has access to the email inbox referenced by that credential.

WorkOS considers it a security risk if the user cannot verify their email access. For some identity providers, a credential with an email address does not guarantee access to that inbox.

When an IT admin verifies a domain for their organization, it means they have access to create email inboxes. Thus, a verified domain implies the ability to verify all users with that email domain.

In practice, when a domain is verified and an SSO connection is configured, users who sign in through an organization’s IdP are automatically considered email verified if the domain matches. This shortcut reduces friction for your end users.

Not only can a user have multiple credentials, they may also have multiple SSO credentials. This might happen when a user works with multiple organizations that require SSO authentication for all members. In this case, there is still only one User object, but they would choose which organization’s SSO IdP to use when authenticating.

The email verification safety still applies. When the user signs-in for the first time through an SSO IdP where the user’s email address is not a verified domain, the user is asked to verify their email before the SSO credential is linked to their account.

Users without a verified domain must be invited to the organization before they have access via SSO for the first time.