agnes-the-ai-analyst/docs/auth-google-oauth.md

# Google OAuth — operator gotchas

The Google OAuth provider (`app/auth/providers/google.py`) reads `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` straight from environment variables. If either is empty, `is_available()` returns `False` and the login page falls back to email / password auth without complaint.

## Env vars

| Var | Required for Google | Notes |
|---|---|---|
| `GOOGLE_CLIENT_ID` | yes | From Google Cloud Console OAuth 2.0 Client ID (Web application). |
| `GOOGLE_CLIENT_SECRET` | yes | From the same client. Rotate via "Reset secret" on the client; old value is invalidated immediately. |
| `SESSION_SECRET` | yes | Used by Starlette `SessionMiddleware` to stash OAuth `state`/`nonce` between `/auth/google/login` and `/auth/google/callback`. Auto-generated to `data/state/.session_secret` if unset, but for multi-replica or VM-rebuild scenarios pin it explicitly. |
| `JWT_SECRET_KEY` | yes | Signs the access-token cookie. Same auto-generate-and-persist pattern as `SESSION_SECRET`. |
| `FORWARDED_ALLOW_IPS` | only when behind a reverse proxy | Default `127.0.0.1` — uvicorn ignores `X-Forwarded-Proto/Host` from any other client IP, which means callbacks come back as `http://localhost:8000/...` instead of `https://your-host/...`. Set to `*` (or the proxy's IP) when terminating TLS at Caddy / nginx / Cloudflare Tunnel. The compose `command:` already passes `--proxy-headers --forwarded-allow-ips='*'` — this env var is the override. |
| `DOMAIN` | recommended behind TLS | Public hostname (`data.example.com`). Gates the `Secure` flag on the access-token cookie in `google_callback()` — when set, the cookie is only sent over HTTPS, when empty the cookie works over plain HTTP so local dev is unbroken. Also consumed by the Caddy profile. |
| `SERVER_URL` | optional | Absolute base URL (`https://data.example.com`) used to build OAuth callback URLs and other external links. Set it when you don't trust the incoming `Host` header (e.g. a misconfigured proxy), so the callback URL is deterministic regardless of what the reverse proxy forwards. Must match the redirect URI registered on the Google OAuth client. |
| `SEED_ADMIN_EMAIL` | recommended on first boot | App startup (`app/main.py`) creates this user with `role="admin"` if missing. Combined with Google OAuth, the first time the matching email signs in, `repo.get_by_email()` finds the seeded record and the user lands as admin. |

## `instance.yaml` requirements that affect auth

`config/loader.py:_validate_config` requires:

- `instance.name`
- `auth.allowed_domain` (CSV — e.g. `"example.com, partner.org"`; empty allows any verified Google account)
- `auth.webapp_secret_key` (typically `"${SESSION_SECRET}"`)
- `server.host`
- `server.hostname`

If any are missing, `app/instance_config.py` catches the `ValueError`, logs `Could not load instance.yaml: ... Using defaults`, and the app keeps running with **empty** instance config. That means `get_allowed_domains()` returns `[]` and **every verified Google account is allowed**. Always grep your runtime log for `Could not load instance.yaml` after a config change — silent fallback is by design (resilience over strictness) but easy to miss.

## OAuth client setup (Google Cloud Console)

1. APIs & Services → Credentials → "Create Credentials" → "OAuth client ID" → "Web application".
2. Authorized redirect URIs — one per public hostname:
   ```
   https://<hostname>/auth/google/callback
   ```
   Add `http://localhost:8000/auth/google/callback` for local dev.
3. The Client ID and Client Secret go into `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`.

## Common failure modes

| Symptom | Cause | Fix |
|---|---|---|
| `Error 400: redirect_uri_mismatch` | Either the URI isn't registered on the OAuth client, or the app generated `http://localhost:8000/...` because `FORWARDED_ALLOW_IPS` wasn't set (or `SERVER_URL` isn't defined and the proxy's `Host` header is missing / wrong). | Add the URI in Console; verify `FORWARDED_ALLOW_IPS=*` reaches the container; pin `SERVER_URL=https://<host>` to bypass `Host`-header reliance. |
| Login works but the user keeps getting re-prompted on the next request | Access-token cookie lost between requests. Common cause: `DOMAIN` unset → `Secure=False` but the browser hit the app over `https://` via a proxy and dropped the cookie for another reason; or `DOMAIN` set but the browser hit `http://`. | Set `DOMAIN=<hostname>` to match the terminator's hostname, and always serve over HTTPS to the browser. |
| `/login?error=google_not_configured` | `GOOGLE_CLIENT_ID` or `GOOGLE_CLIENT_SECRET` empty in container env. | Inspect `docker compose exec app env \| grep GOOGLE`. |
| `/login?error=domain_not_allowed` | User's email domain isn't in `auth.allowed_domain`. | Add the domain (CSV) and reload — note that allowed_domain only takes effect when `instance.yaml` validates (see above). |
| Login succeeds but `/admin/*` returns "Requires role admin or higher" | New user got `role="analyst"` (default for Google-provisioned users). The JWT in the cookie is also stale. | Set `SEED_ADMIN_EMAIL` BEFORE first login, or promote in DB and have the user log out + log back in. |

## DB role promotion (when `SEED_ADMIN_EMAIL` was missed)

The system DB (`/data/state/system.duckdb`) is held exclusively by uvicorn (PID 1 in container), so `docker compose exec app python ...` can't open a second connection. Stop the app, run a throwaway container against the host volume, restart:

Adjust the install dir, the host data path the `data` volume maps to, and the image tag for your deployment:

```bash
cd <install-dir>                                   # wherever docker-compose.yml lives
COMPOSE='docker compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.host-mount.yml'
$COMPOSE stop app scheduler
docker run --rm -v <data-dir>:/data --entrypoint python ghcr.io/keboola/agnes-the-ai-analyst:${AGNES_TAG:-stable} -c "
import duckdb
c = duckdb.connect('/data/state/system.duckdb')
c.execute(\"UPDATE users SET role = 'admin' WHERE email = 'me@example.com'\")
c.close()
"
$COMPOSE up -d app scheduler
```

The promoted user must sign out and sign back in — JWTs carry the role at issue time and don't refresh until a new token is issued.