Auth: Google SSO (OAuth2 / OIDC)

Start by reviewing #16 for the users table foundation and #2 for the parent authentication design. Use the stated environment variables and OAuth2/OIDC flow as the implementation map, including the callback, state-cookie verification, Google token validation, user upsert, and session creation. Done means users can sign in with Google securely and return to / with a session.

Sub-issue of #2. Depends on #16 (users table must exist first).

Add "Sign in with Google" via OAuth2 / OpenID Connect.

Setup (one-time, outside the codebase)

1. Go to Google Cloud Console → APIs & Services → Credentials.
2. Create an OAuth 2.0 Client ID (Web application type).
3. Add your redirect URI: https://<your-domain>/auth/google/callback.
4. Copy the Client ID and Client Secret into your env file.

Environment variables

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URL=https://<your-domain>/auth/google/callback

Flow

Browser                          Server                        Google
  │                                │                              │
  │── GET /auth/google ───────────►│                              │
  │                                │── redirect to accounts.google.com/o/oauth2/auth
  │◄── 302 ────────────────────────│   with client_id, redirect_uri, scope=openid email profile
  │                                │                              │
  │── user logs in to Google ─────────────────────────────────►  │
  │◄── redirect to /auth/google/callback?code=... ───────────────│
  │                                │                              │
  │── GET /auth/google/callback ──►│                              │
  │                                │── POST /token (exchange code)►│
  │                                │◄── id_token + access_token ──│
  │                                │── verify id_token signature  │
  │                                │── upsert user by email       │
  │                                │── create session             │
  │◄── 302 /  (session cookie) ────│                              │

Implementation

• Use golang.org/x/oauth2 + golang.org/x/oauth2/google — no heavy frameworks.
• Verify the id_token JWT signature against Google's public keys (JWKS endpoint).
• On callback: look up users by email. If found, attach Google identity. If not, create a new user with password_hash = NULL.
• State parameter (random nonce stored in a short-lived cookie) must be verified to prevent CSRF.

Related

• #2 Authentication (parent)
• #16 Username/password (users table foundation)