Account Linking

Account Linking is a process that Clerk uses to ensure a smooth sign-in and sign-up experience using SAML SSO and other methods (e.g. username/password). By using the email address as the common identifier, Clerk automatically attempts to link accounts whenever possible. Account linking triggers when a SAML provider returns an email address that matches an existing account, assuming a single owner for each email address.

How it works

When a user attempts to sign in or sign up, Clerk first checks the provided email address. Clerk will attempt to link the SAML account with any existing Clerk account that shares the same email address.

In the following sections, we'll look at the different scenarios that can occur during this process and explain how Clerk handles each one.

Email is verified in Clerk

When a user signs into your app using a SAML provider that returns a matching verified email address, Clerk links the SAML account to the existing account and signs the user in. This even applies to password-protected accounts, as the SAML sign-in process automatically bypasses password verification.

Email is unverified and verification isn't required

For instances that allow account creation without email verification at sign-up, there is a possibility that an account may be created using an unverified email address.

To allow unverified email addresses for your instance:

1. Navigate to the Email, Phone, Username page in the Clerk Dashboard.

2. Select the settings cog icon next to "Email address" and uncheck the Verify at sign-up toggle.

When a user signs into your app using a SAML provider, Clerk links the SAML account to the existing account by also verifying the existing email address and signs the user in. This even applies to password-protected accounts, as the SAML sign-in process automatically bypasses password verification.

Email is unverified

When a user signs into your app using a SAML provider that returns a matching unverified email address, Clerk doesn't link the SAML account to the existing account, but instead signs the user up and creates a completely new account.