Add Google Workspace as a SAML connection

Create a Google Workspace 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. You'll need to give these to the customer so they can configure their Google Workspace application.

Configure SAML application

Now the customer's Google Workspace application needs to be configured with the ACS URL and Entity ID from Clerk.

To get you started, you can use the following email template with detailed instructions. Remember to share the ACS URL and Entity ID:

Add the IdP configuration in Clerk

Once the customer has shared their Google Workspace details, add them to the connection. There are two options:

• Metadata configuration (recommended) - Use the metadata file the customer downloaded from Google. This is quicker than manually inputting the configuration settings.
• Custom configuration - Manually input the configuration settings.

Metadata configuration

1. In the Clerk Dashboard, open the connection and, in the Identity Provider Configuration section, select Upload file.
2. Upload the metadata file that the customer shared.

Custom configuration

If you're configuring the connection manually, fill in these three fields in the Clerk Dashboard:

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

1. In the Identity Provider Configuration section, select Use manual configuration.
2. Fill in the SSO URL and Entity ID, and upload the Certificate that the customer shared. Select Save.

Map IdP claims to Clerk fields

Clerk automatically maps the standard SAML claims (email, first name, and last name) to the User object. To review them, open the connection's SSO tab and find the Common attributes section under Attribute mapping.

To map a claim that has no standard Clerk field, store it in the user's publicMetadata. The approach depends on whether the connection also uses Directory Sync:

• SSO only: In the IdP, prefix the claim name with public_metadata_. For example, mapping a phone number to public_metadata_phone_number stores it under phone_number in User.publicMetadata. Some IdPs, such as Microsoft Entra, send claims as URLs; map those as plain strings.
• SSO with Directory Sync: Define a custom attribute so the mapping applies to both SSO and SCIM. Define it on the connection's Overview tab (in the Identity provider attributes section), then map it in the SSO tab (in the Custom attributes section of the Attribute mapping section). Refer to the guide on custom attribute mapping. While Directory Sync is enabled, SCIM is the only source for these values and overrides SSO.

Learn more about accessing user metadata from the API.

Enable the connection in Clerk

You have configured the SAML connection. Once enabled, all users with email addresses ending in the domain will be redirected to your identity provider at sign-up and sign-in.

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

1. Navigate to the SSO connections⁠ page and select the connection.
2. At the top of the page, toggle on Enable connection and select Save.