Use Google Workspace for SAML SSO

Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

1. Navigate to the Clerk Dashboard⁠.
2. In the navigation sidebar, select User & Authentication > Enterprise Connections⁠.
3. Select the Create connection button.
4. You will be presented with a modal to create a new connection. Fill in the required fields and for the Identity Provider, select Google Workspace.
5. Next, on the Connection page, do not select the Enable connection toggle just yet. You need to fully configure your IdP first before exposing your connection to your users.
6. Leave this page open. You will need to come back to it to complete the setup.

Create a new enterprise application in Google

To create a new enterprise application in Google:

1. Navigate to the Google Admin Console⁠ and sign in.
2. In the navigation sidebar, under Apps, select Web and mobile apps.
3. Select the Add app button.
4. From the dropdown, select Add custom SAML app.
5. In the App details section, an App name is required.
6. Select the Continue button.

Configure your identity provider

There are two options for configuring your IdP:

• Metadata configuration - This is where you can input the URL to your IdP's metadata file. This is the recommended way to configure your IdP.
• Custom configuration - This is where you can manually input the configuration settings for your IdP.

Metadata configuration

1. In the Google Admin Console, under Option 1: Download IdP Metadata, select the Download Metadata button.
2. In the Clerk Dashboard, find the Identity Provider configuration section.
3. Under the Metadata configuration option, select the Upload button.
4. Upload the metadata file you downloaded from Google.
5. Select the Save changes button to complete the setup.

Custom configuration

If you choose to manually input the configuration settings for your IdP, you must add these three fields to your Clerk settings:

• SSO URL - This is the unique identifier of your IdP application.
• Entity ID - This is your IdP's URL that Clerk will redirect your users to so that they can authenticate.
• Certificate - This is the certificate needed for Clerk to securely connect to your IdP.

1. In the Google Admin Console, under Option 2, copy the SSO URL, Entity ID, and download the Certificate.
2. In the Clerk Dashboard, find the Identity Provider configuration section.
3. Select the Custom configuration option.
4. Fill in the SSO URL, Entity ID, and upload the Certificate.
5. Select the Save changes button in the Clerk Dashboard.
6. Select the Continue button in the Google Admin Console.

Configure your service provider

To configure your service provider (Clerk), you will need to add these two fields to your IdP's application:

• ACS URL - This is a unique identifier for your SAML connection that your IdP application needs.
• Entity ID - This is your application's URL that your IdP will redirect your users back to after they have authenticated in your IdP.

To fill out the appropriate values for these fields:

1. In the Clerk Dashboard, find the Service Provider configuration section.
2. Copy the ACS URL and Entity ID.
3. In the Google Admin Console, paste these values into their respective fields.
4. Under the Name ID section, select the dropdown for Name ID format and select Email.

Map Google claims to Clerk attributes

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.

The only Google claim that is necessary to map is the Primary email. This is the email address that your users will use to log in to your application.

1. In the Google Admin Console, under the Attributes section, select the dropdown under Google Directory attributes.
2. Select Primary email.
3. Select the dropdown under App attributes.
4. Enter mail in the field.
5. 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 section. Otherwise, select the Finish button.

Map other claims (optional)

In Clerk, the User object has a publicMetadata property that you can use to store additional information about your users.

To map other claims from Google that don't have a direct mapping to Clerk attributes, you can map them to the publicMetadata property. To do this, prepend the Clerk claims with public_metadata_ during the mapping process.

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.

1. In the Google Admin Console, under the Attributes section, select the dropdown under Google Directory attributes.
2. Select Phone number.
3. Select the empty input under App attributes.
4. Enter public_metadata_phone_number in the field.
5. Select the Finish button.

The value for the user's phone number will be saved in the user's User.publicMetadata under the key phone_number.

Learn more about how to access the metadata from our APIs.⁠

Enable the connection for Google

Once the configuration is complete, you will be redirected to the app details page.

1. In the User access section, select View details.
2. In the Service status section, select ON for everyone.
3. Select the Save button.

Enable the connection for Clerk

To make the connection available for your users to authenticate with:

1. In the Clerk Dashboard, scroll to the top of the Connection page.
2. Toggle on the Enable connection option.