feat: SSO per org

docs/authentication/enterprise-connections/authentication-flows.mdx

@@ -3,7 +3,7 @@ title: Enterprise SSO authentication flows
 description: Learn about the Enterprise SSO authentication flows.
 ---
 
-There are two types of Enterprise SSO connections: [EASIE](#easie) and [SAML](#saml).
+There are three types of Enterprise SSO connections: [EASIE](#easie), [SAML](#saml), and [OIDC](#oidc).
 
 ## EASIE
 
@@ -36,7 +36,7 @@ In an IdP-initiated flow:
 To allow IdP-initiated flows for your SAML connection:
 
 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. Select **Add connection** and select **For specific domains or organizations**.
 1. Select your **Identity Provider**. Complete the fields and select **Add connection**. You'll be redirected to the SAML connection's configuration page.
 1. Select the **Advanced** tab.
 1. In **Advanced Settings**, enable **Allow IdP-Initiated flow**. A modal will open. Select **Enable** to confirm.
@@ -56,3 +56,7 @@ To mitigate the risks associated with IdP-initiated flows, Clerk implements seve
 - **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're using a custom IdP, you must ensure that the validation periods are set correctly.
+
+## OIDC
+
+Clerk supports Enterprise SSO via the OpenID Connect (OIDC) protocol, either through [EASIE](#easie) or by [integrating with any OIDC-compatible provider](/docs/authentication/enterprise-connections/oidc/custom-provider).

docs/authentication/enterprise-connections/easie/google.mdx

@@ -32,9 +32,9 @@ Enabling EASIE SSO with Google allows your users to sign up and sign in to your
 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 **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 app.
+1. Select **Add connection** and select **For specific domains or organizations**.
+1. Under **EASIE**, select **Google**.
+1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
 1. Select **Add connection**.
 
 ## Configure for your production instance
@@ -50,10 +50,10 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   ### Enable Google as an EASIE connection
 
   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. Ensure that **Use custom credentials** is toggled on.
+  1. Select **Add connection** and select **For specific domains or organizations**.
+  1. Under **EASIE**, select **Google**.
+  1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
+  1. Enable **Use custom credentials**.
   1. Save the **Redirect URI** somewhere secure. Keep this page open.
 
   ### Create a Google Developer project

docs/authentication/enterprise-connections/easie/microsoft.mdx

@@ -32,9 +32,9 @@ Enabling EASIE SSO with Microsoft (formerly [Active Directory](https://learn.mic
 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. 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** and select **For specific domains or organizations**.
+1. Under **EASIE**, select **Microsoft**.
+1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
 1. Select **Add connection**.
 
 ## Configure for your production instance
@@ -50,10 +50,10 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   ### Enable Microsoft as an EASIE connection
 
   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 **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. Ensure that **Use custom credentials** is toggled on.
+  1. Select **Add connection** and select **For specific domains or organizations**.
+  1. Under **EASIE**, select **Microsoft**.
+  1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
+  1. Enable **Use custom credentials**.
   1. Save the **Redirect URI** somewhere secure. Keep this page open.
 
   ### Create a Microsoft Entra ID app

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

@@ -28,7 +28,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   ### Set up an enterprise connection in Clerk
 
   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. Select **Add connection** and select **For specific domains or organizations**.
   1. Under **Third party**, select **OpenID Connect (OIDC)**.
   1. Add the **Name** of the connection.
   1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation).

docs/authentication/enterprise-connections/saml/azure.mdx

@@ -30,13 +30,13 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   To create a SAML connection in Clerk:
 
   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 **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** and select **For specific domains or organizations**.
+  1. Under **SAML**, select **Microsoft Entra ID (Formerly AD)**.
+  1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
+  1. Enter the **Name**. This will be displayed on the sign-in form.
   1. Select **Add connection**. You'll be redirected to the connection's configuration page.
-  1. Find the **Service Provider Configuration** section.
-  1. Save the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step. Leave this page open.
+  1. In the **Service Provider Configuration** section, save the **Reply URL (Assertion Consumer Service URL)** and **Identifier (Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step.
+  1. Keep this page open.
 
   ### Create a new enterprise app in Microsoft
 

docs/authentication/enterprise-connections/saml/custom-provider.mdx

@@ -1,6 +1,6 @@
 ---
-title: Add a custom Identity Provider as a SAML connection
-description: Learn how to integrate an Identity Provider with Clerk using SAML SSO.
+title: Add a custom Identity Provider (IdP) as a SAML connection
+description: Learn how to integrate an Identity Provider (IdP) with Clerk using SAML SSO.
 ---
 
 <TutorialHero
@@ -20,7 +20,9 @@ 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.
 </TutorialHero>
 
-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.
+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 the following IdPs: [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 IdPs that supports the SAML protocol.
+
+This guide shows you how to set up a SAML connection with a custom IdP in Clerk.
 
 ## Tutorial
 
@@ -30,11 +32,11 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth
   To create a SAML connection in Clerk:
 
   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. Select **Add connection** and select **For specific domains or organizations**.
   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.
+  1. Add the **Domain** for which you want to enable this connection. This is the domain of the users you wish to allow to sign in to your application. Optionally, select an **Organization**.
+  1. Enter the **Name**. This will be displayed on the sign-in form.
+  1. Select **Add connection**. You'll be redirected to the connection's configuration page.
 
   ### Create a new enterprise application in your IdP
 

docs/authentication/enterprise-connections/saml/google.mdx

@@ -28,10 +28,10 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   To create a SAML connection in Clerk:
 
   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** and select **For specific domains or organizations**.
+  1. Under **SAML**, select **Google Workspace**.
+  1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
+  1. Enter the **Name**. This will be displayed on the sign-in form.
   1. Select **Add connection**. You'll be redirected to the connection's configuration page.
 
   ### Create a new enterprise application in Google

docs/authentication/enterprise-connections/saml/okta.mdx

@@ -20,22 +20,19 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   - Use Okta Workforce to enable single sign-on (SSO) via SAML for your Clerk application.
 </TutorialHero>
 
-## Tutorial
-
 <Steps>
   ### Set up an enterprise connection in Clerk
 
   To create a SAML connection in Clerk:
 
   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.
-  1. Find the **Service Provider Configuration** section.
-  1. Save the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step.
-  1. Leave this page open.
+  1. Select **Add connection** and select **For specific domains or organizations**.
+  1. Under **SAML**, select **Okta Workforce**.
+  1. Enter the **Domain**. This is the URL users use to sign in to your application. Optionally, select an **Organization**.
+  1. Enter the **Name**. This will be displayed on the sign-in form.
+  1. Select **Add connection**. You'll be redirected to the connection's configuration page.
+  1. In the **Service Provider Configuration** section, save the **Single sign-on URL** and **Audience URI (SP Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step.
+  1. Keep this page open.
 
   ### Create a new enterprise application in Okta
 
@@ -44,10 +41,10 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   1. Navigate to [Okta](https://www.okta.com/) and sign in.
   1. In the Okta dashboard, select **Admin** in the top right corner.
   1. In the navigation sidebar, select the **Applications** dropdown and select **Applications**.
-  1. Select the **Create App Integration** button.
+  1. Select **Create App Integration**.
   1. In the **Create a new app integration** modal, select the **SAML 2.0** option and select the **Next** button.
-  1. Once redirected to the **Create SAML Integration** page, fill in the **General Settings** fields. An **App name** is required.
-  1. Select the **Next** button to continue.
+  1. Once redirected to the **Create SAML Integration** page, complete the **General Settings** fields. An **App name** is required.
+  1. Select **Next**.
 
   ### Configure your service provider
 

docs/manifest.json

@@ -668,6 +668,10 @@
                     "title": "Verified domains",
                     "href": "/docs/organizations/verified-domains"
                   },
+                  {
+                    "title": "Enterprise SSO",
+                    "href": "/docs/organizations/enterprise-sso"
+                  },
                   {
                     "title": "Guides",
                     "items": [

docs/organizations/enterprise-sso.mdx

@@ -0,0 +1,48 @@
+---
+title: Organization-level enterprise SSO
+description: Learn how to set up and manage enterprise SSO for organizations.
+---
+
+Clerk supports adding enterprise SSO connections to organizations, enabling users to sign in with an Identity Provider (IdP) and easily join organizations. There are three types of [enterprise connections](/docs/authentication/enterprise-connections/authentication-flows) that are supported: EASIE, SAML, and OIDC.
+
+When users sign in or up using an organization's enterprise connection, they're automatically added as members of that organization and assigned the [default role](/docs/organizations/roles-permissions#default-roles), which can be either `member` or `admin`.
+
+> [!WARNING]
+> A domain used for enterprise SSO can't be used as a [verified domain](/docs/organizations/verified-domains) for the same organization.
+
+## Add an organization-level enterprise SSO connection
+
+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 or organizations**.
+1. Select a Identity Provider.
+1. Add the **Domain** for which you want to enable this connection and select an **Organization**.
+
+## Onboarding flows
+
+The two common onboarding flows for organizations with enterprise SSO are to either create an organization first or to have users initiate the setup themselves.
+
+#### Organization created first (top-down approach)
+
+This flow is common for enterprise sales where the relationship is established before users access the application.
+
+1. [Create an organization](/docs/organizations/overview#create-an-organization) for your customer through the Clerk Dashboard.
+1. Collaborate with the customer's IT administrator to obtain the necessary configuration details.
+1. Configure the SSO connection for the organization.
+1. Invite users to the organization, who can then sign in using SSO.
+
+#### User-initiated setup (bottom-up approach)
+
+This flow is common when individual users try the product before company-wide adoption.
+
+1. An end user signs up to evaluate your application, starting with an individual account.
+1. After adopting the application, the user [creates an organization](/docs/organizations/overview#create-an-organization) for their company.
+1. Configure SSO for the organization through the Clerk Dashboard.
+1. All subsequent users from that organization can now sign in using enterprise SSO.
+
+## Enforcing SSO by domain
+
+SSO connections are enforced on a per-domain basis in organizations, enabling flexible access management:
+
+- Configure SSO for your primary domain (e.g., `company.com`) to enforce SSO authentication for employees.
+- Add additional domains without SSO for external collaborators (e.g., contractors, consultants)
+- Each domain in an organization can have different authentication requirements.