docs: add Google Workspace SSO setup guide (#85)

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.

Co-authored-by: Venkat SF <venkatesh.sakamuri@stayflexi.com>

Author: geekypunk

.env.example

@@ -259,6 +259,28 @@ SLACK_BOT_TOKEN=
 SLACK_SIGNING_SECRET=
 SLACK_DEEPSQL_BOT_USERNAME=
 
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# OPTIONAL — Google Workspace SSO
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Full walkthrough: docs/GOOGLE_SSO_SETUP.md
+#
+# Two things that are easy to miss:
+#  - The domain allowlist is a DATABASE TABLE (google_workspace_domain), not a
+#    variable here. SSO rejects everyone until a row exists for your domain.
+#  - SSO does not create accounts. Users must exist in DeepSQL first, or they
+#    get "403 This account is not provisioned in DeepSQL".
+
+SECURITY_GOOGLE_ENABLED=false
+SECURITY_GOOGLE_CLIENT_ID=
+SECURITY_GOOGLE_CLIENT_SECRET=
+# Must match the Authorized redirect URI on the OAuth client EXACTLY.
+SECURITY_GOOGLE_REDIRECT_URI=https://deepsql.example.com/api/auth/google/callback
+
+# Set false to make SSO exclusive: hides the password form and refuses
+# /auth/login. Enabling SSO alone does NOT close the password path.
+# Everyone must be able to sign in with Google before you set this.
+SECURITY_PASSWORD_ENABLED=true
+
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # OPTIONAL — Admin Bootstrap (managed by install.sh)
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

README.md

@@ -443,6 +443,7 @@ caching · nginx.
 - [`docs/README.md`](docs/README.md) — documentation index
 - [`AGENTS.md`](AGENTS.md) — codebase map
 - [`mcp/README.md`](mcp/README.md) — CLI and MCP server
+- [`docs/GOOGLE_SSO_SETUP.md`](docs/GOOGLE_SSO_SETUP.md) — Google Workspace SSO, and disabling password sign-in
 - [`SECURITY.md`](SECURITY.md) — reporting a vulnerability
 
 ## License

docs/GOOGLE_SSO_SETUP.md

@@ -0,0 +1,210 @@
+# Google Workspace SSO
+
+Let your team sign in to DeepSQL with their work Google accounts, and
+optionally turn off password sign-in entirely.
+
+DeepSQL verifies Google's `hd` (hosted domain) claim against an allowlist you
+control, so only domains you name can get in — a personal Gmail account cannot
+sign in even if someone types a matching email address.
+
+**Two things surprise most people, so they are called out up front:**
+
+1. The allowlist is a **database table**. Configuring the environment variables
+   alone leaves SSO rejecting everyone. See [step 4](#4-allowlist-your-domain).
+2. SSO does **not** create accounts. A user who has never been added to DeepSQL
+   gets `403 This account is not provisioned in DeepSQL`, even with a valid
+   Workspace login. That is deliberate — see [Provisioning](#provisioning-users).
+
+---
+
+## 1. Create the OAuth client
+
+OAuth clients are created in **Google Cloud Console** (`console.cloud.google.com`),
+*not* in the Workspace Admin console (`admin.google.com`). There is no `gcloud`
+command for this — the IAP OAuth Admin API was the closest thing and was shut
+down in March 2026, and it never supported custom redirect URIs anyway.
+
+In the Cloud Console, the relevant area is **Google Auth Platform**. It was
+previously a single "OAuth consent screen" page and is now split:
+
+| You want | Where it lives now |
+| --- | --- |
+| Internal / External | **Audience** |
+| Create an OAuth client | **Clients** |
+| App name, logo, support email | **Branding** |
+| Scopes | **Data Access** |
+
+Steps:
+
+1. Pick or create a project. It must belong to your Google Workspace
+   **organization**, or the Internal option in step 2 is not offered.
+2. **Branding** — app name, user support email, developer contact.
+3. **Audience** — choose **Internal**.
+4. **Clients → Create client**
+   - Application type: **Web application**
+   - Authorized redirect URI, exactly:
+     `https://deepsql.example.com/api/auth/google/callback`
+   - Leave *Authorized JavaScript origins* empty — this is a server-side flow.
+5. Copy the **Client ID** and **Client secret**.
+
+### Choose Internal if you can
+
+**Internal** means Google itself refuses to issue a token to anyone outside your
+organization — the request never reaches DeepSQL. That sits on top of DeepSQL's
+own domain allowlist, so a mistake in one does not open the door. It also avoids
+the "unverified app" warning that External shows.
+
+> **Do not flip an existing project from External to Internal without checking
+> what already uses it.** The Audience setting is project-wide. If another
+> application in that project serves users outside your organization, switching
+> to Internal cuts them off immediately. Check **Overview → Metrics** for live
+> OAuth traffic first; if in doubt, create a separate project.
+
+### One project can serve many apps
+
+`Audience` and `Branding` are per-project; **Clients** are not. Add one client
+per application and they share the Internal gate with no extra setup.
+
+Because Branding is shared, name it for the organization rather than one app —
+`Acme Internal` rather than `DeepSQL` — since every app in the project shows that
+same name on its consent screen.
+
+---
+
+## 2. Configure DeepSQL
+
+```bash
+SECURITY_GOOGLE_ENABLED=true
+SECURITY_GOOGLE_CLIENT_ID=<client id>
+SECURITY_GOOGLE_CLIENT_SECRET=<client secret>
+SECURITY_GOOGLE_REDIRECT_URI=https://deepsql.example.com/api/auth/google/callback
+```
+
+`SECURITY_GOOGLE_REDIRECT_URI` must match the value registered in the Cloud
+Console **character for character**, trailing slash included, or Google rejects
+the callback.
+
+---
+
+## 3. Set your public URL
+
+```bash
+APP_PUBLIC_URL=https://deepsql.example.com
+```
+
+**This one catches people.** There are two similarly named settings and they do
+different jobs:
+
+| Variable | Property | Used for |
+| --- | --- | --- |
+| `APP_PUBLIC_URL` | `app.public-url` | **every auth redirect**, including the Google callback, and invite emails |
+| `APP_BASE_URL` | `app.base-url` | the `deepsql login` CLI device-flow authorize URL |
+
+Both default to `http://localhost:3000`. Leave `APP_PUBLIC_URL` unset and Google
+sign-in appears to work, then dumps the user on `localhost:3000/dashboard` — the
+session cookie was written correctly, but the browser is sent nowhere useful.
+Set both on any real deployment.
+
+---
+
+## 4. Allowlist your domain
+
+**SSO rejects every sign-in until you do this.** There is no environment
+variable for it; the allowlist lives in the `google_workspace_domain` table so
+it can be changed without a restart.
+
+```sql
+INSERT INTO google_workspace_domain (domain, enabled, created_at, updated_at)
+VALUES ('example.com', true, NOW(), NOW());
+```
+
+A sign-in is accepted only when the domain is present **and** enabled **and**
+Google's `hd` claim for that account matches it. Checking `hd` rather than the
+email suffix is what stops a personal account from impersonating a Workspace
+one.
+
+To revoke a domain later, set `enabled = false` — it takes effect immediately.
+
+---
+
+## 5. Restart and verify
+
+Configuration is read at startup, and `docker restart` does **not** re-read
+`.env`:
+
+```bash
+docker compose up -d --force-recreate backend
+```
+
+Check the flag is live:
+
+```bash
+curl -s https://deepsql.example.com/api/setup/status
+# {"setupComplete":true, ... ,"googleEnabled":true,"passwordLoginEnabled":true}
+```
+
+`googleEnabled: true` makes the **Sign in with Google** button appear on the
+login page.
+
+---
+
+## Provisioning users
+
+Google proves *who someone is*. It does not decide *whether they may use
+DeepSQL*. A user who has never been added gets:
+
+```
+403 This account is not provisioned in DeepSQL
+```
+
+This is intentional. Without it, anyone in your Workspace — contractors,
+interns, every department — could grant themselves access to a tool holding
+production database credentials.
+
+Add users through the admin UI (or `POST /admin/users`) **before** they sign in.
+On first successful SSO login DeepSQL links their Google identity to the
+existing account automatically; there is no separate linking step.
+
+---
+
+## Optional: disable password sign-in
+
+Enabling SSO does **not** close the password path. `/auth/login` keeps working
+for every local account, so seed or demo credentials remain usable on an
+internet-facing install. To make SSO exclusive:
+
+```bash
+SECURITY_PASSWORD_ENABLED=false
+```
+
+The login page then hides the password form and offers only Google. The backend
+refuses password logins before any credential comparison and records a
+`PASSWORD_LOGIN_FAILURE` audit event with `reason=password_login_disabled`.
+
+Defaults to `true`, so existing installs are unaffected.
+
+> **Every user must be able to sign in with Google before you set this.** Anyone
+> who has only ever used a password is locked out until they use the Google
+> button once. Setting this while `SECURITY_GOOGLE_ENABLED=false` leaves nobody
+> able to sign in at all; DeepSQL logs an ERROR at startup if you do.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| No **Sign in with Google** button | `SECURITY_GOOGLE_ENABLED` is not `true`, or the backend was not recreated. Check `/api/setup/status`. |
+| `redirect_uri_mismatch` from Google | `SECURITY_GOOGLE_REDIRECT_URI` differs from the Cloud Console entry. Compare exactly — a trailing slash counts. |
+| `403 This Google Workspace domain is not allowed` | No enabled row in `google_workspace_domain`, or the account's `hd` claim does not match. Personal Gmail accounts have no `hd` and are always rejected. |
+| `403 This account is not provisioned in DeepSQL` | Authentication worked; the user does not exist in DeepSQL. Create them first. |
+| Lands on `localhost:3000` after sign-in | `APP_PUBLIC_URL` is unset. See [step 3](#3-set-your-public-url). |
+| Everyone locked out after `SECURITY_PASSWORD_ENABLED=false` | Set it back to `true`, recreate the backend, and confirm SSO works before disabling again. |
+
+To see what actually happened, the `security_event` table records every attempt
+with its outcome and reason:
+
+```sql
+SELECT created_at, event_type, outcome, email, event_metadata
+FROM security_event ORDER BY id DESC LIMIT 20;
+```

docs/README.md

@@ -39,6 +39,7 @@ for a project overview and the fastest path to a running instance.
 - **[PERFORMANCE_UI_IMPLEMENTATION.md](./PERFORMANCE_UI_IMPLEMENTATION.md)** — Performance dashboard implementation
 - **[PERFORMANCE_UI_BUGFIXES.md](./PERFORMANCE_UI_BUGFIXES.md)** — Performance UI fixes and improvements
 - **[RBAC_USAGE_GUIDE.md](./RBAC_USAGE_GUIDE.md)** — Roles, permissions, and access control
+- **[GOOGLE_SSO_SETUP.md](./GOOGLE_SSO_SETUP.md)** — Google Workspace SSO and password-login control
 
 ## Operations