IdP setup: Google Workspace

Admin guide · Install wizard

This walkthrough pairs with the IdP step of the Greenlight install wizard. You’ll create an OAuth client in the Google Cloud console, copy its credentials back into the wizard, and validate the connection. Plan for about five minutes; everything happens in the browser — no CLI.

Note

Have the wizard open in another tab. It shows the exact Redirect URI for your install—it lives under your verified control-plane URL (for example https://greenlight.acme.com/auth/callback). Never register the temporary bootstrap URL.

What you’ll need

• Access to a Google Cloud project in your Workspace organization (any project works; a dedicated greenlight project keeps things tidy).
• The Redirect URI shown in the wizard’s IdP step.
• Optionally, the list of domains your Workspace uses (for example acme.com, acme.co.uk) — the wizard can restrict sign-in to them.

Create the OAuth client

1. Open console.cloud.google.com, pick your project, and go to APIs & Services → OAuth consent screen.

2. Choose user type Internal so only accounts in your Workspace can sign in. Fill in the app name (Greenlight) and a support email, then save.

3. Go to APIs & Services → Credentials → Create credentials → OAuth client ID.

4. Choose application type Web application and name it Greenlight.

5. Under Authorized redirect URIs, paste the Redirect URI from the wizard. Select Create.

6. In the confirmation dialog, select Download JSON. The file (client_secret_….json) carries the client ID and client secret. You can also copy the Client ID and Client secret from the dialog instead.

How roles work for Google

Google ID tokens carry no group claim, so Greenlight does not map Google groups to roles. For Google Workspace orgs, roles are managed in the Greenlight dashboard: everyone who signs in starts as a Builder, and an Org Owner promotes people to Admin or Org Owner on the Users page. A role set there persists — it is not overwritten at the next sign-in.

Note

No directory service account or Admin console setup is needed. The Workspace domain restriction (below) is Greenlight’s only sign-in gate for Google; everything else about who-can-do-what is set in the dashboard.

Back in the wizard

1. The Issuer URL for Google is fixed — the wizard pre-fills https://accounts.google.com.

2. Under Import JSON from Google Cloud, choose or drop the file you downloaded. It fills Client ID and Client secret, and both stay editable. The file is read in your browser, and nothing is sent until you save. You can also paste the two values by hand.

   • A Desktop app client is refused. Create a Web application client instead.
   • If the file’s redirect URIs don’t include this install’s Redirect URI, the wizard warns you and shows the exact URI. Add it under Authorized redirect URIs in Google Cloud. Otherwise sign-in fails with redirect_uri_mismatch.

3. Optionally enter your Workspace domains (for example acme.com, acme.co.uk). Sign-in is then restricted to verified accounts in those domains via the hd claim.

   Caution

   Google reports each person’s own domain in hd, not your Workspace’s primary one — so if your Workspace holds more than one domain, list every one your people sign in with, or leave the field blank.

   Leaving it blank is safe when you chose user type Internal above: Google already limits that OAuth client to your Workspace organization, across every domain it holds. If you chose External, a blank field lets any Google account sign in — set the domains.

4. Select Validate configuration. Greenlight fetches Google’s /.well-known/openid-configuration and confirms the issuer, authorization endpoint, token endpoint, and JWKS all resolve, checks that your client ID has Google’s shape, and asks Google whether your redirect URI is registered against that client. Each check shows a green tick when it passed, a red cross when it failed, or a grey dash when Greenlight could not check it, with the reason on the line beneath; only a red cross blocks Save & continue. Client credentials always shows a grey dash on Google, which offers no way to test a secret without a sign-in — that is expected, and the redirect-URI check still covers the client.

5. Save & continue. The client secret goes straight to your cloud’s managed secret store; it is not stored in the database or shown again. After the first people sign in, assign their roles under Users in the dashboard.

Troubleshooting

Symptom	Fix
Error 400: redirect_uri_mismatch at sign-in	The redirect URI in the OAuth client doesn’t exactly match the wizard’s value (scheme, host, and path must all match). Validate pre-flights this, so a mismatch normally fails the Redirect URI registered check before you save.
Validate fails on the client ID format	A Google client ID always ends .apps.googleusercontent.com. Copy it from the OAuth 2.0 Client ID entry in the Google Cloud console.
Redirect URI registered fails with “The issuer does not recognize this Client ID”	The client ID names no client in your project, even though its shape is right. Copy it again from the OAuth 2.0 Client ID entry.
Sign-in rejected for a valid employee	Their account’s domain is not in the configured Workspace domains list — common when your Workspace holds several domains and only one was entered — or their Google email is unverified. Add the missing domain, or clear the field to rely on the OAuth client’s Internal user type.
A Google user needs Admin or Org Owner rights	Roles are managed in the dashboard for Google. An Org Owner sets the role on the Users page; it takes effect immediately and persists across sign-ins.