# Single sign-on with Google Workspace

> Page: https://docs.plotwork.dev/single-sign-on-google-workspace. Index of every page: https://docs.plotwork.dev/llms.txt

Connect an Enterprise organisation to Google Workspace with OpenID Connect or SAML 2.0. Prove your email domain in Plotwork first, as the [single sign-on guide](https://docs.plotwork.dev/single-sign-on.md) describes.

## TL;DR

| Plotwork field | Where it comes from in Google Cloud |
|---|---|
| Issuer URL | `https://accounts.google.com` |
| Client ID | The OAuth client's Client ID, ending in `.apps.googleusercontent.com` |
| Client secret | The OAuth client's Client secret |
| Redirect URI to give Google | `https://api.plotwork.dev/auth/sso/callback`, under Authorized redirect URIs |
| SAML: ACS URL and Entity ID to give Google | The ACS URL and the Entity ID on Plotwork's Single sign-on tab |
| SAML: metadata | The custom SAML app's IdP metadata file, pasted into Plotwork |

## 1. Set up the consent screen

1. In the Google Cloud console, choose or create a project in your Workspace organisation.
2. Open APIs & Services, then OAuth consent screen (Google Auth Platform, Branding and Audience in newer consoles).
3. Set the user type, or Audience, to Internal, so only accounts in your Workspace can sign in.
4. Fill in the app name (`Plotwork`), the support email and the developer contact, and save.

## 2. Make the OAuth client

1. Open APIs & Services, then Credentials, press Create credentials, and choose OAuth client ID.
2. Fill in the form:

| Google field | Value |
|---|---|
| Application type | Web application |
| Name | `Plotwork` |
| Authorized JavaScript origins | Leave empty |
| Authorized redirect URIs | `https://api.plotwork.dev/auth/sso/callback` |

3. Press Create, and copy the Client ID and the Client secret.

## 3. Copy the values into Plotwork

In Plotwork, open your organisation's Single sign-on tab and fill in Identity provider:

| Plotwork field | Value |
|---|---|
| Issuer URL | `https://accounts.google.com` |
| Client ID | The Client ID you copied |
| Client secret | The Client secret you copied |

Press Save provider, then turn on Sign in with single sign-on.

## How Plotwork tells your Workspace from others

Every Google account signs in at the same issuer, so Plotwork checks two more things for Google. The ID token must carry the `hd` claim, which Google sets only for a Workspace account, and it must equal the domain of the person's address. The address must also be on a domain you verified in Plotwork. A personal Google account, or a Workspace account of another company, is refused even if it signs in at Google.

## Or connect with SAML 2.0

1. In the Google Admin console, open Apps, then Web and mobile apps, then Add app, then Add custom SAML app. Name it `Plotwork` and press Continue.
2. On Google Identity Provider details, press Download Metadata and keep the file. Press Continue.
3. In Plotwork's Single sign-on tab, choose SAML 2.0 under Identity provider, then fill in Google's Service provider details from it:

| Google field | Value |
|---|---|
| ACS URL | The ACS URL from Plotwork |
| Entity ID | The Entity ID from Plotwork |
| Start URL | Leave empty |
| Signed response | Either. Plotwork accepts a signed assertion or a signed response. |
| Name ID format | EMAIL |
| Name ID | Basic Information, Primary email |

4. Press Continue, skip Attribute mapping, and press Finish.
5. Open the app's User access and turn it on for everyone, or for the organisational units or groups who should sign in. Google can take a few minutes to apply it.
6. In Plotwork, open the metadata file you downloaded, paste all of it under Or paste the metadata XML, leave Email attribute empty, and press Save provider. Then turn on Sign in with single sign-on.

Google's certificate for the app lasts five years. When you make a new one under Manage certificates, download the metadata again and paste it into Plotwork.

With SAML, the address check is the same as above: only addresses on domains you verified in Plotwork sign in.

## Troubleshooting

| What you see | What to check |
|---|---|
| "Your identity provider did not sign you in" | The consent screen is set to Internal and the person's account is outside your Workspace, or they cancelled. |
| "Your address is not on a domain your organisation verified" | The person used a personal Google account, or an address on a domain you have not verified in Plotwork. |
| Google says `redirect_uri_mismatch` | The redirect URI in the OAuth client is not exactly `https://api.plotwork.dev/auth/sso/callback`. |
| Google says `app_not_configured_for_user` with SAML | User access is off for the person's organisational unit or group, or the change has not applied yet. |
| "Your identity provider sent a sign-in Plotwork could not trust" with SAML | The ACS URL or the Entity ID at Google is not Plotwork's, or the certificate changed and the metadata in Plotwork is the old one. |

## See also

| Page | Why |
|---|---|
| [Single sign-on](https://docs.plotwork.dev/single-sign-on.md) | Domains, the switches, Require single sign-on and the way back in |
| [Single sign-on with Okta](https://docs.plotwork.dev/single-sign-on-okta.md) | The same for Okta |
| [Single sign-on with Microsoft Entra ID](https://docs.plotwork.dev/single-sign-on-entra-id.md) | The same for Microsoft Entra ID |