Add Google Workspace as a SAML connection

Set up an enterprise connection in Clerk

To create 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.
3. Under SAML, select Google Workspace as the identity provider.
4. Add the Name of the connection. This is the name that will be displayed in the sign-in form.
5. 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.
6. Select Add connection. You'll be redirected to the connection's configuration page.

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. 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 - 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. 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 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. Navigate to the Clerk Dashboard and 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 on 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, you should still have the connection's configuration page open. If not, navigate to the SSO connections page and select the connection.
2. Toggle on Enable connection and select Save.