Skip to content

SSO Runbook — Google Workspace

End-to-end setup for sign-in with Google. ~10 minutes from a clean Google Cloud project to a working "Sign in with Google" button on the MFCloud console.

What you'll end up with

  • A Google Cloud project that owns the OAuth client.
  • An OAuth 2.0 client ID + secret you'll paste into MFCloud's Settings → SSO.
  • An OAuth consent screen approved internally for your workspace domain.
  • (Optional) Group mapping via Google Workspace security groups.

Prerequisites

  • Workspace Super Admin OR Owner of a Google Cloud project tied to your Workspace organization.
  • MFCloud master reachable at a stable HTTPS URL. Google refuses HTTP redirect URIs except for http://localhost.

Caveat — Google has no end_session_endpoint

Google's OIDC discovery doc does not advertise an end-session endpoint, so RP-initiated logout only clears the MFCloud session — the user stays signed into their Google account in the same browser. Click Manage your Google account → Sign out if you need to break the upstream session too. Documented separately on the SSO Callback troubleshooting page.

Step 1 — Create or pick a Google Cloud project

  1. console.cloud.google.com → Project picker → New Project.
  2. Name = mfcloud-sso (or whatever you like).
  3. Organization = your workspace org.
  4. Create.
  1. APIs & Services → OAuth consent screen.
  2. User Type = Internal (only users in your workspace can sign in — what you almost certainly want for an admin console). External requires Google verification for production use.
  3. Create.
  4. App information:
  5. App name = MFCloud Console
  6. User support email = your admin email
  7. App domain (optional) = your workspace domain
  8. Authorized domains — add your master's domain (e.g. example.com for mfcloud.example.com).
  9. Developer contact email = your email.
  10. Save and Continue → Scopes.
  11. Scopes — click Add or Remove Scopes, tick:
  12. openid
  13. .../auth/userinfo.email
  14. .../auth/userinfo.profile
  15. Save and Continue through the rest, Back to Dashboard.

Step 3 — Create the OAuth client

  1. APIs & Services → Credentials → + Create Credentials → OAuth client ID.
  2. Application type = Web application.
  3. Name = mfcloud-web (visible only to admins).
  4. Authorized JavaScript origins = https://<your-mfcloud-host>.
  5. Authorized redirect URIs = https://<your-mfcloud-host>/api/auth/oidc/callback.
  6. Create.

Google rejects bare IP addresses here

The redirect URI's host must look like a real public domain (a valid TLD, checked against the public suffix list) — https://192.168.1.24/... gets rejected with "Invalid Redirect: must use a domain that is a valid top private domain" even though Google never actually verifies the domain resolves or is owned by you. For lab/test setups without a real hostname yet, register any domain-shaped placeholder (e.g. https://mfcloud-lab-test.com/api/auth/oidc/callback) and point it at your master with a local hosts file entry — nothing needs to be publicly resolvable for Google's client-creation check to pass.

A modal pops up with two values you'll need:

Field Where it goes in MFCloud
Your Client ID Settings → SSO → Client ID
Your Client secret Settings → SSO → Client Secret

Both are also recoverable later from the Credentials page if you lose the modal — unlike Entra, Google lets you view the secret again.

Step 4 — Paste into MFCloud

In the MFCloud console:

  1. Settings → 🔑 Single Sign-On (OpenID Connect).
  2. Fill in:
  3. Issuer URL — https://accounts.google.com
  4. Client ID — from Step 3.
  5. Client Secret — from Step 3.
  6. Sign-in Button Label — Sign in with Google.
  7. Default Role — Tenant Viewer (safe default).
  8. Email Claim — email (Google always populates this).
  9. Groups Claim — groups (will be empty unless you complete Step 5).
  10. Enable OIDC sign-in ✓.
  11. Save SSO Settings.

Step 5 — Group claim (optional, requires extra setup)

By default Google's ID token does NOT include group memberships. Two options:

Option A — Workspace Cloud Identity Premium groups

  1. Workspace Admin → Apps → LDAP / Cloud Identity → enable group provisioning to your OIDC apps.
  2. In Google Cloud → IAM → Workforce Identity Federation → add the group claim mapping.

Production-grade but requires Cloud Identity Premium (paid SKU).

Skip the group claim entirely. Instead:

  1. Create a Google Workspace group [email protected].
  2. Add members in Google Admin.
  3. In MFCloud Settings → SSO, leave the group mapping table empty.
  4. Manually promote those users in MFCloud's IAM tab after their first sign-in.

The trade-off: changes in Google Workspace don't automatically reflect in MFCloud — you'd add+remove people manually. For ≤ 20 admins this is usually fine.

Step 6 — Test it

  1. Sign out of MFCloud.
  2. Login page should show Sign in with Google.
  3. Click → google.com picker → pick a workspace-domain account → consent screen (first time only) → back to MFCloud dashboard.
  4. Open user-avatar menu — should show your email.

Troubleshooting

Symptom Cause Fix
Error 400: redirect_uri_mismatch Step 3 Authorized redirect URI doesn't match what MFCloud generates Check master is behind a reverse proxy passing X-Forwarded-Proto: https. Uvicorn needs --proxy-headers.
Error 403: org_internal User isn't in your Workspace org (Step 2 set User Type to Internal) Either add the user to the org, or change User Type to External + complete Google verification.
Sign-in works but no group claim Step 5 not done Use Option B or set up Cloud Identity Premium.
Logout doesn't end Google session Google has no end_session_endpoint Expected — see "Caveat" at the top of this page.

See also