From 4f0a2f3dffb9525f9d510c21239b720e22d6f116 Mon Sep 17 00:00:00 2001 From: Mary Zhong Date: Thu, 14 Nov 2024 09:42:45 -0500 Subject: [PATCH 01/35] feat: First pass at EASIE documentation --- docs/authentication/saml/account-linking.mdx | 14 +++---- .../saml/authentication-flows.mdx | 10 ++++- docs/authentication/saml/overview.mdx | 41 +++++++++++++------ docs/manifest.json | 41 +++++++++++-------- 4 files changed, 68 insertions(+), 38 deletions(-) diff --git a/docs/authentication/saml/account-linking.mdx b/docs/authentication/saml/account-linking.mdx index 69bbce1b04..212448f9f5 100644 --- a/docs/authentication/saml/account-linking.mdx +++ b/docs/authentication/saml/account-linking.mdx @@ -1,24 +1,24 @@ --- title: Account Linking -description: Learn how Clerk handles account linking during SAML SSO. +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 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. +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. ## 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. +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. 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 SAML providers are considered verified by default. +> Email addresses from identity providers are considered verified by default. ![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 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. +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. ### Email is unverified and verification isn't required @@ -30,8 +30,8 @@ To allow unverified email addresses for your instance: 1. In the navigation sidebar, select **Email, Phone, Username**. 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 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. +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. ### 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. +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. diff --git a/docs/authentication/saml/authentication-flows.mdx b/docs/authentication/saml/authentication-flows.mdx index 78a6d58927..2821d4f430 100644 --- a/docs/authentication/saml/authentication-flows.mdx +++ b/docs/authentication/saml/authentication-flows.mdx @@ -1,8 +1,10 @@ --- -title: SAML SSO authentication flows -description: Learn about the SAML SSO authentication flows. +title: Enterprise SSO authentication flows +description: Learn about the Enterprise SSO authentication flows. --- +# SAML + The SAML protocol supports two methods to start an SSO flow: Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated). ## Service Provider-initiated flow (recommended) @@ -61,3 +63,7 @@ Each SAML response contains a timestamp indicating when it was issued and when i ### Conclusion 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—such as MFA, replay detection, and short validation periods—are in place to mitigate the associated risks. + +# EASIE + +EASIE Connections support the authentication flows described at [easie.dev](https://easie.dev). With EASIE, your application can provide enterprise-grade SSO through a multi-tenant OpenID provider. This provides an easier alternative to setting up SAML SSO. diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx index 84d9ab5ead..b9d0cd6c4d 100644 --- a/docs/authentication/saml/overview.mdx +++ b/docs/authentication/saml/overview.mdx @@ -1,24 +1,39 @@ --- -title: Enterprise SSO via SAML -description: Clerk supports Enterprise SSO via the SAML protocol so that you can create authentication strategies for Identity Providers, such as Okta. +title: Enterprise SSO +description: Clerk supports Enterprise SSO via different protocols so that you can create authentication strategies for Identity Providers, such as Okta. --- -Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [SAML SSO authentication flows](/docs/authentication/saml/authentication-flows) and [Account linking](/docs/authentication/saml/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. +Clerk supports Enterprise SSO via the SAML protocol and [EASIE](https://easie.dev), enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [Enterprise SSO authentication flows](/docs/authentication/saml/authentication-flows) and [Account linking](/docs/authentication/saml/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. + +Currently, Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. + +For EASIE connections, Clerk offers integration with Google Workspace and Microsoft Entra ID. Setting up an EASIE connection for production requires custom OAuth credentials, following the same steps outlined in our Google and Microsoft social connection guides: + +- [Google] docs/authentication/social-connections/google +- [Microsoft] docs/authentication/social-connections/azure + +For development, the same shared OAuth credentials supported by Social Connections can be used for EASIE. + +## SAML vs. EASIE + +[EASIE](https://easie.dev) Connections allow for enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to support an easier alternative to fully fledged SAML SSO, without requiring additional configuration in the identity provider and potential sharing of credentials or secrets. + +One of the primary tradeoffs is [security](https://easie.dev#security). Clerk does take steps to [migitate potential security conerns](https://easie.clerkstage.dev/#mitigating-tenant-crossover-vulnerabilities), but applications that must use single-tenant identity providers should use SAML SSO. ## 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. -To support SAML SSO with subdomains, +To support Enterprise SSO with subdomains, 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the SAML connection you want to allow subdomains for. +1. Select the Enterprise Connection you want to allow subdomains for. 1. Select the **Advanced** tab. 1. Toggle on the **Allow subdomains** option. > [!NOTE] -> To enable the **Allow subdomains** option, your SAML connection domain must be an eTLD+1. +> To enable the **Allow subdomains** option, your Enterprise Connection domain must be an eTLD+1. ## Frequently asked questions (FAQ) @@ -26,27 +41,29 @@ To support SAML SSO with subdomains, 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. -### Will SAML work for my existing users? +### Will Enterprise SSO work for my existing users? -Yes, SAML will work for your existing users as well! If you enable SAML, any existing users with an email address that matches the SAML 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. -### What happens if I delete the SAML connection? Will my users be deleted? +### 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. ### Does Clerk support IdP-initiated SSO? -Yes, Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/saml/authentication-flows). +Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/saml/authentication-flows). ### How much does it cost? -For production instances, each active connection costs $50 per month. SAML connections require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for those costs, and the costs of other add-ons or features. +For production instances, each active SAML connection costs $50 per month. SAML connections require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for those costs, and the costs of other add-ons or features. + +EASIE connections are included with the Enahnced Authentication Add-on. -For development instances, SAML connections will always be free, but capped to 5. +For development instances, Enterprise Connections will always be free, but capped to 5. ### Can I get a bulk discount? diff --git a/docs/manifest.json b/docs/manifest.json index 030d8c2fb6..1d3c26dceb 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -490,7 +490,7 @@ ] }, { - "title": "SAML", + "title": "Enterprise Connections", "items": [ [ { @@ -505,25 +505,32 @@ "title": "Account linking", "href": "/docs/authentication/saml/account-linking" }, - { - "title": "Azure", - "href": "/docs/authentication/saml/azure" - }, - { - "title": "Google", - "href": "/docs/authentication/saml/google" - }, - { - "title": "Okta", - "href": "/docs/authentication/saml/okta" - }, - { - "title": "Custom provider", - "href": "/docs/authentication/saml/custom-provider" - }, { "title": "Just-in-Time account provisioning", "href": "/docs/authentication/saml/jit-provisioning" + }, + { + "title": "SAML Guides", + "items": [ + [ + { + "title": "Azure", + "href": "/docs/authentication/saml/azure" + }, + { + "title": "Google", + "href": "/docs/authentication/saml/google" + }, + { + "title": "Okta", + "href": "/docs/authentication/saml/okta" + }, + { + "title": "Custom provider", + "href": "/docs/authentication/saml/custom-provider" + } + ] + ] } ] ] From 8de446a12682f77460dfc69a86ad0372180135ae Mon Sep 17 00:00:00 2001 From: Mary Zhong Date: Fri, 15 Nov 2024 13:32:55 -0500 Subject: [PATCH 02/35] fix: Add create enterprise connection documentation, fix links --- docs/authentication/saml/overview.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx index b9d0cd6c4d..b2a6202488 100644 --- a/docs/authentication/saml/overview.mdx +++ b/docs/authentication/saml/overview.mdx @@ -9,8 +9,8 @@ Currently, Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs For EASIE connections, Clerk offers integration with Google Workspace and Microsoft Entra ID. Setting up an EASIE connection for production requires custom OAuth credentials, following the same steps outlined in our Google and Microsoft social connection guides: -- [Google] docs/authentication/social-connections/google -- [Microsoft] docs/authentication/social-connections/azure +- [Google](docs/authentication/social-connections/google) +- [Microsoft](docs/authentication/social-connections/azure) For development, the same shared OAuth credentials supported by Social Connections can be used for EASIE. @@ -20,6 +20,16 @@ For development, the same shared OAuth credentials supported by Social Connectio One of the primary tradeoffs is [security](https://easie.dev#security). Clerk does take steps to [migitate potential security conerns](https://easie.clerkstage.dev/#mitigating-tenant-crossover-vulnerabilities), but applications that must use single-tenant identity providers should use SAML SSO. +## Creating Enterprise Connections in Clerk Dashboard + +To create an Enterprise Connection, + +1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). +1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. +1. Click on **Add connection** on the top right and select **For specific domains**. +1. Select one of the IdP options for an EASIE or SAML connection. +1. On the next page, enter any required information for the new Enterprise Connection, such as the **domain**. + ## 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. From b8286b75fc4b804a7d1d3b1705de5b6d3639478c Mon Sep 17 00:00:00 2001 From: Mary Zhong Date: Fri, 15 Nov 2024 13:40:38 -0500 Subject: [PATCH 03/35] fix: Allow subdomains only applies for SAML --- docs/authentication/saml/overview.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx index b2a6202488..ab2aad8a84 100644 --- a/docs/authentication/saml/overview.mdx +++ b/docs/authentication/saml/overview.mdx @@ -22,28 +22,26 @@ One of the primary tradeoffs is [security](https://easie.dev#security). Clerk do ## Creating Enterprise Connections in Clerk Dashboard -To create an Enterprise Connection, - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. 1. Click on **Add connection** on the top right and select **For specific domains**. 1. Select one of the IdP options for an EASIE or SAML connection. 1. On the next page, enter any required information for the new Enterprise Connection, such as the **domain**. -## Allow subdomains +## Allow subdomains for SAML 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. -To support Enterprise SSO with subdomains, +To support SAML SSO with subdomains, 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the Enterprise Connection you want to allow subdomains for. +1. Select the SAML Connection you want to allow subdomains for. 1. Select the **Advanced** tab. 1. Toggle on the **Allow subdomains** option. > [!NOTE] -> To enable the **Allow subdomains** option, your Enterprise Connection domain must be an eTLD+1. +> To enable the **Allow subdomains** option, your SAML Connection domain must be an eTLD+1. ## Frequently asked questions (FAQ) From 1545fe53d4c4a9d632a8eefd9f0536a72da6037c Mon Sep 17 00:00:00 2001 From: Mary Zhong Date: Fri, 15 Nov 2024 13:46:43 -0500 Subject: [PATCH 04/35] fix: Reorganize authentication flows page --- .../saml/authentication-flows.mdx | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/authentication/saml/authentication-flows.mdx b/docs/authentication/saml/authentication-flows.mdx index 2821d4f430..921599ce24 100644 --- a/docs/authentication/saml/authentication-flows.mdx +++ b/docs/authentication/saml/authentication-flows.mdx @@ -3,11 +3,15 @@ title: Enterprise SSO authentication flows description: Learn about the Enterprise SSO authentication flows. --- -# SAML +## EASIE + +EASIE Connections support the authentication flows described at [easie.dev](https://easie.dev). With EASIE, your application can provide enterprise-grade SSO through a multi-tenant OpenID provider. This provides an easier alternative to setting up SAML SSO. + +## SAML The SAML protocol supports two methods to start an SSO flow: Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated). -## Service Provider-initiated flow (recommended) +### Service Provider-initiated flow (recommended) In an SP-initiated flow: @@ -15,7 +19,7 @@ In an SP-initiated flow: - 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. -## Identity Provider-initiated flow +### Identity Provider-initiated flow In an IdP-initiated flow: @@ -34,36 +38,32 @@ To allow IdP-initiated flows for your SAML connection: 1. In **Advanced Settings**, enable **Allow IdP-Initiated flow**. A modal will open. Select **Enable** to confirm. 1. Select **Save**. -### Risks of IdP-initiated flow +#### Risks of IdP-initiated flow 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. -### Clerk's security measures +#### Clerk's security measures To mitigate the risks associated with IdP-initiated flows, Clerk implements several security measures: -#### Unsolicited `InResponseTo` attribute +##### 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 +##### 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 +##### 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 +##### 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. -### Conclusion +#### Conclusion 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—such as MFA, replay detection, and short validation periods—are in place to mitigate the associated risks. - -# EASIE - -EASIE Connections support the authentication flows described at [easie.dev](https://easie.dev). With EASIE, your application can provide enterprise-grade SSO through a multi-tenant OpenID provider. This provides an easier alternative to setting up SAML SSO. From e8d6d8ee1340dee0e7f018c69e28b30f2050efda Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 18:12:22 -0300 Subject: [PATCH 05/35] Update page structure to reference 'Enterprise connections' --- .../account-linking.mdx | 0 .../authentication-flows.mdx | 0 .../jit-provisioning.mdx | 0 .../overview.mdx | 0 .../{ => enterprise-connections}/saml/azure.mdx | 0 .../saml/custom-provider.mdx | 0 .../{ => enterprise-connections}/saml/google.mdx | 0 .../{ => enterprise-connections}/saml/okta.mdx | 0 docs/manifest.json | 16 ++++++++-------- 9 files changed, 8 insertions(+), 8 deletions(-) rename docs/authentication/{saml => enterprise-connections}/account-linking.mdx (100%) rename docs/authentication/{saml => enterprise-connections}/authentication-flows.mdx (100%) rename docs/authentication/{saml => enterprise-connections}/jit-provisioning.mdx (100%) rename docs/authentication/{saml => enterprise-connections}/overview.mdx (100%) rename docs/authentication/{ => enterprise-connections}/saml/azure.mdx (100%) rename docs/authentication/{ => enterprise-connections}/saml/custom-provider.mdx (100%) rename docs/authentication/{ => enterprise-connections}/saml/google.mdx (100%) rename docs/authentication/{ => enterprise-connections}/saml/okta.mdx (100%) diff --git a/docs/authentication/saml/account-linking.mdx b/docs/authentication/enterprise-connections/account-linking.mdx similarity index 100% rename from docs/authentication/saml/account-linking.mdx rename to docs/authentication/enterprise-connections/account-linking.mdx diff --git a/docs/authentication/saml/authentication-flows.mdx b/docs/authentication/enterprise-connections/authentication-flows.mdx similarity index 100% rename from docs/authentication/saml/authentication-flows.mdx rename to docs/authentication/enterprise-connections/authentication-flows.mdx diff --git a/docs/authentication/saml/jit-provisioning.mdx b/docs/authentication/enterprise-connections/jit-provisioning.mdx similarity index 100% rename from docs/authentication/saml/jit-provisioning.mdx rename to docs/authentication/enterprise-connections/jit-provisioning.mdx diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx similarity index 100% rename from docs/authentication/saml/overview.mdx rename to docs/authentication/enterprise-connections/overview.mdx diff --git a/docs/authentication/saml/azure.mdx b/docs/authentication/enterprise-connections/saml/azure.mdx similarity index 100% rename from docs/authentication/saml/azure.mdx rename to docs/authentication/enterprise-connections/saml/azure.mdx diff --git a/docs/authentication/saml/custom-provider.mdx b/docs/authentication/enterprise-connections/saml/custom-provider.mdx similarity index 100% rename from docs/authentication/saml/custom-provider.mdx rename to docs/authentication/enterprise-connections/saml/custom-provider.mdx diff --git a/docs/authentication/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx similarity index 100% rename from docs/authentication/saml/google.mdx rename to docs/authentication/enterprise-connections/saml/google.mdx diff --git a/docs/authentication/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx similarity index 100% rename from docs/authentication/saml/okta.mdx rename to docs/authentication/enterprise-connections/saml/okta.mdx diff --git a/docs/manifest.json b/docs/manifest.json index 1d3c26dceb..de1b40e009 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -495,19 +495,19 @@ [ { "title": "Overview", - "href": "/docs/authentication/saml/overview" + "href": "/docs/authentication/enterprise-connections/overview" }, { "title": "Authentication flows", - "href": "/docs/authentication/saml/authentication-flows" + "href": "/docs/authentication/enterprise-connections/authentication-flows" }, { "title": "Account linking", - "href": "/docs/authentication/saml/account-linking" + "href": "/docs/authentication/enterprise-connections/account-linking" }, { "title": "Just-in-Time account provisioning", - "href": "/docs/authentication/saml/jit-provisioning" + "href": "/docs/authentication/enterprise-connections/jit-provisioning" }, { "title": "SAML Guides", @@ -515,19 +515,19 @@ [ { "title": "Azure", - "href": "/docs/authentication/saml/azure" + "href": "/docs/authentication/enterprise-connections/saml/azure" }, { "title": "Google", - "href": "/docs/authentication/saml/google" + "href": "/docs/authentication/enterprise-connections/saml/google" }, { "title": "Okta", - "href": "/docs/authentication/saml/okta" + "href": "/docs/authentication/enterprise-connections/saml/okta" }, { "title": "Custom provider", - "href": "/docs/authentication/saml/custom-provider" + "href": "/docs/authentication/enterprise-connections/saml/custom-provider" } ] ] From 8a7ecd6adbc36e66c7c7d5be6bffbc1c39740918 Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 18:59:09 -0300 Subject: [PATCH 06/35] Refine overview page --- .../enterprise-connections/overview.mdx | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index ab2aad8a84..0c12689e3b 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -1,24 +1,23 @@ --- title: Enterprise SSO -description: Clerk supports Enterprise SSO via different protocols so that you can create authentication strategies for Identity Providers, such as Okta. +description: Clerk provides Enterprise SSO to authenticate users via federated Identity Providers such such as Azure AD, Okta, Google Workspace and more. --- -Clerk supports Enterprise SSO via the SAML protocol and [EASIE](https://easie.dev), enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [Enterprise SSO authentication flows](/docs/authentication/saml/authentication-flows) and [Account linking](/docs/authentication/saml/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. +With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [Enterprise SSO authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [Account linking](/docs/authentication/enterprise-connections/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. -Currently, Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. +Currently, Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. -For EASIE connections, Clerk offers integration with Google Workspace and Microsoft Entra ID. Setting up an EASIE connection for production requires custom OAuth credentials, following the same steps outlined in our Google and Microsoft social connection guides: +For [EASIE](https://easie.dev), Clerk offers integration with Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured credentials and redirect URIs - no other configuration is needed. For production instances, you will need to generate your own Client ID and Client secret, following the same steps outlined in our guides: - [Google](docs/authentication/social-connections/google) - [Microsoft](docs/authentication/social-connections/azure) -For development, the same shared OAuth credentials supported by Social Connections can be used for EASIE. ## SAML vs. EASIE -[EASIE](https://easie.dev) Connections allow for enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to support an easier alternative to fully fledged SAML SSO, without requiring additional configuration in the identity provider and potential sharing of credentials or secrets. +[EASIE](https://easie.dev) allows for enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to support an easier alternative to fully fledged SAML SSO, without requiring additional configuration in the Identity Provider and potential sharing of credentials or secrets. -One of the primary tradeoffs is [security](https://easie.dev#security). Clerk does take steps to [migitate potential security conerns](https://easie.clerkstage.dev/#mitigating-tenant-crossover-vulnerabilities), but applications that must use single-tenant identity providers should use SAML SSO. +A key consideration is [security](https://easie.dev#security). While Clerk implements measures to [address potential security issues](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), applications that require single-tenant Identity Providers should opt for SAML SSO. ## Creating Enterprise Connections in Clerk Dashboard @@ -67,12 +66,10 @@ Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated ### How much does it cost? -For production instances, each active SAML connection costs $50 per month. SAML connections require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for those costs, and the costs of other add-ons or features. - -EASIE connections are included with the Enahnced Authentication Add-on. - For development instances, Enterprise Connections will always be free, but capped to 5. +Production instances require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for more information. + ### Can I get a bulk discount? Yes, [reach out to support](/contact/support){{ target: '_blank' }} to work out a custom plan. From b65ac591f84301ca67bd7b7bb29386b767552961 Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 19:09:23 -0300 Subject: [PATCH 07/35] Run format --- .../enterprise-connections/authentication-flows.mdx | 2 +- docs/authentication/enterprise-connections/overview.mdx | 7 +++---- docs/manifest.json | 2 +- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/authentication/enterprise-connections/authentication-flows.mdx b/docs/authentication/enterprise-connections/authentication-flows.mdx index 921599ce24..d8a86512c8 100644 --- a/docs/authentication/enterprise-connections/authentication-flows.mdx +++ b/docs/authentication/enterprise-connections/authentication-flows.mdx @@ -5,7 +5,7 @@ description: Learn about the Enterprise SSO authentication flows. ## EASIE -EASIE Connections support the authentication flows described at [easie.dev](https://easie.dev). With EASIE, your application can provide enterprise-grade SSO through a multi-tenant OpenID provider. This provides an easier alternative to setting up SAML SSO. +EASIE Connections support the authentication flows described at [easie.dev](https://easie.dev). With EASIE, your application can provide enterprise-grade SSO through a multi-tenant OpenID provider. This provides an easier alternative to setting up SAML SSO. ## SAML diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 0c12689e3b..86b24e43e5 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -12,20 +12,19 @@ For [EASIE](https://easie.dev), Clerk offers integration with Google Workspace a - [Google](docs/authentication/social-connections/google) - [Microsoft](docs/authentication/social-connections/azure) - ## SAML vs. EASIE [EASIE](https://easie.dev) allows for enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to support an easier alternative to fully fledged SAML SSO, without requiring additional configuration in the Identity Provider and potential sharing of credentials or secrets. A key consideration is [security](https://easie.dev#security). While Clerk implements measures to [address potential security issues](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), applications that require single-tenant Identity Providers should opt for SAML SSO. -## Creating Enterprise Connections in Clerk Dashboard +## Add your first Enterprise Connection 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. 1. Click on **Add connection** on the top right and select **For specific domains**. -1. Select one of the IdP options for an EASIE or SAML connection. -1. On the next page, enter any required information for the new Enterprise Connection, such as the **domain**. +1. Select one of the IdP options based on your protocol of choice. +1. On the next page, enter any required configuration information. ## Allow subdomains for SAML diff --git a/docs/manifest.json b/docs/manifest.json index de1b40e009..28b870646d 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -510,7 +510,7 @@ "href": "/docs/authentication/enterprise-connections/jit-provisioning" }, { - "title": "SAML Guides", + "title": "SAML", "items": [ [ { From 4fc16ecc0a0599569cd1f715a979cb6695fc6a97 Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 19:26:02 -0300 Subject: [PATCH 08/35] Add first draft for Google EASIE guide --- .../enterprise-connections/easie/google.mdx | 73 +++++++++++++++++++ docs/manifest.json | 15 ++++ 2 files changed, 88 insertions(+) create mode 100644 docs/authentication/enterprise-connections/easie/google.mdx diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx new file mode 100644 index 0000000000..4f0c5a0b6c --- /dev/null +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -0,0 +1,73 @@ +--- +title: Add Google as a EASIE connection +description: Learn how to integrate Google with Clerk using EASIE SSO. +--- + + + - Use Google to enable SSO via [EASIE](https://easie.dev) for your Clerk app. + + +## Configure for your development instance + +For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. + +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. 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. Select **Add connection**. + +## Configure for your production instance + +For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. + +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). + + + ### Set up an enterprise connection in Clerk + + 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). + 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. + 1. Select the **Add connection** button, 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. Ensure that **Use custom credentials** is toggled on. + + ### Create a Google Developer project + + 1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/). + 1. Select a project or [create a new one](https://console.cloud.google.com/projectcreate). + 1. If the **APIs & Services** page isn't already open, open the menu on the left and select **APIs & Services**. + 1. In the menu on the left, select **Credentials**. + 1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent). + 1. Select the appropriate application type for your project. Most likely, you will choose **Web application**. + 1. In the **Authorized Redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. + 1. Select **Create**. Keep this page open. + + ### Set the Client ID and Client Secret in your Clerk Dashboard + + Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. + + Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Then, select **Add connection**. + + > [!NOTE] + > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Google** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + diff --git a/docs/manifest.json b/docs/manifest.json index 28b870646d..4ba99f0a61 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -509,6 +509,21 @@ "title": "Just-in-Time account provisioning", "href": "/docs/authentication/enterprise-connections/jit-provisioning" }, + { + "title": "EASIE", + "items": [ + [ + { + "title": "Azure", + "href": "/docs/authentication/enterprise-connections/easie/azure" + }, + { + "title": "Google", + "href": "/docs/authentication/enterprise-connections/easie/google" + } + ] + ] + }, { "title": "SAML", "items": [ From 1b76bf18226d9746c98b364b16038a999e2e5f0a Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:13:07 -0300 Subject: [PATCH 09/35] Add first draft for Microsoft EASIE guide --- .../enterprise-connections/easie/google.mdx | 3 - .../easie/microsoft.mdx | 99 +++++++++++++++++++ docs/manifest.json | 4 +- 3 files changed, 101 insertions(+), 5 deletions(-) create mode 100644 docs/authentication/enterprise-connections/easie/microsoft.mdx diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index 4f0c5a0b6c..e21486d740 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -67,7 +67,4 @@ To make the setup process easier, it's recommended to keep two browser tabs open Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Then, select **Add connection**. - - > [!NOTE] - > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Google** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx new file mode 100644 index 0000000000..2671f5ea3d --- /dev/null +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -0,0 +1,99 @@ +--- +title: Add Microsoft as a EASIE connection +description: Learn how to allow users to sign up and sign in to your Clerk app with their Microsoft account using EASIE SSO. +--- + + + - Use Microsoft to enable SSO via EASIE for your Clerk app. + + +Enabling single sign-on (SSO) with Microsoft (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk application with their Microsoft account. + +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). + +## Configure for your development instance + +For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. + +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. Below 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. Select **Add connection**. + +## Configure for your production instance + +For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. + +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). + + + ### Set up an enterprise connection in Clerk + + 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). + 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. + 1. Select the **Add connection** button, and select **For specific domains**. + 1. Below 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. Ensure that **Use custom credentials** is toggled on. + 1. Save the **Redirect URI** somewhere secure. + + ### Create a Microsoft Entra ID app + + > [!TIP] + > If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the [Microsoft Azure portal](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret). + + 1. On the homepage of the [Microsoft Azure portal](https://portal.azure.com/#home), in the **Azure services** section, select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**. + 1. In the sidebar, open the **Manage** dropdown and select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**. + 1. Select **New Registration**. You'll be redirected to the **Register an application** page. + 1. Complete the form as follows: + 1. Under **Name**, enter your app name. + 1. Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**. + 1. Under **Redirect URI (Optional)**, select **Web**. + 1. Select **Register** to submit the form. + + ### Get your client ID and client secret + + Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Azure portal, you'll be redirected to its **Overview**. + + 1. From your app's overview, save the **Application (client) ID** somewhere secure. You'll need it to connect your Microsoft Entra ID app to your Clerk app. + 1. Under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. + 1. Select **New client secret**. In the modal that opens, enter a description and set an expiration time for your secret. + > [!IMPORTANT] + > When your secret expires, your social connection will stop working until you generate a new client secret and add it to your Clerk app. + 1. Save the new client secret's **Value** somewhere secure. You'll add this and your client ID to your Clerk app later. Keep this page open. + + ### Set the Client ID and Client Secret in your Clerk Dashboard + + Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. + + ### Enable OpenID + + To connect your Clerk app to your Microsoft app, set the **Redirect URI** in your Microsoft Azure portal. + + 1. Navigate back to the Microsoft Azure portal. + 1. In the sidebar, open the **Manage** dropdown and select **Authentication**. + 1. Select **Add a platform**. + 1. Select **Web**. + 1. In the **Redirect URIs** field and the **Front-channel logout URL** field, paste the **Redirect URI** you copied from the Clerk Dashboard. + 1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**. + 1. Select **Configure** to save the changes. + diff --git a/docs/manifest.json b/docs/manifest.json index 4ba99f0a61..cd0db6fcb8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -514,8 +514,8 @@ "items": [ [ { - "title": "Azure", - "href": "/docs/authentication/enterprise-connections/easie/azure" + "title": "Microsoft", + "href": "/docs/authentication/enterprise-connections/easie/microsoft" }, { "title": "Google", From 3dc12d81915196e85fb68b44404b707cdc36808d Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:15:37 -0300 Subject: [PATCH 10/35] Fix typo --- docs/authentication/enterprise-connections/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 86b24e43e5..054e222824 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -5,9 +5,9 @@ description: Clerk provides Enterprise SSO to authenticate users via federated I With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [Enterprise SSO authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [Account linking](/docs/authentication/enterprise-connections/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. -Currently, Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. +Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. -For [EASIE](https://easie.dev), Clerk offers integration with Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured credentials and redirect URIs - no other configuration is needed. For production instances, you will need to generate your own Client ID and Client secret, following the same steps outlined in our guides: +For [EASIE](https://easie.dev), Clerk offers integration with Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured credentials and redirect URIs - no other configuration is needed. For production instances, you will need to generate your own Client ID and Client Secret, following the same steps outlined in our guides: - [Google](docs/authentication/social-connections/google) - [Microsoft](docs/authentication/social-connections/azure) @@ -23,7 +23,7 @@ A key consideration is [security](https://easie.dev#security). While Clerk imple 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. 1. Click on **Add connection** on the top right and select **For specific domains**. -1. Select one of the IdP options based on your protocol of choice. +1. Select one of the Identity Provider options based on your protocol of choice. 1. On the next page, enter any required configuration information. ## Allow subdomains for SAML From 94eb9b2676cd990345a1db9ef665f9a412914681 Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:26:14 -0300 Subject: [PATCH 11/35] Fix contact support CTA on overview --- docs/authentication/enterprise-connections/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 054e222824..fdcac2c44f 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -71,4 +71,4 @@ Production instances require the Pro plan and the Enhanced Authentication Add-on ### Can I get a bulk discount? -Yes, [reach out to support](/contact/support){{ target: '_blank' }} to work out a custom plan. +Yes, [contact support](/contact/support){{ target: '_blank' }} to work out a custom plan. From d3e77da22817dbfaabde743dd6d098aaf3e980b9 Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:40:21 -0300 Subject: [PATCH 12/35] Fix broken links --- .../enterprise-connections/jit-provisioning.mdx | 2 +- docs/authentication/enterprise-connections/overview.mdx | 4 ++-- .../enterprise-connections/saml/custom-provider.mdx | 2 +- docs/authentication/saml/overview.mdx | 4 ++-- docs/authentication/social-connections/microsoft.mdx | 2 +- docs/custom-flows/saml-connections.mdx | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/authentication/enterprise-connections/jit-provisioning.mdx b/docs/authentication/enterprise-connections/jit-provisioning.mdx index 51e41eb0e0..e2b35adc01 100644 --- a/docs/authentication/enterprise-connections/jit-provisioning.mdx +++ b/docs/authentication/enterprise-connections/jit-provisioning.mdx @@ -7,7 +7,7 @@ Just-in-Time (JIT) Provisioning, or automatic account provisioning, is a process Using JIT Provisioning means your IT department won't have to manually create user accounts for each of the services or apps your employees use to get work done. -Clerk supports JIT account provisioning for all [supported SAML providers](/docs/authentication/saml/overview). +Clerk supports JIT account provisioning for all [supported SAML providers](/docs/authentication/enterprise-connections/overview). Check your preferred SAML provider's documentation to enable JIT account provisioning on their side. diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index fdcac2c44f..4d8a01a87d 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -5,7 +5,7 @@ description: Clerk provides Enterprise SSO to authenticate users via federated I With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [Enterprise SSO authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [Account linking](/docs/authentication/enterprise-connections/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. -Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. +Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. For [EASIE](https://easie.dev), Clerk offers integration with Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured credentials and redirect URIs - no other configuration is needed. For production instances, you will need to generate your own Client ID and Client Secret, following the same steps outlined in our guides: @@ -61,7 +61,7 @@ The users will not be deleted, so your application will not break. However, they ### 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/saml/authentication-flows). +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). ### How much does it cost? diff --git a/docs/authentication/enterprise-connections/saml/custom-provider.mdx b/docs/authentication/enterprise-connections/saml/custom-provider.mdx index 15162ea682..0593eb2b9a 100644 --- a/docs/authentication/enterprise-connections/saml/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/saml/custom-provider.mdx @@ -20,7 +20,7 @@ description: Learn how to integrate an Identity Provider with Clerk using SAML S - Use a custom IdP to enable single sign-on (SSO) via SAML for your Clerk application. -Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also integrate with any other IdP that supports the SAML protocol. This guide will show you how to set up a SAML connection with a custom IdP in Clerk. +Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also integrate with any other IdP that supports the SAML protocol. This guide will show you how to set up a SAML connection with a custom IdP in Clerk. ## Tutorial diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx index 7f0bd583aa..8c223816e2 100644 --- a/docs/authentication/saml/overview.mdx +++ b/docs/authentication/saml/overview.mdx @@ -3,7 +3,7 @@ title: Enterprise SSO via SAML description: Clerk supports Enterprise SSO via the SAML protocol so that you can create authentication strategies for Identity Providers, such as Okta. --- -Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [SAML SSO authentication flows](/docs/authentication/saml/authentication-flows) and [Account linking](/docs/authentication/saml/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/saml/azure), [Google Workspace](/docs/authentication/saml/google), and [Okta Workforce](/docs/authentication/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/saml/custom-provider) that supports the SAML protocol. +Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [SAML SSO authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [Account linking](/docs/authentication/enterprise-connections/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. ## Allow subdomains @@ -40,7 +40,7 @@ The users will not be deleted, so your application will not break. However, they ### Does Clerk support IdP-initiated SSO? -Yes, Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/saml/authentication-flows). +Yes, Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/enterprise-connections/authentication-flows). ### How much does it cost? diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index 0b0ed582e7..167ecb1de6 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -131,4 +131,4 @@ To make the setup process easier, it's recommended to keep two browser tabs open - Only credentials of type `secret` are supported (not the `certificate` type). > [!TIP] -> If you're using [SAML with Microsoft](/docs/authentication/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations. +> If you're using [SAML with Microsoft](/docs/authentication/enterprise-connections/saml/azure), the different tenant types _are_ supported, and you can disregard these limitations. diff --git a/docs/custom-flows/saml-connections.mdx b/docs/custom-flows/saml-connections.mdx index b1386039de..e062065c88 100644 --- a/docs/custom-flows/saml-connections.mdx +++ b/docs/custom-flows/saml-connections.mdx @@ -7,7 +7,7 @@ description: Learn how to use the Clerk API to build a custom sign-up and sign-i ## Before you start -You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/saml/overview) to learn how to configure your instance. +You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance. ## Create the sign-up and sign-in flow From 7e5fde9ae618c480bd055fd2756aef4c69a49d13 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:51:40 -0500 Subject: [PATCH 13/35] update authentication flows guide --- .../authentication-flows.mdx | 31 ++++++------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/docs/authentication/enterprise-connections/authentication-flows.mdx b/docs/authentication/enterprise-connections/authentication-flows.mdx index d8a86512c8..24cdd2652e 100644 --- a/docs/authentication/enterprise-connections/authentication-flows.mdx +++ b/docs/authentication/enterprise-connections/authentication-flows.mdx @@ -3,13 +3,17 @@ 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). + ## EASIE -EASIE Connections support the authentication flows described at [easie.dev](https://easie.dev). With EASIE, your application can provide enterprise-grade SSO through a multi-tenant OpenID provider. This provides an easier alternative to setting up SAML SSO. +EASIE connections support the authentication flows described at [easie.dev](https://easie.dev). ## SAML -The SAML protocol supports two methods to start an SSO flow: Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated). +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. ### Service Provider-initiated flow (recommended) @@ -48,22 +52,7 @@ When enabling an IdP-initiated flow, it is possible for Clerk to receive unsolic To mitigate the risks associated with IdP-initiated flows, Clerk implements several security measures: -##### 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. - -#### Conclusion - -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—such as MFA, replay detection, and short validation periods—are in place to mitigate the associated risks. +- **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. From 02f0c3c29931e5bad6e839f02abd14532c76ebad Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:28:15 -0500 Subject: [PATCH 14/35] update overview --- .../enterprise-connections/overview.mdx | 46 ++++++++-------- docs/authentication/saml/overview.mdx | 53 ------------------- docs/manifest.json | 4 ++ 3 files changed, 26 insertions(+), 77 deletions(-) delete mode 100644 docs/authentication/saml/overview.mdx diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 4d8a01a87d..365609d2f1 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -3,43 +3,41 @@ title: Enterprise SSO description: Clerk provides Enterprise SSO to authenticate users via federated Identity Providers such such as Azure AD, Okta, Google Workspace and more. --- -With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [Enterprise SSO authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [Account linking](/docs/authentication/enterprise-connections/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. +With Enterprise SSO, users can sign in seamlessly using their Identity Provider's (IdP) credentials and have their user data synchronized with Clerk. You can learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). -Clerk offers direct SAML integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. +## SAML -For [EASIE](https://easie.dev), Clerk offers integration with Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured credentials and redirect URIs - no other configuration is needed. For production instances, you will need to generate your own Client ID and Client Secret, following the same steps outlined in our guides: +Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an IdP. The following IdPs are supported: [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta). However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. -- [Google](docs/authentication/social-connections/google) -- [Microsoft](docs/authentication/social-connections/azure) +### Allow subdomains -## SAML vs. EASIE +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. -[EASIE](https://easie.dev) allows for enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to support an easier alternative to fully fledged SAML SSO, without requiring additional configuration in the Identity Provider and potential sharing of credentials or secrets. +To configure subdomains for a SAML connection: -A key consideration is [security](https://easie.dev#security). While Clerk implements measures to [address potential security issues](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), applications that require single-tenant Identity Providers should opt for SAML SSO. +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 SAML connection you want to allow subdomains for. +1. Select the **Advanced** tab. +1. Enable or disable the **Allow subdomains** option. +1. Select **Save**. -## Add your first Enterprise Connection +> [!NOTE] +> To enable the **Allow subdomains** option, your SAML connection domain must be an [eTLD+1](https://developer.mozilla.org/en-US/docs/Glossary/eTLD). -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Click on **Add connection** on the top right and select **For specific domains**. -1. Select one of the Identity Provider options based on your protocol of choice. -1. On the next page, enter any required configuration information. +## EASIE -## Allow subdomains for SAML +[EASIE](https://easie.dev) SSO is a way for applications to provide enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to be an easier alternative to SAML SSO. -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. +The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—no other configuration is needed. For _production instances_, you must provide custom credentials. Follow the steps outlined in the guides to complete the setup: -To support SAML SSO with subdomains, +- [Google](docs/authentication/social-connections/google) +- [Microsoft](docs/authentication/social-connections/azure) -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the SAML Connection you want to allow subdomains for. -1. Select the **Advanced** tab. -1. Toggle on the **Allow subdomains** option. +## SAML vs. EASIE -> [!NOTE] -> To enable the **Allow subdomains** option, your SAML Connection domain must be an eTLD+1. +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). ## Frequently asked questions (FAQ) diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx deleted file mode 100644 index 8c223816e2..0000000000 --- a/docs/authentication/saml/overview.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Enterprise SSO via SAML -description: Clerk supports Enterprise SSO via the SAML protocol so that you can create authentication strategies for Identity Providers, such as Okta. ---- - -Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). With Enterprise SSO, users can sign in seamlessly using their IdP's credentials and have their user data synchronized with Clerk. You can learn more about the process in the [SAML SSO authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [Account linking](/docs/authentication/enterprise-connections/account-linking) guides, or you can jump straight into integrating an IdP with Clerk. Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. - -## 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. - -To support SAML SSO with subdomains, - -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the SAML connection you want to allow subdomains for. -1. Select the **Advanced** tab. -1. Toggle on the **Allow subdomains** option. - -> [!NOTE] -> To enable the **Allow subdomains** option, your SAML connection domain must be an eTLD+1. - -## 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. - -### Will SAML work for my existing users? - -Yes, SAML will work for your existing users as well! If you enable SAML, any existing users with an email address that matches the SAML 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. - -### What happens if I delete the SAML 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. - -### Does Clerk support IdP-initiated SSO? - -Yes, Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/enterprise-connections/authentication-flows). - -### How much does it cost? - -For production instances, each active connection costs $50 per month. SAML connections require the Pro plan and the Enhanced Authentication Add-on. See [pricing](/pricing){{ target: '_blank' }} for those costs, and the costs of other add-ons or features. - -For development instances, SAML connections will always be free, but capped to 5. - -### Can I get a bulk discount? - -Yes, [contact support](/contact/support){{ target: '_blank' }} to work out a custom plan. diff --git a/docs/manifest.json b/docs/manifest.json index b66d65442f..c1b70cf538 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -528,6 +528,10 @@ "title": "SAML", "items": [ [ + { + "title": "Overview", + "href": "/docs/authentication/enterprise-connections/saml/overview" + }, { "title": "Azure", "href": "/docs/authentication/enterprise-connections/saml/azure" From ee8feaa5a6d2aa9df9b8561169ce97e7a01f41d8 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:47:42 -0500 Subject: [PATCH 15/35] update account linking --- .../account-linking.mdx | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/docs/authentication/enterprise-connections/account-linking.mdx b/docs/authentication/enterprise-connections/account-linking.mdx index 212448f9f5..5d8dd135c4 100644 --- a/docs/authentication/enterprise-connections/account-linking.mdx +++ b/docs/authentication/enterprise-connections/account-linking.mdx @@ -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. From ff6c77f183c7c9682b3abaa60f5219bd3fc0970d Mon Sep 17 00:00:00 2001 From: Izaak Lauer <8404559+izaaklauer@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:01:07 -0500 Subject: [PATCH 16/35] Removing non-existent saml overview --- docs/manifest.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index c1b70cf538..b66d65442f 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -528,10 +528,6 @@ "title": "SAML", "items": [ [ - { - "title": "Overview", - "href": "/docs/authentication/enterprise-connections/saml/overview" - }, { "title": "Azure", "href": "/docs/authentication/enterprise-connections/saml/azure" From 98ce2f9f614ff9621828b5924397324fb561bb1c Mon Sep 17 00:00:00 2001 From: Izaak Lauer <8404559+izaaklauer@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:34:23 -0500 Subject: [PATCH 17/35] Deprovisioning section --- docs/authentication/enterprise-connections/overview.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 365609d2f1..4999f9185a 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -33,6 +33,14 @@ The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _ - [Google](docs/authentication/social-connections/google) - [Microsoft](docs/authentication/social-connections/azure) +### Automatic Deprovisioning + +Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the application. + +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, NextJS applications 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. From 87adc799a71547742c5e9308e8c64261dd1c65ba Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:40:12 -0500 Subject: [PATCH 18/35] update easie connection guides --- .../account-linking.mdx | 9 +++---- .../enterprise-connections/easie/google.mdx | 24 ++++++++++------- .../easie/microsoft.mdx | 27 ++++++++++--------- 3 files changed, 33 insertions(+), 27 deletions(-) diff --git a/docs/authentication/enterprise-connections/account-linking.mdx b/docs/authentication/enterprise-connections/account-linking.mdx index 5d8dd135c4..c5a55372fc 100644 --- a/docs/authentication/enterprise-connections/account-linking.mdx +++ b/docs/authentication/enterprise-connections/account-linking.mdx @@ -3,8 +3,7 @@ title: Account linking description: Learn how Clerk handles account linking during Enterprise SSO. --- -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. +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 @@ -16,7 +15,7 @@ The following sections describe different scenarios that can occur during this p ### Email is verified in Clerk -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. +When a user signs into your app using an IdP that returns a matching verified email address, Clerk automatically links the Enterprise SSO account to the existing account and completes the sign-in process. This includes accounts protected by passwords, as the Enterprise SSO sign-in flow automatically bypasses password verification. ### Email is not verified and verification isn't required @@ -27,8 +26,8 @@ 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. -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. +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. ### Email is not verified -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. +When a user signs into your app using an IdP that returns a matching unverified email address, Clerk doesn't link the Enterprise SSO account to the existing account, but instead signs the user up and creates a completely new account. diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index e21486d740..998f96f341 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -1,6 +1,6 @@ --- -title: Add Google as a EASIE connection -description: Learn how to integrate Google with Clerk using EASIE SSO. +title: Add Google as an EASIE connection +description: Learn how to allow users to sign up and sign in to your Clerk app with their Google account using EASIE SSO. --- - - Use Google to enable SSO via [EASIE](https://easie.dev) for your Clerk app. + - Use Google to authenticate users with EASIE SSO. +Enabling EASIE SSO with Google allows your users to sign up and sign in to your Clerk application with their Google account. + ## Configure for your development instance -For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. +For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—no other configuration is needed. 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. 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. Select **Add connection**. ## Configure for your production instance +> [!WARNING] +> If you already [configured Google as a social provider](/docs/authentication/social-connections/google), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social connection. + For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). - ### Set up an enterprise connection in Clerk + ### Enable Google as an EASIE connection - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. + 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. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. + 1. Save the **Redirect URI** somewhere secure. ### Create a Google Developer project diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 2671f5ea3d..49d6a45a0c 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -1,5 +1,5 @@ --- -title: Add Microsoft as a EASIE connection +title: Add Microsoft as an EASIE connection description: Learn how to allow users to sign up and sign in to your Clerk app with their Microsoft account using EASIE SSO. --- @@ -22,16 +22,14 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w } ]} > - - Use Microsoft to enable SSO via EASIE for your Clerk app. + - Use Microsoft to authenticate users with EASIE SSO. -Enabling single sign-on (SSO) with Microsoft (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk application with their Microsoft account. - -To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). +Enabling EASIE SSO with Microsoft (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk application with their Microsoft account. ## Configure for your development instance -For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. +For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—no other configuration is needed. 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**. @@ -41,18 +39,21 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a ## Configure for your production instance -For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. +> [!WARNING] +> If you already [configured Microsoft as a social provider](/docs/authentication/social-connections/microsoft), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social connection. + +For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID account. To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com). - ### Set up an enterprise connection in Clerk + ### Enable Microsoft as an EASIE connection - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Below EASIE, select **Microsoft** as the identity provider. + 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. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. 1. Save the **Redirect URI** somewhere secure. @@ -83,7 +84,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Set the Client ID and Client Secret in your Clerk Dashboard - Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. + Go back to the Clerk Dashboard, where the modal should still be open, and paste the **Client ID** and **Client Secret** values into the respective fields. Then, select **Add connection**. ### Enable OpenID From b33b5b2ce259b683694783327f3c7830f1f42911 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:42:39 -0500 Subject: [PATCH 19/35] deprovisioning section code review --- docs/authentication/enterprise-connections/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 4999f9185a..70d88ffe7e 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -33,13 +33,13 @@ The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _ - [Google](docs/authentication/social-connections/google) - [Microsoft](docs/authentication/social-connections/azure) -### Automatic Deprovisioning +### Automatic deprovisioning Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the application. 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, NextJS applications using [`auth.Protect`](docs/references/nextjs/auth#auth-protect) will automatically redirect the user to the sign-in page. +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. ## SAML vs. EASIE From 0c79b00d9142bdcae80ff7c0680eace12b2b0527 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:52:26 -0500 Subject: [PATCH 20/35] fix dashboard navigation instructions --- .../enterprise-connections/easie/google.mdx | 2 +- .../enterprise-connections/easie/microsoft.mdx | 2 +- .../enterprise-connections/saml/azure.mdx | 13 +------------ .../saml/custom-provider.mdx | 15 ++++----------- .../enterprise-connections/saml/google.mdx | 9 ++++----- .../enterprise-connections/saml/okta.mdx | 7 +++---- 6 files changed, 14 insertions(+), 34 deletions(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index 998f96f341..b0c8d184c8 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -33,7 +33,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. Below EASIE, select **Google** as the identity provider. +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. Select **Add connection**. diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 49d6a45a0c..ae47a18e07 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -33,7 +33,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. Below EASIE, select **Microsoft** as the identity provider. +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. Select **Add connection**. diff --git a/docs/authentication/enterprise-connections/saml/azure.mdx b/docs/authentication/enterprise-connections/saml/azure.mdx index d2228ef9ec..1ae47660ab 100644 --- a/docs/authentication/enterprise-connections/saml/azure.mdx +++ b/docs/authentication/enterprise-connections/saml/azure.mdx @@ -31,7 +31,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. In the modal that opens, select **Microsoft Entra ID (Formerly AD)** as the identity provider. + 1. Under **SAML**, select **Microsoft Entra ID (Formerly AD)** as the identity provider. 1. Add the **Name** of the connection. This is the name that will be displayed on the sign-in form. 1. Enter 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**. You'll be redirected to the connection's configuration page. @@ -118,15 +118,4 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. 1. At the top of the page, toggle on **Enable connection** and select **Save**. - - ### Test your OAuth - - The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box. - - 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. - 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - - - **For development** – `https://your-domain.accounts.dev/sign-in` - - **For production** – `https://accounts.your-domain.com/sign-in` - 1. Sign in with your Microsoft account. diff --git a/docs/authentication/enterprise-connections/saml/custom-provider.mdx b/docs/authentication/enterprise-connections/saml/custom-provider.mdx index 0593eb2b9a..c0b23a82ba 100644 --- a/docs/authentication/enterprise-connections/saml/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/saml/custom-provider.mdx @@ -29,10 +29,9 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth To create a SAML connection in Clerk: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Select **Custom SAML Provider**. + 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 **SAML**, select **Custom SAML Provider**. 1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form. 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. Select **Add connection**. You will be redirected to the connection's configuration page. @@ -103,16 +102,10 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth Learn more about [how to access the metadata from our APIs](/docs/users/metadata). - ### Activate your SAML connection - - Now that you have configured your SAML connection, you can activate it. + ### Enable the connection for Clerk To make the connection available for your users to authenticate with: 1. In the Clerk Dashboard, you should still have the connection's configuration page open. If not, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. 1. Toggle on **Enable connection** and select **Save**. - - ### Test your SAML connection - - Everything should be set up now for you to test authentication via SAML. Go to your Clerk application's sign-in page and add your email address in the input field. If it matches an active SAML connection, you will be redirected to your IdP where you will sign in with your credentials. diff --git a/docs/authentication/enterprise-connections/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx index 88c0bcaaff..15495420a1 100644 --- a/docs/authentication/enterprise-connections/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -27,13 +27,12 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. To create a SAML connection in Clerk: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Select **Google Workspace** as the identity provider. + 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 **SAML**, select **Google Workspace** as the identity provider. 1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form. 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. Select **Add connection**. You will be redirected to the connection's configuration page. + 1. Select **Add connection**. You'll be redirected to the connection's configuration page. ### Create a new enterprise application in Google diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index d05ebe395b..e442e44eda 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -27,10 +27,9 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. To create a SAML connection in Clerk: - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). - 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. - 1. Select the **Add connection** button, and select **For specific domains**. - 1. Select **Okta Workforce** as the identity provider. + 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 **SAML**, select **Okta Workforce** as the identity provider. 1. Add the **Name** of the connection. This is the name that will be displayed in the sign-in form. 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. Select **Add connection**. You will be redirected to the connection's configuration page. From c9e6269512d75dad0c1375b76f9f4b5d5085275b Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 19 Nov 2024 16:12:45 -0500 Subject: [PATCH 21/35] Apply suggestions from code review --- .../account-linking.mdx | 8 ++++---- .../authentication-flows.mdx | 14 ++++++------- .../enterprise-connections/easie/google.mdx | 2 +- .../easie/microsoft.mdx | 4 ++-- .../enterprise-connections/overview.mdx | 20 +++++++++---------- 5 files changed, 24 insertions(+), 24 deletions(-) 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. From 552f3b44d6f0e0c497b903429e4b851d68cb16c7 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 19 Nov 2024 16:15:13 -0500 Subject: [PATCH 22/35] Update docs/authentication/enterprise-connections/easie/google.mdx --- docs/authentication/enterprise-connections/easie/google.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index c59dc339ed..a9f0442f07 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -51,7 +51,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. Below EASIE, select **Google Workspace** 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. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. From 951561e659885ca2aef4734cefb682d3b95bc546 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 19 Nov 2024 16:15:32 -0500 Subject: [PATCH 23/35] Update docs/authentication/enterprise-connections/easie/microsoft.mdx --- docs/authentication/enterprise-connections/easie/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 9619640521..23c3fe162a 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -51,7 +51,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. Below EASIE, select **Google Workspace** 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 app. 1. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. From 835b3f01507a43a4d9148c50fb8d4e9fc68ad7ed Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 19 Nov 2024 16:21:22 -0500 Subject: [PATCH 24/35] Update docs/authentication/enterprise-connections/easie/google.mdx --- docs/authentication/enterprise-connections/easie/google.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index a9f0442f07..ff5d4c036a 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -65,7 +65,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the menu on the left, select **Credentials**. 1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent). 1. Select the appropriate application type for your project. Most likely, you will choose **Web application**. - 1. In the **Authorized Redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. + 1. In the **Authorized redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. 1. Select **Create**. Keep this page open. ### Set the Client ID and Client Secret in your Clerk Dashboard From ae2dcfc5ef1688a54ceb60061bd1cab58f3302d5 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 19 Nov 2024 16:37:52 -0500 Subject: [PATCH 25/35] Update docs/authentication/enterprise-connections/easie/google.mdx --- docs/authentication/enterprise-connections/easie/google.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index ff5d4c036a..46a6fe7853 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -51,7 +51,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 Workspace** as the identity provider. + 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. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. From 5ab46db7f91ac5546ec3ffc9d56141192be24751 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 19 Nov 2024 16:37:57 -0500 Subject: [PATCH 26/35] Update docs/authentication/enterprise-connections/easie/microsoft.mdx --- docs/authentication/enterprise-connections/easie/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 23c3fe162a..18d7e1d3fc 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -51,7 +51,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 Workspace** as the identity provider. + 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 app. 1. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. From 989e24142d380d67e89d6d8f4e34dc3d6c3365d1 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 17:11:01 -0500 Subject: [PATCH 27/35] Update docs/authentication/enterprise-connections/easie/microsoft.mdx --- docs/authentication/enterprise-connections/easie/microsoft.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 18d7e1d3fc..8bb6c4d89d 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -53,9 +53,8 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add connection** 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 app. - 1. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. - 1. Save the **Redirect URI** somewhere secure. + 1. Save the **Redirect URI** somewhere secure. Keep this page open. ### Create a Microsoft Entra ID app From 4b96c30eded824d0051ce4b4a3dd04d515557304 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 17:11:06 -0500 Subject: [PATCH 28/35] Update docs/authentication/enterprise-connections/easie/microsoft.mdx --- docs/authentication/enterprise-connections/easie/microsoft.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 8bb6c4d89d..b31a04b500 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -75,7 +75,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Azure portal, you'll be redirected to its **Overview**. 1. From your app's overview, save the **Application (client) ID** somewhere secure. You'll need it to connect your Microsoft Entra ID app to your Clerk app. - 1. Under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. + 1. Under **Client credentials**, select **Add a certificate or secret** to generate a **Client Secret**. You'll be redirected to the **Certificate & secrets** page. 1. Select **New client secret**. In the modal that opens, enter a description and set an expiration time for your secret. > [!IMPORTANT] > When your secret expires, your social connection will stop working until you generate a new client secret and add it to your Clerk app. From 7bf58ff6dbb452ff0bba451fed2c87857f9f8352 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 17:11:53 -0500 Subject: [PATCH 29/35] Update docs/authentication/enterprise-connections/easie/google.mdx --- docs/authentication/enterprise-connections/easie/google.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index 46a6fe7853..7b864ae282 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -53,9 +53,8 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. Select **Add connection**. 1. Ensure that **Use custom credentials** is toggled on. - 1. Save the **Redirect URI** somewhere secure. + 1. Save the **Redirect URI** somewhere secure. Keep this page open. ### Create a Google Developer project From d77adad593295004f4fe183708691be6df37f42f Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 19 Nov 2024 17:11:58 -0500 Subject: [PATCH 30/35] Update docs/authentication/enterprise-connections/easie/google.mdx --- docs/authentication/enterprise-connections/easie/google.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index 7b864ae282..71f99ad8d1 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -65,7 +65,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent). 1. Select the appropriate application type for your project. Most likely, you will choose **Web application**. 1. In the **Authorized redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. - 1. Select **Create**. Keep this page open. + 1. Select **Create**. ### Set the Client ID and Client Secret in your Clerk Dashboard From 7d0b96ef0cb3cfe0b855cef1aba045d65c66525f Mon Sep 17 00:00:00 2001 From: Izaak Lauer <8404559+izaaklauer@users.noreply.github.com> Date: Tue, 19 Nov 2024 19:40:13 -0500 Subject: [PATCH 31/35] Clarifying the xms_edov claim is required for microsoft entra AD Copied (mostly) from here: https://clerk.com/docs/authentication/social-connections/microsoft#secure-your-app-against-the-n-o-auth-vulnerability --- .../easie/microsoft.mdx | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index b31a04b500..a624ce632d 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -70,6 +70,30 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Under **Redirect URI (Optional)**, select **Web**. 1. Select **Register** to submit the form. + ### Secure your app against the nOAuth vulnerability + + [nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to account takeovers via email address spoofing. Clerk mitigates this risk by enforcing stricter checks on verified email addresses. + + For further security, Microsoft offers an optional `xms_edov` claim, which provides additional context to determine whether the returned email is verified. + + This claim is mandatory for applications backing EASIE connections. To enable it, you must: + + 1. In the Microsoft Azure portal, navigate to your app. + 1. In the sidebar, select **Token configuration**. + 1. Select **Add optional claim**. + 1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims. + 1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form. + > [!NOTE] + > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. + 1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**. + 1. In the sidebar, go to **Manifest**. + 1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`. + 1. Search for `"optionalClaims"`, where you'll find the `idToken` and `accessToken` arrays. Each array has an object with the name `xms_pdl`. Change the name to `xms_edov`. + 1. At the top of the page, select **Save**. + 1. In the sidebar, navigate back to **Token configuration** and confirm that the **Optional claims** list includes two claims for `email` and two for `xms_edov`: one each for **ID** and **Access**. + + With these steps complete, Microsoft will send the `xms_edov` claim in the token, which Clerk will use to determine whether the email is verified, even when used with Microsoft Entra ID. + ### Get your client ID and client secret Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Azure portal, you'll be redirected to its **Overview**. From 31a11f7010d462a3e091a26e24156833a9bf9ff3 Mon Sep 17 00:00:00 2001 From: Izaak Lauer <8404559+izaaklauer@users.noreply.github.com> Date: Tue, 19 Nov 2024 19:44:20 -0500 Subject: [PATCH 32/35] Preventing the numbering from resetting --- .../authentication/enterprise-connections/easie/microsoft.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index a624ce632d..0a390a3286 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -83,8 +83,8 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add optional claim**. 1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims. 1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form. - > [!NOTE] - > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. + > [!NOTE] + > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. 1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**. 1. In the sidebar, go to **Manifest**. 1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`. From 0ec20ad713355ee0985e4edcd85641e0fb4e91cb Mon Sep 17 00:00:00 2001 From: Izaak Lauer <8404559+izaaklauer@users.noreply.github.com> Date: Tue, 19 Nov 2024 19:52:55 -0500 Subject: [PATCH 33/35] copy-pasting the magic whitespace --- .../authentication/enterprise-connections/easie/microsoft.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 0a390a3286..29a27c6684 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -83,8 +83,8 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add optional claim**. 1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims. 1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form. - > [!NOTE] - > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. + > [!NOTE] + > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later. 1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**. 1. In the sidebar, go to **Manifest**. 1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`. From 58c80993043e386cb0b6129d06d0124c87d2bcc8 Mon Sep 17 00:00:00 2001 From: Izaak Lauer <8404559+izaaklauer@users.noreply.github.com> Date: Tue, 19 Nov 2024 19:57:23 -0500 Subject: [PATCH 34/35] Noting the shared nature of built-in oauth credentials --- docs/authentication/enterprise-connections/easie/google.mdx | 2 +- docs/authentication/enterprise-connections/easie/microsoft.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index 71f99ad8d1..fba2b4c478 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -71,5 +71,5 @@ To make the setup process easier, it's recommended to keep two browser tabs open Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. - Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Then, select **Add connection**. + Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Note that if you have any other Google EASIE connections or a [Google social connection](docs/authentication/social-connections/google), this will update the credentials for all of them. Select **Add connection**. diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index 29a27c6684..a95fdf590c 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -107,7 +107,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Set the Client ID and Client Secret in your Clerk Dashboard - Go back to the Clerk Dashboard, where the modal should still be open, and paste the **Client ID** and **Client Secret** values into the respective fields. Then, select **Add connection**. + Go back to the Clerk Dashboard, where the modal should still be open, and paste the **Client ID** and **Client Secret** values into the respective fields. Note that if you have any other Microsoft EASIE connections or a [Microsoft social connection](docs/authentication/social-connections/microsoft), this will update the credentials for all of them. Select **Add connection**. ### Enable OpenID From 40e82a0039c3269257756fe50f6eb0114090ccb1 Mon Sep 17 00:00:00 2001 From: Mary Zhong Date: Tue, 19 Nov 2024 21:27:52 -0500 Subject: [PATCH 35/35] fix: 25 is the max number of enterprise connections allowed for dev instances --- docs/authentication/enterprise-connections/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 6120df7a3e..7964cc946f 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -71,7 +71,7 @@ Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated ### How much does it cost? -For development instances, Enterprise connections are always free but limited to a maximum of 5. +For development instances, Enterprise connections are always free but limited to a maximum of 25. Production instances require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for more information.