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”.
Select “Google SAML” from the Identity Provider dropdown, enter a descriptive name for the connection, and then select the “Create Connection” button.
WorkOS provides the ACS URL and the SP Entity ID. It’s readily available in your Connection Settings 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”.
Give the app a descriptive name and upload an icon, if applicable. Click “Continue”.
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”.
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.”
Provide the following Attribute Mappings and select “Finish”.
Google SAML does not provide the option to map a user’s id attribute claim.
With identity provider role assignment, users can receive roles within your application based on their group memberships. To return this information in the attribute statement, follow the guidance below.
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”.
Finish role assignment set-up by navigating to the Connection page in the Organization section of the WorkOS Dashboard. Create connection groups referencing the group IdP ID. Then, assign roles to connection groups so users in those groups will automatically be granted roles within your application.
In the created SAML app’s landing page, select the “User Access Section”.
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”.
In the connection Settings of the WorkOS Dashboard, click “Edit Metadata Configuration”.
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!
