How Google Workspace single sign-on works and how to set up the OAuth client in Google Cloud.

How it works

Your site delegates sign-in to Google using OpenID Connect. When a visitor opens a gated app, they are redirected to Google, sign in with their Workspace account (subject to your organization's own multi-factor and access policies), and are redirected back to your site. Only members of your Google Workspace can get in; consumer @gmail.com accounts and other organizations are rejected.

You restrict access by listing your Google Workspace domain(s). Only accounts in those domains can sign in, so add every domain your organization uses.

Before you start

You configure Google sign-in with two values from a Google Cloud OAuth client: a Client ID and a Client secret. Create them once per site.

You also need your site's callback URL, because Google must know where to send visitors back. The callback path is always exactly /__auth/callback. The dashboard shows the full Redirect URI with a copy button, on the Sign-in details step of the New site wizard and under Edit sign-in. Copy it from there rather than assembling it by hand from your host, so it matches character for character.

Set up the OAuth client in Google Cloud

1. Open the Google Cloud console and select (or create) a project owned by your Workspace organization.
2. Under APIs & Services, open OAuth consent screen. Choose the Internal user type so only your Workspace can use the client, then fill in the app name and support email.
3. Under APIs & Services → Credentials, select Create credentials → OAuth client ID.
4. Choose Web application as the application type and give it a name.
5. Under Authorized redirect URIs, add the Redirect URI you copied from the dashboard (https://<your-site-host>/__auth/callback). The callback path is always exactly /__auth/callback, and it must match exactly, including https and no trailing slash.
6. Select Create. Google shows the client ID and client secret. Copy both; the secret is shown only once.

Enter the details in BehindGate

1. In the dashboard, choose Google Workspace as the sign-in method (in the New site wizard, or later under Edit sign-in).
2. Enter your Google Workspace domain(s). Only accounts in these Google Workspace domains can sign in. Add every domain your organization uses.
3. Enter the Client ID and Client secret from the step above.
4. Save. The secret is stored encrypted and is never shown again; to change it, re-enter a new value.

Open your live site to test the round trip to Google and back.

Rotating the secret

If the client secret is ever exposed, create a new secret in Google Cloud, enter it under Edit sign-in, and remove the old one in Google. Because BehindGate never displays the stored secret, leave the Client secret field blank to keep the current secret, or enter a new one to replace it.