WorkOS Docs Homepage
DashboardSign In

Google SAML

Learn how to configure a connection to Google Workspace via SAML.

Each SSO Identity Provider requires specific information to create and configure a new connection. Often, the information required to create a connection will differ by Identity Provider.

To create a Google SAML connection, you’ll need three pieces of information: an ACS URL, a SP Entity ID, and an IdP Metadata URL.

Start by logging into your WorkOS Dashboard and selecting “Organizations” from the left hand navigation bar.

Click on the organization you’d like to configure a Google SAML connection for and select “Manually Configure Connection”.

A screenshot showing where to find “Manually Configure Connection” for an Organization in the WorkOS Dashboard.

Select “Google SAML” from the Identity Provider dropdown, enter a descriptive name for the connection, and then select the “Create Connection” button.

A screenshot showing how to create a connection in the WorkOS Dashboard.

WorkOS provides the ACS URL and the SP Entity ID. It’s readily available in your Connection Settings in the WorkOS Dashboard.

A screenshot showing where to find the ACS URL and SP Entity ID in the WorkOS Dashboard.

The ACS URL is the location an Identity Provider redirects its authentication response to. In Google’s case, it needs to be set by the organization when configuring your application in their Google admin dashboard.

The SP Entity ID is a URI used to identify the issuer of a SAML request, response, or assertion. In this case, the entity ID is used to communicate that WorkOS will be the party performing SAML requests to the organization's Google instance.

Specifically, the ACS URL will need to be set as the “ACS URL” and the SP Entity ID will need to be set as the “Entity ID” in the “Service Provider Details” step of the Google SAML setup.

In order to integrate you’ll need the metadata XML file from Google.

Normally, this information will come from the organization's IT Management team when they set up your application’s SAML 2.0 configuration in their Google admin dashboard. But, should that not be the case during your setup, here’s how to obtain it.

Log in to the Google Admin dashboard, select “Apps” from the sidebar menu, and then select “Web and Mobile Apps” from the following list. If your application is already created, select it from the list of applications and move to Step 7. If you haven’t created a SAML application, select “Add App” and then “Add custom SAML app”.

A screenshot showing where to find "Add custom SAML app" in the Google Dashboard.

Give the app a descriptive name and upload an icon, if applicable. Click “Continue”.

A screenshot showing where to add app name in the Google Dashboard.

Select the “Download Metadata” button to download the metadata file. Save this file, as you’ll upload it to the WorkOS Dashboard in Step 7. Click “Continue”.

A screenshot showing where to find "Download Metadata" in the Google Dashboard.

Copy and the “ACS URL” from your WorkOS Dashboard and paste it into the “ACS URL” field, and copy the “SP Entity ID” from your WorkOS Dashboard and paste it into the “Entity ID” field in the Google SAML “Service provider details” modal. Select “Continue.”

A screenshot showing where to enter "Entity ID" and "ACS URL" in the Google Dashboard.

Provide the following Attribute Mappings and select “Finish”.

Google SAML does not provide the option to map a user’s id attribute claim.

A screenshot showing completed Attribute Mappings in the Google Dashboard.

Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.

This feature is currently in beta, contact customer support for more information.

Scroll down to the "Group membership" section. Add any groups you'd like to send under "Google groups", and set the "App attribute" to "groups". Then, select "Finish".

A screenshot showing how to add a group attribute in the Google dashboard.

In the created SAML app’s landing page, select the “User Access Section”.

A screenshot showing where to find the "User Access Section" in the Google Dashboard.

Turn this service ON for the correct organizational units in your Google Directory setup. Save any changes.

Google may take up to 24 hours to propagate these changes. The connection in WorkOS will be inactive until then.

If you haven’t already downloaded the metadata file, select your SAML application, and click “Download Metadata”. In the modal, again click “Download Metadata”.

A screenshot showing where to find "Download Metadata" in the Google Dashboard.

In the connection Settings of the WorkOS Dashboard, click “Edit Metadata Configuration”.

A screenshot showing the “Edit Metadata Configuration” button in the WorkOS Dashboard.

In the modal, upload the Google Metadata file and then select “Save Metadata Configuration”. Once the file is uploaded into WorkOS, your connection will then be linked and good to go!

A screenshot showing a linked Google SAML connection in the WorkOS Dashboard.

Where is the Relay State in Google SAML?

Within the Google SAML setup, there will be a field called “Start URL” which is referred to as the Relay State.