# Google Workspace SAML single sign-on

<!-- Generated by scripts/generate.ts. Do not edit. -->

Add a custom SAML app in the Google Admin console, paste the values from this setup, turn the app on for your users and share Google's metadata with us.

:::caution[Verification]
Not yet verified on a real Google Workspace tenant. It was written from the public Google Workspace documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="create-app"></a>

### Add a custom SAML app

Sign in to the Google Admin console as a super administrator. Go to Menu > Apps > Web and mobile apps, select Add App > Add custom SAML app, enter an app name and select Continue.

</li>

<li class="idp-step">

<a id="metadata"></a>

### Download Google's metadata

On the Google Identity Provider details page, download the IdP metadata and add it to this setup, then select Continue. Do this again whenever the certificate changes.

Fixes: [`saml_signature_invalid`](/errors/saml_signature_invalid/), [`saml_issuer_mismatch`](/errors/saml_issuer_mismatch/)

</li>

<li class="idp-step">

<a id="acs"></a>

### Enter the ACS URL

On the Service provider details page, paste `{acs_url}` into ACS URL.

<div class="setup-values">

Paste into Google Workspace:

- ACS URL: `{acs_url}`

</div>

Fixes: [`saml_destination_mismatch`](/errors/saml_destination_mismatch/), [`saml_response_malformed`](/errors/saml_response_malformed/)

</li>

<li class="idp-step">

<a id="entity-id"></a>

### Enter the entity ID

Paste `{sp_entity_id}` into Entity ID.

<div class="setup-values">

Paste into Google Workspace:

- SP entity ID: `{sp_entity_id}`

</div>

Fixes: [`saml_audience_mismatch`](/errors/saml_audience_mismatch/)

</li>

<li class="idp-step">

<a id="name-id"></a>

### Send the email address as the name ID

Set Name ID format to EMAIL and Name ID to Basic Information > Primary email, then select Continue. Leave Signed response as it is unless your app's support asks you to change it.

Fixes: [`saml_nameid_missing`](/errors/saml_nameid_missing/)

</li>

<li class="idp-step">

<a id="attributes"></a>

### Map the attributes

On the Attribute mapping page, select Add mapping and map Primary email to email, First name to firstName and Last name to lastName. To send groups, add them under Group membership with the app attribute groups. Select Finish.

Fixes: [`saml_email_missing`](/errors/saml_email_missing/)

</li>

<li class="idp-step">

<a id="assign"></a>

### Turn the app on

Open the app, select User access, choose On for everyone (or turn it on for the right organizational units) and select Save.

Fixes: [`saml_idp_status_error`](/errors/saml_idp_status_error/)

</li>

<li class="idp-step">

<a id="test"></a>

### Test the connection

Run a test sign-in in this setup, signing in as a user the app is turned on for. Changes in Google can take a little while to apply.

</li>

</ol>

<a id="standby"></a>

## Standby sign-in is not available

Google Workspace accepts a single ACS URL per custom SAML app, so this connection cannot use the standby address. In the rare case of an outage of our main network, sign-ins pause until it ends. There is nothing to set up.

This step is optional. See [standby route behavior](/trust/standby/) for what the standby address does during an outage.

## Sources

- [Set up your own custom SAML app (Google Workspace Admin Help)](https://knowledge.workspace.google.com/admin/apps/set-up-your-own-custom-saml-app), read on 2026-10-11
