-
Notifications
You must be signed in to change notification settings - Fork 498
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
02f0c3c
commit ee8feaa
Showing
1 changed file
with
13 additions
and
16 deletions.
There are no files selected for viewing
29 changes: 13 additions & 16 deletions
29
docs/authentication/enterprise-connections/account-linking.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,37 +1,34 @@ | ||
--- | ||
title: Account Linking | ||
title: Account linking | ||
description: Learn how Clerk handles account linking during Enterprise SSO. | ||
--- | ||
|
||
Account Linking is a process that Clerk uses to ensure a smooth sign-in and sign-up experience using Enterprise 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. | ||
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. It enables seamless sign-in using Enterprise SSO alongside other authentication methods like username/password. Clerk automatically attempts to link accounts that share the same email address, assuming a single owner for each email. | ||
|
||
## 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 Enterprise account with any existing Clerk account that shares the same email address. | ||
When a user attempts to sign in or sign up, Clerk checks if the email address from the Identity Provider (IdP) matches an existing account and attempts to link them. Email addresses from IdPs are considered verified by default. | ||
|
||
In the following sections, we'll look at the different scenarios that can occur during this process and explain how Clerk handles each one. | ||
|
||
> [!NOTE] | ||
> Email addresses from identity providers are considered verified by default. | ||
The following sections describe different scenarios that can occur during this process and explain how Clerk handles each one. | ||
|
||
![Flow chart of the SAML SSO account linking process in various scenarios.](/docs/images/authentication/account-linking-flow-saml.webp) | ||
|
||
### Email is verified in Clerk | ||
|
||
When a user signs into your app using a identity provider that returns a matching verified email address, Clerk links the Enterprise account to the existing account and signs the user in. This even applies to password-protected accounts, as the Enterprise sign-in process automatically bypasses password verification. | ||
When a user signs into your app using an IdP that returns a matching verified email address, Clerk automatically links the Enterprise account to the existing account and completes the sign-in process. This includes accounts protected by passwords, as the Enterprise sign-in flow automatically bypasses password verification. | ||
|
||
### Email is unverified and verification isn't required | ||
### Email is not verified 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. | ||
By default, Clerk requires email verification at sign-up. For instances that have disabled this behavior, there is a possibility that an account may be created using an unverified email address. | ||
|
||
To allow unverified email addresses for your instance: | ||
To configure email verification at sign-up: | ||
|
||
1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) | ||
1. In the navigation sidebar, select **Email, Phone, Username**. | ||
1. In the Clerk Dashboard, navigate to the [**Email, Phone, Username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page. | ||
1. Next to **Email address**, select the settings icon and uncheck the **Verify at sign-up** toggle. | ||
|
||
When a user signs into your app using a identity provider, Clerk links the Enterprise 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 Enterprise sign-in process automatically bypasses password verification. | ||
When a user signs into your app using an IdP, Clerk automatically links the Enterprise account to the existing account by **also verifying the existing email address** and signing the user in. This includes accounts protected by passwords, as the Enterprise sign-in flow automatically bypasses password verification. | ||
|
||
### Email is unverified | ||
### Email is not verified | ||
|
||
When a user signs into your app using a identity provider that returns a matching unverified email address, Clerk doesn't link the Enterprise account to the existing account, but instead signs the user up and creates a completely new account. | ||
When a user signs into your app using an IdP that returns a matching unverified email address, Clerk doesn't link the Enterprise account to the existing account, but instead signs the user up and creates a completely new account. |