google-oauth

Google OAuth Integration

Configuration

OAuth is opt-in — it activates only when both env vars are set:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Check at runtime:

settings.is_google_oauth_configured  # bool property

OAuth Flow (3-step — never puts the JWT in a URL)

Step	Endpoint	Who calls it
1. Initiate	GET /api/v1/auth/google	Browser
2. Callback	GET /api/v1/auth/google/callback	Google redirect
3. Exchange	POST /api/v1/auth/oauth/exchange-code	Frontend JS

Step 1 — Initiate

• Validates redirect_url is a relative path only (starts with /, not //).
• Generates a secrets.token_urlsafe(32) CSRF state token.
• Stores {"redirect": safe_redirect} in Redis under oauth_state:{state} with 10-minute TTL.
• Rejects the request (503) if Redis is unavailable — never sends OAuth traffic without a verifiable state.

Step 2 — Callback

• Atomically reads and deletes oauth_state:{state} with a single Redis GETDEL call (requires Redis ≥ 6.2). If the key is absent or expired, redirects to /auth/login?error=invalid_state — never proceeds.
  • Do not split this into GET + DELETE — a race condition would let two concurrent callbacks both pass validation with the same state code.
• Re-validates the redirect path from Redis (relative-only check).
• Exchanges the Google code via httpx.AsyncClient(timeout=httpx.Timeout(10.0)). Both the token exchange and user-info fetch must specify a timeout — without one the worker hangs indefinitely if Google is slow.
• Creates or updates the User record (new user → create; returning user → update).
• Issues a _make_jwt(...) for the user.
• Stores the JWT in Redis under oauth_code:{exchange_code} with 30-second TTL.
• Redirects to {redirect_path}?code={exchange_code} — the JWT never appears in a URL.

Step 3 — Exchange

# Frontend calls this immediately after the OAuth redirect lands
POST /api/v1/auth/oauth/exchange-code
{"code": "<exchange_code_from_url>"}

# Response
{"access_token": "<jwt>", "token_type": "bearer"}

The exchange code is deleted from Redis on first use (one-time only). If the code is missing or expired the endpoint returns HTTP 400.