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. Copy the Client ID and Client secret from the confirmation dialog.

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. Paste the Client ID and Client secret.

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.

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).
Error 401: invalid_client (“The OAuth client was not found”) at sign-in	The client ID is wrong — Google’s issuer is fixed and shared by every Workspace tenant, so the wizard’s issuer check cannot catch a bad client ID. Copy the client ID from the OAuth 2.0 Client ID entry in Google Cloud console and re-save the IdP step.
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.