From a2866fcb706470a03a8af4af770788fe2540a963 Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Tue, 17 Dec 2024 17:07:41 +0200 Subject: [PATCH 1/7] fix: Update create enterprise OIDC label (#1820) --- .../enterprise-connections/oidc/custom-provider.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index ffe342ec81..9079a542d2 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -29,7 +29,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. Under **Third party**, select **OpenID Connect (OIDC)**. + 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. From 81e4c1eeec48553dd322ab455d8a9df00a9ae44e Mon Sep 17 00:00:00 2001 From: Gabriel Lopes Date: Tue, 17 Dec 2024 17:15:23 -0300 Subject: [PATCH 2/7] Organization inviterUserId as nullable (#1819) Co-authored-by: Gabriel Lopes Co-authored-by: victoria --- .../backend/organization/create-organization-invitation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/backend/organization/create-organization-invitation.mdx b/docs/references/backend/organization/create-organization-invitation.mdx index c816e57742..dcf5ced83e 100644 --- a/docs/references/backend/organization/create-organization-invitation.mdx +++ b/docs/references/backend/organization/create-organization-invitation.mdx @@ -24,7 +24,7 @@ function createOrganizationInvitation( --- - `inviterUserId` - - `string` + - `string | null` The user ID of the user creating the invitation. From dfc545226652d3ce6c1e9111d0d86006ff88665d Mon Sep 17 00:00:00 2001 From: Laura Beatris <48022589+LauraBeatris@users.noreply.github.com> Date: Wed, 18 Dec 2024 12:51:29 -0300 Subject: [PATCH 3/7] feat: SSO per org (#1755) Co-authored-by: Mary Zhong Co-authored-by: vi Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- .../authentication-flows.mdx | 8 ++- .../enterprise-connections/easie/google.mdx | 21 ++++--- .../easie/microsoft.mdx | 36 ++++++----- .../oidc/custom-provider.mdx | 4 +- .../enterprise-connections/saml/azure.mdx | 12 ++-- .../saml/custom-provider.mdx | 16 ++--- .../enterprise-connections/saml/google.mdx | 8 +-- .../enterprise-connections/saml/okta.mdx | 21 ++++--- docs/manifest.json | 4 ++ docs/organizations/manage-sso.mdx | 60 +++++++++++++++++++ docs/organizations/overview.mdx | 11 ++++ docs/organizations/verified-domains.mdx | 3 + .../create-saml-connection.mdx | 7 +++ .../update-saml-connection.mdx | 7 +++ 14 files changed, 156 insertions(+), 62 deletions(-) create mode 100644 docs/organizations/manage-sso.mdx 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 Date: Wed, 18 Dec 2024 10:39:24 -0800 Subject: [PATCH 4/7] chore: Remove Astro from Community SDKs list (#1823) --- docs/manifest.json | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index ba0b5b300f..0a0d984b8b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -3324,11 +3324,6 @@ "href": "https://github.com/Hawxy/Clerk.Net", "icon": "c-sharp" }, - { - "title": "Astro", - "href": "https://github.com/panteliselef/astro-with-clerk-auth/blob/main/packages/astro-clerk-auth/README.md", - "icon": "astro" - }, { "title": "Koa", "href": "https://github.com/dimkl/clerk-koa/blob/main/README.md", From 8107930bbf798163f1c8a67ffdcf74d5950cce67 Mon Sep 17 00:00:00 2001 From: Aayush Rajagopalan Date: Thu, 19 Dec 2024 02:11:09 +0300 Subject: [PATCH 5/7] change the marking of the _layout.tsx file (#1825) --- docs/quickstarts/expo.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstarts/expo.mdx b/docs/quickstarts/expo.mdx index 1ef8b7da8e..1e642dfa86 100644 --- a/docs/quickstarts/expo.mdx +++ b/docs/quickstarts/expo.mdx @@ -176,7 +176,7 @@ description: Add authentication and user management to your Expo app with Clerk. export const tokenCache = Platform.OS !== 'web' ? createTokenCache() : undefined ``` 1. Update your root layout to use the token cache: - ```tsx {{ filename: 'app/_layout.tsx', mark: [3, 13] }} + ```tsx {{ filename: 'app/_layout.tsx', mark: [1, 13] }} import { tokenCache } from '@/cache' import { ClerkProvider, ClerkLoaded } from '@clerk/clerk-expo' import { Slot } from 'expo-router' From b0e86f57d8adb9222ce64fda96add5fc760e71f5 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:34:07 -0500 Subject: [PATCH 6/7] (custom-session-token) add usage info for non-nextjs frameworks (#1827) --- docs/backend-requests/making/custom-session-token.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx index 4b4973f87e..f0f65d21ba 100644 --- a/docs/backend-requests/making/custom-session-token.mdx +++ b/docs/backend-requests/making/custom-session-token.mdx @@ -24,18 +24,16 @@ This guide will show you how to customize a session token to include additional ## Use the custom claims in your application - The [`Auth`](/docs/references/nextjs/auth-object) object in the `@clerk/nextjs` package includes a `sessionClaims` property that contains the custom claims you added to your session token. + The [`Auth`](/docs/references/nextjs/auth-object) object includes a `sessionClaims` property that contains the custom claims you added to your session token. It's returned by the [`useAuth()`](/docs/references/react/use-auth) hook, the [`auth()`](/docs/references/nextjs/auth) and `getAuth()` helpers, and the `request` object in server contexts. - Access the custom claims in your application by calling `auth()` in App Router applications or `getAuth(req)` in Pages Router applications. - - The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step. + The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step. This examples are written for Next.js, but they can be adapted to other frameworks by using the appropriate method for accessing the `Auth` object. - ```tsx {{ filename: 'app/page.tsx' }} + ```tsx {{ filename: 'app/api/example/route.tsx' }} import { auth } from '@clerk/nextjs/server' import { NextResponse } from 'next/server' - export default async function Page() { + export async function GET() { const { sessionClaims } = await auth() const fullName = sessionClaims?.fullName From d43786bafe455a5295fa07b3cb59b5e3d915eaac Mon Sep 17 00:00:00 2001 From: Nick Wylynko Date: Fri, 20 Dec 2024 02:52:38 +0800 Subject: [PATCH 7/7] Add legalAcceptedAt and skipLegalChecks fields to user management methods (#1828) Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- docs/references/backend/types/backend-user.mdx | 7 +++++++ docs/references/backend/user/create-user.mdx | 17 ++++++++++++++++- docs/references/backend/user/get-user-list.mdx | 6 ++++-- docs/references/backend/user/get-user.mdx | 3 ++- docs/references/backend/user/update-user.mdx | 17 ++++++++++++++++- docs/references/javascript/user/user.mdx | 2 +- 6 files changed, 46 insertions(+), 6 deletions(-) diff --git a/docs/references/backend/types/backend-user.mdx b/docs/references/backend/types/backend-user.mdx index dafe26a73a..70fb019b9e 100644 --- a/docs/references/backend/types/backend-user.mdx +++ b/docs/references/backend/types/backend-user.mdx @@ -208,6 +208,13 @@ The Backend `User` object is similar to the `User` object as it holds informatio - `number` An integer indicating the number of organizations that can be created by the user. If the value is `0`, then the user can create unlimited organizations. Default is `null`. + + --- + + - `legalAcceptedAt?` + - `number | null` + + The unix timestamp of when the user accepted the legal requirements. `null` if [**Require express consent to legal documents**](/docs/authentication/configuration/legal-compliance) is not enabled. [web3-ref]: /docs/references/javascript/web3-wallet/web3-wallet diff --git a/docs/references/backend/user/create-user.mdx b/docs/references/backend/user/create-user.mdx index 1da75cca6f..d912e6615b 100644 --- a/docs/references/backend/user/create-user.mdx +++ b/docs/references/backend/user/create-user.mdx @@ -201,6 +201,20 @@ function createUser(params: CreateUserParams): Promise --- + - `legalAcceptedAt?` + - `Date` + + The date when the user accepted the legal documents. `null` if [**Require express consent to legal documents**](/docs/authentication/configuration/legal-compliance) is not enabled. + + --- + + - `skipLegalChecks?` + - `boolean` + + When set to `true` all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. + + --- + - `createdAt` - `string` @@ -259,7 +273,8 @@ _User { externalAccounts: [], samlAccounts: [], lastActiveAt: null, - createOrganizationEnabled: true + createOrganizationEnabled: true, + legalAcceptedAt: null } */ ``` diff --git a/docs/references/backend/user/get-user-list.mdx b/docs/references/backend/user/get-user-list.mdx index 8d9864e8bc..b0de35638e 100644 --- a/docs/references/backend/user/get-user-list.mdx +++ b/docs/references/backend/user/get-user-list.mdx @@ -140,7 +140,8 @@ console.log(response) web3Wallets: [], externalAccounts: [Array], lastActiveAt: 1707523200000, - createOrganizationEnabled: true + createOrganizationEnabled: true, + legalAcceptedAt: null }, _User { id: 'user_456', @@ -170,7 +171,8 @@ console.log(response) web3Wallets: [], externalAccounts: [Array], lastActiveAt: 1707523200000, - createOrganizationEnabled: true + createOrganizationEnabled: true, + legalAcceptedAt: null }, ... ], diff --git a/docs/references/backend/user/get-user.mdx b/docs/references/backend/user/get-user.mdx index 4122ea8d16..166b6a44e5 100644 --- a/docs/references/backend/user/get-user.mdx +++ b/docs/references/backend/user/get-user.mdx @@ -67,7 +67,8 @@ _User { web3Wallets: [], externalAccounts: [], lastActiveAt: null, - createOrganizationEnabled: true + createOrganizationEnabled: true, + legalAcceptedAt: null } */ ``` diff --git a/docs/references/backend/user/update-user.mdx b/docs/references/backend/user/update-user.mdx index b146c6f9cd..4675846a50 100644 --- a/docs/references/backend/user/update-user.mdx +++ b/docs/references/backend/user/update-user.mdx @@ -186,6 +186,20 @@ function updateUser(userId: string, params: UpdateUserParams): Promise --- + - `legalAcceptedAt?` + - `Date` + + The date when the user accepted the legal documents. `null` if [**Require express consent to legal documents**](/docs/authentication/configuration/legal-compliance) is not enabled. + + --- + + - `skipLegalChecks?` + - `boolean` + + When set to `true` all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. + + --- + - `createdAt?` - `Date` @@ -257,7 +271,8 @@ _User { ], samlAccounts: [], lastActiveAt: 1720205704451, - createOrganizationEnabled: true + createOrganizationEnabled: true, + legalAcceptedAt: null } */ ``` diff --git a/docs/references/javascript/user/user.mdx b/docs/references/javascript/user/user.mdx index e536085839..69b3927afa 100644 --- a/docs/references/javascript/user/user.mdx +++ b/docs/references/javascript/user/user.mdx @@ -255,7 +255,7 @@ The ClerkJS SDK provides some helper [methods](#methods) on the `User` object to - `legalAcceptedAt` - `Date` - Date when the user accepted the legal documents. May be empty if [**Require express consent to legal documents**](/docs/authentication/configuration/legal-compliance) is not enabled. + The date when the user accepted the legal documents. `null` if [**Require express consent to legal documents**](/docs/authentication/configuration/legal-compliance) is not enabled. ---