docs: add Google Workspace SSO setup guide

[geekypunk]

Documents the Google Workspace SSO feature, which shipped without setup docs.

Written while configuring it end-to-end on a real deployment, so it covers the parts that only surface when you actually try it.

Why this is needed

The four SECURITY_GOOGLE_* variables appear nowhere — not in .env.example, not in the README. Worse, two required steps cannot be discovered from configuration at all:

• The domain allowlist is a database table (google_workspace_domain), not an environment variable. Until a row exists, SSO rejects every sign-in while looking fully configured. Nothing points you at the table.
• SSO does not provision accounts. A valid Workspace user who was never added to DeepSQL gets 403 This account is not provisioned in DeepSQL. That is the right behaviour — otherwise anyone in the org could grant themselves access to a tool holding production database credentials — but undocumented it reads as a bug.

Two traps documented

APP_PUBLIC_URL vs APP_BASE_URL. Both default to http://localhost:3000 and they are not interchangeable: app.public-url drives every auth redirect and invite emails, app.base-url only the CLI device flow. Set the wrong one and sign-in succeeds, writes the session cookie correctly, then lands the user on localhost:3000/dashboard — a failure that looks like broken auth but is purely a redirect target.

Audience is project-wide. Flipping an existing Cloud project from External to Internal cuts off every non-org user of any other app in that project. The guide says to check Overview → Metrics for live OAuth traffic first, and to prefer a separate project when in doubt.

Contents

docs/GOOGLE_SSO_SETUP.md covers: creating the client in Google Cloud Console (including the current Google Auth Platform layout, where the old single consent-screen page is now split across Audience / Branding / Clients / Data Access), why Internal is worth taking, sharing one project across multiple apps, the four variables, APP_PUBLIC_URL, the allowlist INSERT, restart and verification, provisioning, SECURITY_PASSWORD_ENABLED, and a troubleshooting table keyed by the exact error strings the app returns.

Also adds the variables to .env.example with the two non-obvious caveats inline, and index entries in README.md and docs/README.md.

Note

There is no gcloud path for creating the OAuth client — gcloud iap oauth-clients was the nearest equivalent and was shut down in March 2026, and it never supported custom redirect URIs. The guide states this so nobody spends time looking for one.

Docs only — no code changes.