From ae57266edd685950c5134c02bedb431cf9c11eb6 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 2 Apr 2025 15:15:12 -0400 Subject: [PATCH 1/3] intro paragraph --- docs/authentication/enterprise-connections/saml/google.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/authentication/enterprise-connections/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx index 6bec89f088..c934f87af9 100644 --- a/docs/authentication/enterprise-connections/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -20,9 +20,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. - Use Google Workspace to enable SSO via SAML for your Clerk app -Enabling SAML with Google allows your users to sign up and sign in to your Clerk application with their Google account. - -To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Admin Console](https://admin.google.com/). +Enabling SAML with Google allows your users to sign up and sign in to your Clerk application with their Google account. It requires that a SAML connection is configured in both the Clerk Dashboard and Google Admin Console. This guide assumes that you have access to the Clerk app's settings in the Clerk Dashboard. The "customer" in this case is whoever has access to the Google Admin Console. ## Enable Google as a SAML connection in Clerk From 582919071a27d1e54c3d956530ceae2a8c5af025 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 1 Aug 2025 17:23:08 -0400 Subject: [PATCH 2/3] wip --- .../enterprise-connections/saml/google.mdx | 127 +++++++++--------- 1 file changed, 65 insertions(+), 62 deletions(-) diff --git a/docs/authentication/enterprise-connections/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx index c934f87af9..e67017953f 100644 --- a/docs/authentication/enterprise-connections/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -16,9 +16,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO. icon: "key", } ]} -> - - Use Google Workspace to enable SSO via SAML for your Clerk app - +/> Enabling SAML with Google allows your users to sign up and sign in to your Clerk application with their Google account. It requires that a SAML connection is configured in both the Clerk Dashboard and Google Admin Console. This guide assumes that you have access to the Clerk app's settings in the Clerk Dashboard. The "customer" in this case is whoever has access to the Google Admin Console. @@ -30,94 +28,99 @@ Enabling SAML with Google allows your users to sign up and sign in to your Clerk 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. - 1. In the **Service Provider Configuration** section, save the **ACS URL** and **Entity ID** values somewhere secure. Keep this page open. + 1. Select **Add connection**. You'll be redirected to the connection's configuration page. Note that the connection is disabled by default. + 1. In the **Service Provider Configuration** section, save the **ACS URL** and **Entity ID** values somewhere secure. You'll need to give these to the customer so they can configure their Google app. - ## Create a new enterprise application in Google + ## Configure SAML app - 1. Navigate to the [Google Admin Console](https://admin.google.com/) and sign in. - 1. In the navigation sidenav, under **Apps**, select **Web and mobile apps**. - 1. Select the **Add app** button. - 1. From the dropdown, select **Add custom SAML app**. - 1. In the **App details** section, an **App name** is required. - 1. Select the **Continue** button. + Now that the enterprise connection is configured in Clerk and the **ACS URL** and **Entity ID** are known, the customer's Google app needs to be configured. At a high level, the process is: - ## Configure Google as your Identity Provider + - Create a new enterprise application in Google. + - Add the **ACS URL** and **Entity ID** from Clerk to the Google app's SAML configuration. + - Verify that the attribute mappings are correct. + - Obtain and share the app's metadata file. - There are two options for configuring your identity provider: + To get you started, you can use the following email template with detailed instructions: - - **[Metadata configuration](#metadata-configuration) (recommended)** - A URL or file to your IdP's metadata. This is quicker than manually inputting the configuration settings. - - [**Custom configuration**](#custom-configuration) - Manually input the configuration settings for your IdP. + + Here are the instructions for setting up SAML SSO with Google: - ### Metadata configuration + **Step 1: Create a new enterprise app in Google** - 1. In the Google Admin Console, under **Option 1: Download IdP Metadata**, select the **Download Metadata** button. - 1. Navigate back to the Clerk Dashboard and in the **Identity Provider Configuration** section, select the **Upload file** button. - 1. Upload the metadata file you downloaded from Google. + 1. Navigate to the [Google Admin Console](https://admin.google.com/) and sign in. + 1. In the navigation sidenav, under **Apps**, select **Web and mobile apps**. + 1. Select the **Add app** button. + 1. From the dropdown, select **Add custom SAML app**. + 1. In the **App details** section, an **App name** is required. + 1. Select the **Continue** button. + 1. Paste the **ACS URL** and **Entity ID** values you saved from the Clerk Dashboard into their respective fields. + 1. Under the **Name ID** section, select the **Name ID format** dropdown and select **Email**. + 1. Select **Continue**. - ### Custom configuration + **Step 2: Share the app's metadata URL** - If you choose to manually input the configuration settings for your IdP, you must add these three fields to your Clerk settings: + Under **Option 1: Download IdP Metadata**, select the **Download Metadata** button. Send this file to the Clerk app admin so they can connect the Clerk app to the Google app. - - **SSO URL** - The unique identifier of your IdP application. - - **Entity ID** - Your IdP's URL that Clerk will redirect your users to so that they can authenticate. - - **Certificate** - The certificate needed for Clerk to securely connect to your IdP. + **Step 3: Verify correct configuration of attributes and claims** - 1. In the Google Admin Console, under **Option 2**, copy the **SSO URL**, **Entity ID**, and download the **Certificate**. - 1. Navigate back to the Clerk Dashboard and in the **Identity Provider Configuration** section, select **Use manual configuration**. - 1. Fill in the **SSO URL**, **Entity ID**, and upload the **Certificate**. Don't forget to select **Save**. - 1. In the Google Admin Console, select the **Continue** button. + We expect your SAML responses to have the following specific attributes: - ## Configure Clerk as your Service Provider + - Email address (required). This is the email address that your users will use to authenticate into your app: + - Claim name: `user.email` + - First name (optional): + - Claim name: `user.firstName` + - Last name (optional): + - Claim name: `user.lastName` - 1. In the Google Admin Console, paste the **ACS URL** and **Entity ID** values you saved from the Clerk Dashboard into their respective fields. - 1. Under the **Name ID** section, select the **Name ID format** dropdown and select **Email**. - 1. Select **Continue**. + These are the defaults, and probably won't need you to change them. However, many SAML configuration errors are due to incorrect attribute mappings, so it's worth double-checking. Here's how: - ## Map Google claims to Clerk attributes + 1. In the Google Admin Console, under the **Attributes** section, select **Add mapping**. + 1. Select the dropdown under **Google Directory attributes**. + 1. Select **Primary email**. + 1. In the **App attributes** field, enter `mail`. + 1. If you have additional claims that you would like to map to Clerk, see the next step. Otherwise, select the **Finish** button. - Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk. + **Step 4: Map additional claims (optional)** - | Clerk attribute | Google claim | - | - | - | - | `mail` | Basic Information > Primary email | - | `firstName` | Basic Information > First name | - | `lastName` | Basic Information > Last name | + In Clerk, the [`User`](/docs/users/overview#user-object) object has a `publicMetadata` property that you can use to store additional information about your users. - The only Google claim that is necessary to map is the **Primary email**. This is the email address that your users will use to authenticate into your application. + To map other claims from Google that don't have a direct mapping to Clerk attributes, you can map them to Clerk's `publicMetadata` property. To do this, prepend the Clerk claims with `public_metadata_` during the mapping process. - 1. In the Google Admin Console, under the **Attributes** section, select **Add mapping**. - 1. Select the dropdown under **Google Directory attributes**. - 1. Select **Primary email**. - 1. In the **App attributes** field, enter `mail`. - 1. If you have additional claims that you would like to map to Clerk, you can do so by following the steps in the [Map other claims](#map-other-claims-optional) section. Otherwise, select the **Finish** button. + For example, say your users have the "Phone number" attribute in Google. You can map this to your users' public metadata in Clerk by mapping the Google field to `public_metadata_phone_number`. - ### Map other claims (optional) + 1. In the Google Admin Console, under the **Attributes** section, select the dropdown under **Google Directory attributes**. + 1. Select **Phone number**. + 1. In the **App attributes** field, enter `public_metadata_phone_number`. + 1. Select the **Finish** button. - In Clerk, the [`User`](/docs/users/overview#user-object) object has a `publicMetadata` property that you can use to store additional information about your users. + The value for the user's phone number will be saved in the user's `User.publicMetadata` under the key `phone_number`. - To map other claims from Google that don't have a direct mapping to Clerk attributes, you can map them to Clerk's `publicMetadata` property. To do this, prepend the Clerk claims with `public_metadata_` during the mapping process. + Learn more about [how to access the metadata from our APIs](/docs/users/metadata). - For example, say your users have the "Phone number" attribute in Google. You can map this to your users' public metadata in Clerk by mapping the Google field to `public_metadata_phone_number`. + **Step 5: Enable the connection** - 1. In the Google Admin Console, under the **Attributes** section, select the dropdown under **Google Directory attributes**. - 1. Select **Phone number**. - 1. In the **App attributes** field, enter `public_metadata_phone_number`. - 1. Select the **Finish** button. + Once the configuration is complete in Google, you'll be redirected to the app's overview page. - The value for the user's phone number will be saved in the user's `User.publicMetadata` under the key `phone_number`. + 1. In the **User access** section, select **OFF for everyone**. You'll be redirected to the **Service status** page. + 1. Select **ON for everyone**. + 1. Select **Save**. + - Learn more about [how to access the metadata from our APIs](/docs/users/metadata). + ## Add the metadata file to the Clerk app - ## Enable the connection in Google + After following the instructions in the email, your customer should have sent you the Google app's metadata file. Now, you're going to add it to the Clerk connection, completing the SAML connection configuration. - Once the configuration is complete in Google, you'll be redirected to the app's overview page. - - 1. In the **User access** section, select **OFF for everyone**. You'll be redirected to the **Service status** page. - 1. Select **ON for everyone**. - 1. Select **Save**. + 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 connection you created in the previous step. + 1. In the **Identity Provider Configuration** section, select **Upload file**. + 1. Upload the metadata file you received from your customer. Keep this page open. ## Enable the connection in Clerk + The SAML connection is ready to enable! Once enabled, all users with email addresses ending in the domain will be redirected to Okta at sign-up and sign-in. + + > [!WARNING] + > If there are existing users with email domains that match the SAML connection, and there is an error in the SAML configuration in Clerk or Okta, those users will be **unable to sign in** when the connection is enabled. If this is a concern, we recommend coordinating with your counterpart to test the connection at an off-peak time. + From 2e0e64f2b8cbf039a703bb1cb4c09c0318d6a47e Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 1 Aug 2025 17:25:11 -0400 Subject: [PATCH 3/3] update --- docs/_partials/authentication/saml/enable-connection.mdx | 5 +++++ docs/authentication/enterprise-connections/saml/google.mdx | 5 ----- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_partials/authentication/saml/enable-connection.mdx b/docs/_partials/authentication/saml/enable-connection.mdx index a9840fd7be..c7be223127 100644 --- a/docs/_partials/authentication/saml/enable-connection.mdx +++ b/docs/_partials/authentication/saml/enable-connection.mdx @@ -1,3 +1,8 @@ +The SAML connection is ready to enable! Once enabled, all users with email addresses ending in the domain will be redirected to Okta at sign-up and sign-in. + +> [!WARNING] +> If there are existing users with email domains that match the SAML connection, and there is an error in the SAML configuration in Clerk or Okta, those users will be **unable to sign in** when the connection is enabled. If this is a concern, we recommend coordinating with your counterpart to test the connection at an off-peak time. + To make the connection available for your users to authenticate with: 1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. diff --git a/docs/authentication/enterprise-connections/saml/google.mdx b/docs/authentication/enterprise-connections/saml/google.mdx index e67017953f..f06cda466b 100644 --- a/docs/authentication/enterprise-connections/saml/google.mdx +++ b/docs/authentication/enterprise-connections/saml/google.mdx @@ -117,10 +117,5 @@ Enabling SAML with Google allows your users to sign up and sign in to your Clerk ## Enable the connection in Clerk - The SAML connection is ready to enable! Once enabled, all users with email addresses ending in the domain will be redirected to Okta at sign-up and sign-in. - - > [!WARNING] - > If there are existing users with email domains that match the SAML connection, and there is an error in the SAML configuration in Clerk or Okta, those users will be **unable to sign in** when the connection is enabled. If this is a concern, we recommend coordinating with your counterpart to test the connection at an off-peak time. -