diff --git a/docs/authentication/enterprise-connections/account-linking.mdx b/docs/authentication/enterprise-connections/account-linking.mdx index c5a55372fc..951170b1ad 100644 --- a/docs/authentication/enterprise-connections/account-linking.mdx +++ b/docs/authentication/enterprise-connections/account-linking.mdx @@ -7,9 +7,9 @@ Account linking is the process of connecting multiple user accounts from differe ## How it works -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. +When a user attempts to sign in or 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. -The following sections describe different scenarios that can occur during this process and explain how Clerk handles each one. +The following sections explain the different scenarios that can occur during this process and 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) @@ -19,12 +19,12 @@ When a user signs into your app using an IdP that returns a matching verified em ### Email is not verified and verification isn't required -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. +By default, Clerk requires email verification at sign-up. For instances that have disabled this behavior, there's a possibility that an account may be created using an unverified email address. To configure email verification at sign-up: 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. +1. Next to **Email address**, select the settings icon and disable the **Verify at sign-up** toggle. When a user signs into your app using an IdP, Clerk automatically links the Enterprise SSO 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 SSO sign-in flow automatically bypasses password verification. diff --git a/docs/authentication/enterprise-connections/authentication-flows.mdx b/docs/authentication/enterprise-connections/authentication-flows.mdx index 24cdd2652e..f1d62c9895 100644 --- a/docs/authentication/enterprise-connections/authentication-flows.mdx +++ b/docs/authentication/enterprise-connections/authentication-flows.mdx @@ -3,7 +3,7 @@ title: Enterprise SSO authentication flows description: Learn about the Enterprise SSO authentication flows. --- -Currently, there are two types of Enterprise SSO connections: [EASIE](#easie) and [SAML](#saml). +There are two types of Enterprise SSO connections: [EASIE](#easie) and [SAML](#saml). ## EASIE @@ -13,7 +13,7 @@ EASIE connections support the authentication flows described at [easie.dev](http The SAML protocol supports two methods to start an SSO flow: [Service Provider-initiated (SP-initiated)](#service-provider-initiated-flow-recommended) and [Identity Provider-initiated (IdP-initiated)](#identity-provider-initiated-flow). -For the best security practices, Clerk recommends using the SP-initiated flow wherever possible. If you decide to enable IdP-initiated flows, ensure that proper [security measures](#clerks-security-measures), such as MFA and short validation periods, are in place to mitigate the associated risks. +For the best security practices, it's recommended to use the SP-initiated flow wherever possible. If you decide to enable IdP-initiated flows, ensure that proper [security measures](#clerks-security-measures), such as MFA and short validation periods, are in place to mitigate the associated risks. ### Service Provider-initiated flow (recommended) @@ -21,14 +21,14 @@ In an SP-initiated flow: - The user starts the authentication process from your application (Service Provider, or SP), by providing their email address. - The user is redirected to the SAML provider (Identity Provider, or IdP) where they must authenticate. -- After successful authentication, the user is redirected back to your application, gaining access to their account. +- After successful authentication, the user is redirected back to your app, gaining access to their account. ### Identity Provider-initiated flow In an IdP-initiated flow: -- The user starts the authentication flow from the SAML provider (IdP) by selecting which application (SP) they want to access. -- The user is redirected to the application of their choice, gaining access to their account. +- The user starts the authentication flow from the SAML provider (IdP) by selecting which app (SP) they want to access. +- The user is redirected to the app of their choice, gaining access to their account. > [!NOTE] > IdP-Initiated flow carries a [security risk](#risks-of-id-p-initiated-flow). It is recommended to use an SP-Initiated flow whenever possible. @@ -46,7 +46,7 @@ To allow IdP-initiated flows for your SAML connection: While IdP-initiated flows might offer convenience, they are also susceptible to security risks, such as [meddler-in-the-middle (MITM) attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). A bad actor might hijack the IdP response to gain access to a compromised account. -When enabling an IdP-initiated flow, it is possible for Clerk to receive unsolicited authentication requests, which neither the SP nor IdP can verify were initiated by the specified user. Additionally, a bad actor could intercept the IdP response and replace it, performing a CSRF attack to sign in as the attacker. +When enabling an IdP-initiated flow, it's possible for Clerk to receive unsolicited authentication requests, which neither the SP nor IdP can verify were initiated by the specified user. Additionally, a bad actor could intercept the IdP response and replace it, performing a CSRF attack to sign in as the attacker. #### Clerk's security measures @@ -55,4 +55,4 @@ To mitigate the risks associated with IdP-initiated flows, Clerk implements seve - **Unsolicited `InResponseTo` attribute**: Clerk ensures that unsolicited responses don't contain an `InResponseTo` attribute, in accordance with the [SAML 2.0 profiles specification](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). This prevents bad actors from stealing a response used in an SP-initiated flow and using it in an IdP-initiated flow. - **Replay detection**: Clerk consumes and remembers each response to prevent re-use. This ensures that bad actors cannot steal and reuse a response to gain access to a user's account. - **Multi-factor authentication**: Clerk supports [multi-factor authentication (MFA)](/docs/authentication/configuration/sign-up-sign-in-options#multi-factor-authentication) for SAML IdP-initiated flows. MFA requires users to provide two or more forms of verification, which significantly enhances security by reducing the risk of unauthorized access. -- **Use small validation periods**: Each SAML response contains a timestamp indicating when it was issued and when it will expire. Since IdP-initiated flows are expected to be completed within seconds, validation periods must be as small as possible to prevent attacks. Common IdP providers such as Azure, Google, and Okta handle this by default. However, if you are using a custom IdP, you must ensure that the validation periods are set correctly. +- **Use small validation periods**: Each SAML response contains a timestamp indicating when it was issued and when it will expire. Since IdP-initiated flows are expected to be completed within seconds, validation periods must be as small as possible to prevent attacks. Common IdP providers such as Azure, Google, and Okta handle this by default. However, if you're using a custom IdP, you must ensure that the validation periods are set correctly. diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index b0c8d184c8..c59dc339ed 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -34,7 +34,7 @@ For _development instances_, Clerk uses preconfigured shared credentials and red 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For specific domains**. 1. Under **EASIE**, select **Google** as the identity provider. -1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. +1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. ## Configure for your production instance diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index ae47a18e07..9619640521 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -34,7 +34,7 @@ For _development instances_, Clerk uses preconfigured shared credentials and red 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select the **Add connection** button, and select **For specific domains**. 1. Under **EASIE**, select **Microsoft** as the identity provider. -1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. +1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. ## Configure for your production instance @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For specific domains**. 1. Below EASIE, select **Google** as the identity provider. - 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. + 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. 1. Save the **Redirect URI** somewhere secure. diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 70d88ffe7e..6120df7a3e 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -11,7 +11,7 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth ### Allow subdomains -Authenticating via SAML SSO requires the user's email address domain to match the exact domain the SAML connection has been configured with. By default, subdomains are not supported. For example, a user with the email address `john@sales.example.com` would not be able to use a SAML connection with the `example.com` domain in order to authenticate. +Authenticating via SAML SSO requires the user's email address domain to match the exact domain the SAML connection has been configured with. By default, subdomains are not supported. For example, a user with the email address `john@sales.example.com` wouldn't be able to use a SAML connection with the `example.com` domain to authenticate. To configure subdomains for a SAML connection: @@ -35,43 +35,43 @@ The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _ ### Automatic deprovisioning -Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the application. +Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the app. Within 10 minutes of a user being removed from the OpenID provider (e.g. [suspendeded](https://support.google.com/a/answer/33312?hl=en) or [deleted](https://support.google.com/a/answer/33314?hl=en) via Google Workspace, or [deleted](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-create-delete-users#delete-a-user) via Microsoft Entra), Clerk will recognize that the user has been deprovisioned and will revoke that user's existing sessions. -It is ultimately the application's responsibility to handle this unauthenticated state and display something appropriate to the user. For example, Next.js applications using [`auth.protect()`](docs/references/nextjs/auth#auth-protect) will automatically redirect the user to the sign-in page. +It is ultimately the app's responsibility to handle this unauthenticated state and display something appropriate to the user. For example, Next.js apps using [`auth.protect()`](docs/references/nextjs/auth#auth-protect) will automatically redirect the user to the sign-in page. ## SAML vs. EASIE The primary security difference between EASIE SSO and SAML SSO is that EASIE depends on a multi-tenant identity provider, while SAML depends on a single-tenant identity provider. Relying on a multi-tenant provider **increases** the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. While Clerk implements [measures to address this risk](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), apps that require single-tenant IdPs should opt for SAML. -Read more in the [EASIE docs](https://easie.dev#security). +For more information, see the [EASIE docs](https://easie.dev#security). ## Frequently asked questions (FAQ) ### I've enabled other strategies but they don't work -A Clerk application can have multiple authentication strategies, but a domain that enables Enterprise SSO can not. Once Enterprise SSO is enabled for a domain, there can be no other authentication methods for that specific domain. This is in line with an organization's intent to manage their users' identity from one place. This will allow your Clerk application to enable Enterprise SSO connections for certain domains while others use non-Enterprise SSO methods depending on each organization's needs. +A Clerk app can have multiple authentication strategies, but a domain that enables Enterprise SSO can't. Once Enterprise SSO is enabled for a domain, there can be no other authentication methods for that specific domain. This is in line with an organization's intent to manage their users' identity from one place. This allows your Clerk app to enable Enterprise SSO connections for certain domains while others use non-Enterprise SSO methods depending on each organization's needs. ### Will Enterprise SSO work for my existing users? -Yes, Enterprise SSO will work for your existing users as well! If you enable SAML or EASIE, any existing users with an email address that matches the SAML or EASIE Connection domain will have to authenticate on the IdP side and an Enterprise Account will be linked to their existing account. +Yes, Enterprise SSO will work for your existing users as well! If you enable SAML or EASIE, any existing users with an email address that matches the SAML or EASIE connection domain will have to authenticate on the IdP side and an Enterprise account will be linked to their existing account. ### What happens if I have multi-factor enabled at Clerk? -This will work: Once the user comes back from the IdP, they will need to go through the extra factors of authentication. This is in case you need to add extra factors on top of what your IdP supports (or in case they don't). You can choose to not enable this feature if you wish. +Once the user returns from the IdP, they will need to complete additional authentication factors. This is useful if you want to add extra factors beyond what your IdP supports or if your IdP doesn’t support them. This feature is optional and can be disabled if not needed. ### What happens if I delete the Enterprise Connection? Will my users be deleted? -The users will not be deleted, so your application will not break. However, they will need to use another [strategy](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) such as password, email OTP, etc., to authenticate themselves moving forward. +The users will not be deleted, so your app will not break. However, they will need to use another [strategy](/docs/authentication/configuration/sign-up-sign-in-options#authentication-strategies) such as password or email to authenticate themselves moving forward. ### Does Clerk support IdP-initiated SSO? -Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/enterprise-connections/authentication-flows). +Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. For more information, see the [authentication flows guide](/docs/authentication/enterprise-connections/authentication-flows). ### How much does it cost? -For development instances, Enterprise Connections will always be free, but capped to 5. +For development instances, Enterprise connections are always free but limited to a maximum of 5. Production instances require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for more information.