Skip to content

Commit

Permalink
update account linking
Browse files Browse the repository at this point in the history
  • Loading branch information
alexisintech committed Nov 19, 2024
1 parent 02f0c3c commit ee8feaa
Showing 1 changed file with 13 additions and 16 deletions.
29 changes: 13 additions & 16 deletions docs/authentication/enterprise-connections/account-linking.mdx
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.

0 comments on commit ee8feaa

Please sign in to comment.