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] 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"