Add Google Workspace as a SAML connection

Enable Google as a SAML connection in Clerk

1. In the Clerk Dashboard, navigate to the SSO connections⁠ page.
2. Select Add connection and select For specific domains or organizations.
3. Under SAML, select Google Workspace.
4. 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.
5. Enter the Name. This will be displayed on the sign-in form.
6. Select Add connection. You'll be redirected to the connection's configuration page.
7. 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. 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 Google as your Identity Provider

There are two options for configuring your identity provider:

• Metadata configuration (recommended) - A URL or file to your IdP's metadata. This is quicker than manually inputting the configuration settings.
• Custom configuration - 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. Navigate back to the Clerk Dashboard and in the Identity Provider Configuration section, select the Upload file button.
3. Upload the metadata file you downloaded from Google.

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

1. In the Google Admin Console, under Option 2, copy the SSO URL, Entity ID, and download the Certificate.
2. Navigate back to the Clerk Dashboard and in the Identity Provider Configuration section, select Use manual configuration.
3. Fill in the SSO URL, Entity ID, and upload the Certificate. Don't forget to select Save.
4. In the Google Admin Console, select the Continue button.

Configure Clerk as your Service Provider

1. In the Google Admin Console, paste the ACS URL and Entity ID values you saved from the Clerk Dashboard into their respective fields.
2. Under the Name ID section, select the Name ID format dropdown and select Email.
3. Select Continue.

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 authenticate into your application.

1. In the Google Admin Console, under the Attributes section, select Add mapping.
2. Select the dropdown under Google Directory attributes.
3. Select Primary email.
4. In the App attributes field, enter mail.
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 Clerk's 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. In the App attributes field, enter public_metadata_phone_number.
4. 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 in Google

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.
2. Select ON for everyone.
3. Select Save.

Enable the connection in Clerk

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⁠ page and select the connection.
2. At the top of the page, toggle on Enable connection and select Save.