Hosted diagrams and plans

Single sign-on with Google Workspace

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 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

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

2. Make the OAuth client

Open APIs & Services, then Credentials, press Create credentials, and choose OAuth client ID.
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`

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

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.
On Google Identity Provider details, press Download Metadata and keep the file. Press Continue.
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

Press Continue, skip Attribute mapping, and press Finish.
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.
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.

Page	Why
Single sign-on	Domains, the switches, Require single sign-on and the way back in
Single sign-on with Okta	The same for Okta
Single sign-on with Microsoft Entra ID	The same for Microsoft Entra ID