diff --git a/docs/authentication/enterprise-connections/authentication-flows.mdx b/docs/authentication/enterprise-connections/authentication-flows.mdx index cda6ab5ae4..05a1d583d6 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. --- -There are two types of Enterprise SSO connections: [EASIE](#easie) and [SAML](#saml). +Clerk offers the following 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). diff --git a/docs/authentication/enterprise-connections/easie/google.mdx b/docs/authentication/enterprise-connections/easie/google.mdx index 4e8ed5048f..caa6e91d22 100644 --- a/docs/authentication/enterprise-connections/easie/google.mdx +++ b/docs/authentication/enterprise-connections/easie/google.mdx @@ -25,16 +25,16 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w - 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. +Enabling [EASIE SSO](/docs/authentication/enterprise-connections/overview#easie) 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 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 email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. 1. Select **Add connection**. ## Configure for your production instance @@ -50,21 +50,20 @@ 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. Save the **Redirect URI** somewhere secure. Keep this page open. + 1. Select **Add connection** and select **For specific domains or organizations**. + 1. Under **EASIE**, select **Google**. + 1. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. + 1. Save the **Redirect URI** somewhere secure. Keep this modal open to enter the OAuth credentials in the following steps. ### 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. In the left sidebar, 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** section, select **Add URI** and paste the **Redirect URI** value you saved from the Clerk Dashboard. 1. Select **Create**. ### Set the Client ID and Client Secret in the Clerk Dashboard diff --git a/docs/authentication/enterprise-connections/easie/microsoft.mdx b/docs/authentication/enterprise-connections/easie/microsoft.mdx index f0ac052697..e98dd01ed3 100644 --- a/docs/authentication/enterprise-connections/easie/microsoft.mdx +++ b/docs/authentication/enterprise-connections/easie/microsoft.mdx @@ -25,16 +25,16 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w - Use Microsoft to authenticate users with EASIE SSO. -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. +Enabling [EASIE SSO](/docs/authentication/enterprise-connections/overview#easie) 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 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 email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. 1. Select **Add connection**. ## Configure for your production instance @@ -50,11 +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. Save the **Redirect URI** somewhere secure. Keep this page open. + 1. Select **Add connection** and select **For specific domains or organizations**. + 1. Under **EASIE**, select **Microsoft**. + 1. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. + 1. Save the **Redirect URI** somewhere secure. Keep this modal open to enter the OAuth credentials in the following steps. ### Create a Microsoft Entra ID app @@ -62,11 +61,11 @@ To make the setup process easier, it's recommended to keep two browser tabs open > 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. In the left sidebar, in the **Manage** dropdown, 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 **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. @@ -79,24 +78,23 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. In the left sidebar, in the **Manage** dropdown, 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. - 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. Repeat the previous steps but for **Token type**, 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 left sidebar, in the **Manage** dropdown, select **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**. + 1. In the left sidebar, in the **Manage** dropdown, select **Token configuration** to 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**. - - 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. In the left sidebar, select **Overview**. + 1. 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] @@ -112,7 +110,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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. In the left sidebar, in the **Manage** dropdown, 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. diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 9079a542d2..96879196e8 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -28,11 +28,11 @@ 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 **OpenID Connect (OIDC)**, select **Custom OIDC Provider**. 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). - 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. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. 1. Select **Add connection**. You will be redirected to the connection's configuration page. Keep this page open. ## Configure your IdP diff --git a/docs/authentication/enterprise-connections/saml/azure.mdx b/docs/authentication/enterprise-connections/saml/azure.mdx index 67a08b2cbd..88539e2429 100644 --- a/docs/authentication/enterprise-connections/saml/azure.mdx +++ b/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 email domain of the users you want 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. - 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 diff --git a/docs/authentication/enterprise-connections/saml/custom-provider.mdx b/docs/authentication/enterprise-connections/saml/custom-provider.mdx index e0dbd4a0d6..d5df7bf3d1 100644 --- a/docs/authentication/enterprise-connections/saml/custom-provider.mdx +++ b/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. --- -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. ## Set up an enterprise connection in Clerk @@ -28,11 +30,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 diff --git a/docs/authentication/enterprise-connections/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx index 4ec7423f1c..e329e47868 100644 --- a/docs/authentication/enterprise-connections/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -26,10 +26,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 email domain of the users you want 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 Google diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index 2ba9589b4c..675eb241b7 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -26,14 +26,13 @@ description: Learn how to integrate Okta Workforce 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 **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 email domain of the users you want 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. + 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 @@ -42,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 diff --git a/docs/manifest.json b/docs/manifest.json index e64bec3ffd..ba0b5b300f 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -674,6 +674,10 @@ "title": "Verified domains", "href": "/docs/organizations/verified-domains" }, + { + "title": "Manage SSO", + "href": "/docs/organizations/manage-sso" + }, { "title": "Guides", "items": [ diff --git a/docs/organizations/manage-sso.mdx b/docs/organizations/manage-sso.mdx new file mode 100644 index 0000000000..7a1a9d3708 --- /dev/null +++ b/docs/organizations/manage-sso.mdx @@ -0,0 +1,60 @@ +--- +title: Organization-level SSO +description: Learn how to set up and manage SSO for organizations. +--- + +Clerk supports adding 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 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 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. + +## Managing memberships + +### Removing a member from your organization + +Users cannot leave the organization themselves, but they can be removed in the Clerk Dashboard, using [Clerk's Backend API](/docs/reference/backend-api/tag/Organization-Memberships#operation/DeleteOrganizationMembership) endpoint, and by another organization member with the [manage members permission](/docs/organizations/roles-permissions#system-permissions) (`org:sys_memberships:manage`). However, the user will be added back to the organization on next sign in, unless they are removed from the IdP or the enterprise connection is no longer associated with the organization. + +## Updating organization from existing enterprise connection + +When transitioning an enterprise connection to a new organization, existing members will remain part of the original organization. However, they will automatically join the new organization upon their next sign-in. + +To remove members from the original organization, you have two options: utilize [Clerk's Backend API](/docs/reference/backend-api/tag/Organization-Memberships#operation/DeleteOrganizationMembership) or manage memberships directly through the Clerk Dashboard. diff --git a/docs/organizations/overview.mdx b/docs/organizations/overview.mdx index 9674c0dfbc..b750105d26 100644 --- a/docs/organizations/overview.mdx +++ b/docs/organizations/overview.mdx @@ -165,3 +165,14 @@ If the prebuilt components don't meet your specific needs or if you require more - [Creating an infinite paginated list of memberships](/docs/organizations/viewing-memberships) - [Inviting users to an organization](/docs/organizations/inviting-users), which also includes code for creating a custom list of invitations - [Managing memberships](/docs/organizations/managing-roles), which includes code for updating and deleting a user's membership, for inviting a user, and for creating a custom list of memberships, invitations, and requests + +## Manage SSO + +Single Sign-On (SSO) can be configured at the organization level, allowing organizations to use their own Identity Provider (IdP) for authentication. When configured: + +- Users can sign in through their organization's configured IdP +- Users are automatically added as members of the organization upon successful authentication +- Organizations can maintain their existing identity management workflows +- SAML 2.0 and OIDC protocols are supported + +For instructions on how to set up and manage SSO for your organizations, see the [dedicated guide](/docs/organizations/manage-sso). diff --git a/docs/organizations/verified-domains.mdx b/docs/organizations/verified-domains.mdx index f434825539..bc45a9d06d 100644 --- a/docs/organizations/verified-domains.mdx +++ b/docs/organizations/verified-domains.mdx @@ -7,6 +7,9 @@ Verified domains can be used to streamline enrollment into an organization. For A verified domain cannot be a disposable domain or common email provider. For example, you cannot create a verified domain for `@gmail.com`. +> [!WARNING] +> A verified domain can't be added if it's already in use for the [organization's SSO](/docs/organizations/manage-sso). + ## Enable verified domains Enabling verified domains applies to all organizations and cannot currently be managed on a per-organization basis. diff --git a/docs/references/backend/saml-connections/create-saml-connection.mdx b/docs/references/backend/saml-connections/create-saml-connection.mdx index 5fb2ed0f19..50bd8315a2 100644 --- a/docs/references/backend/saml-connections/create-saml-connection.mdx +++ b/docs/references/backend/saml-connections/create-saml-connection.mdx @@ -33,6 +33,13 @@ function createSamlConnection(params: CreateSamlConnectionParams): Promise