Account linking for OAuth

Account linking is the process of connecting multiple user accounts from different services or platforms, allowing users to access various services with a single set of credentials. By using the email address as the common identifier, Clerk automatically attempts to link accounts whenever possible. Account linking is triggered when an OAuth 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 OAuth 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 address is verified in both OAuth and Clerk

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

Email address is verified in Clerk but not in OAuth

When a user signs in to your app using an OAuth provider that returns an unverified email address, Clerk will initiate a verification process. Once the email address is verified, the OAuth account is linked to the existing one, and the user is signed in.

Email address is unverified in Clerk

By default, users are required to verify their email addresses before they can sign up.

If you disabled the Verify at sign-up option in the Clerk Dashboard⁠, users will be able to sign up without verifying their email addresses.

When a user signs up with an unverified email address and later attempts to sign in with an OAuth provider, Clerk implements security measures to prevent potential account takeovers. For example, if an account was created with an unverified email/password combination and the user later signs in with Google (where the email is verified), Clerk will prompt the user to change their password before linking the accounts. This process begins with email verification, regardless of the method used. After successful verification, Clerk may require additional steps, such as validating existing connections or passwords, to ensure the account's security. These measures are in place because Clerk cannot confirm the original ownership of the account, which could otherwise lead to unauthorized access.

Users with different email addresses

If a user has a different email from the one associated with the OAuth account, they can manually associate the two by following these steps:

1. Sign in to their Clerk application with the account that uses their main email address.
2. In the <UserProfile />, add the different email.

After following these steps, the user's OAuth accounts associated with both their primary and added email addresses will be linked to their main account.