Skip to content

Rewrite Google SAML docs for application owners #2157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Rewrite Google SAML docs for application owners #2157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ae57266
intro paragraph
alexisintech Apr 2, 2025
5829190
wip
alexisintech Aug 1, 2025
2e0e64f
update
alexisintech Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/_partials/authentication/saml/enable-connection.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
126 changes: 61 additions & 65 deletions docs/authentication/enterprise-connections/saml/google.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,9 @@ 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
</TutorialHero>
/>

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.

<Steps>
## Enable Google as a SAML connection in Clerk
Expand All @@ -32,92 +28,92 @@ To make the setup process easier, it's recommended to keep two browser tabs open
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.

## Create a new enterprise application in Google
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.

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.
## Configure SAML app

## Configure Google as your Identity Provider
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:

There are two options for configuring 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.

- **[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.
To get you started, you can use the following email template with detailed instructions:

### Metadata configuration
<Copyable as="html">
Here are the instructions for setting up SAML SSO with 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.
**Step 1: Create a new enterprise app in Google**

### Custom configuration
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**.

If you choose to manually input the configuration settings for your IdP, you must add these three fields to your Clerk settings:
**Step 2: Share the app's metadata URL**

- **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.
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.

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.
**Step 3: Verify correct configuration of attributes and claims**

## Configure Clerk as your Service Provider
We expect your SAML responses to have the following specific attributes:

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**.
- 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`

## Map Google claims to Clerk attributes
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:

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.
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.

| Clerk attribute | Google claim |
| - | - |
| `mail` | Basic Information > Primary email |
| `firstName` | Basic Information > First name |
| `lastName` | Basic Information > Last name |
**Step 4: Map additional claims (optional)**

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.
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.

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.
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.

### Map other claims (optional)
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`.

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.
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.

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.
The value for the user's phone number will be saved in the user's `User.publicMetadata` under the key `phone_number`.

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`.
Learn more about [how to access the metadata from our APIs](/docs/users/metadata).

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.
**Step 5: Enable the connection**

The value for the user's phone number will be saved in the user's `User.publicMetadata` under the key `phone_number`.
Once the configuration is complete in Google, you'll be redirected to the app's overview page.

Learn more about [how to access the metadata from our APIs](/docs/users/metadata).
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**.
</Copyable>

## Enable the connection in Google
## Add the metadata file to the Clerk app

Once the configuration is complete in Google, you'll be redirected to the app's overview page.
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.

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

Expand Down