Authentication

1. User logs in:
   Client → Auth Server (credentials: email + password, or OAuth)
   Auth Server verifies → issues tokens:
     - Access Token (short-lived: 15 min - 1 hour)
     - Refresh Token (long-lived: 7 - 30 days)

2. User makes API requests:
   Client → API Server
   Header: Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
   API Server validates the access token:
     - JWT: verify signature locally (no DB call)
     - Session: look up token in session store (Redis)

3. Token expires:
   Client → Auth Server (with refresh token)
   Auth Server verifies refresh token → issues new access token
   No re-login needed

4. User logs out:
   Client → Auth Server (revoke refresh token)
   Refresh token deleted from store
   Access token still valid until expiry (JWT limitation)

User clicks "Login with Google" on your app:

1. REDIRECT TO AUTH SERVER
   Your app redirects user to:
   https://accounts.google.com/o/oauth2/auth
     ?client_id=YOUR_APP_ID
     &redirect_uri=https://yourapp.com/callback
     &response_type=code
     &scope=openid email profile
     &state=random_csrf_token

2. USER AUTHENTICATES
   User logs into Google (if not already)
   User sees: "YourApp wants to access your email and profile"
   User clicks "Allow"

3. AUTH SERVER REDIRECTS BACK
   Google redirects to:
   https://yourapp.com/callback?code=AUTH_CODE_XYZ&state=random_csrf_token

4. EXCHANGE CODE FOR TOKENS (server-to-server)
   Your backend → Google token endpoint:
   POST https://oauth2.googleapis.com/token
   Body: { code: AUTH_CODE_XYZ, client_id, client_secret, redirect_uri }

   Google responds:
   {
     "access_token": "ya29.a0AfH6SM...",     // Access APIs
     "refresh_token": "1//0eXy7z...",         // Get new access tokens
     "id_token": "eyJhbGciOiJSUzI1NiJ9...",  // User identity (OIDC)
     "expires_in": 3600
   }

5. YOUR APP HAS THE USER'S IDENTITY
   Decode id_token → { sub: "12345", email: "user@gmail.com", name: "Alice" }
   Create or find user in your database
   Issue your own session/JWT for subsequent requests

Key security: the authorization code is exchanged server-to-server.
The client_secret never reaches the browser.

Structure: Header.Payload.Signature

Header (base64):
  { "alg": "RS256", "typ": "JWT" }

Payload (base64):
  {
    "sub": "user_42",           // Subject (user ID)
    "email": "alice@example.com",
    "role": "admin",
    "iat": 1706140800,          // Issued at
    "exp": 1706144400           // Expires (1 hour later)
  }

Signature:
  RS256(base64(header) + "." + base64(payload), private_key)

Verification (any API server):
  1. Split token into header.payload.signature
  2. Verify signature using the auth server's PUBLIC key
  3. Check exp > now (not expired)
  4. Check iss = expected issuer
  5. Extract user info from payload → no DB call needed

Key insight: the token IS the session.
  All user info is embedded in the token.
  Any server with the public key can verify it.
  No shared session store needed.

Login:
  Client sends credentials → Server verifies
  Server creates session in Redis:
    SET "session:abc123xyz" '{"user_id":"42","role":"admin"}' EX 3600
  Server returns: Set-Cookie: session_id=abc123xyz; HttpOnly; Secure

Subsequent requests:
  Client sends: Cookie: session_id=abc123xyz
  Server: GET "session:abc123xyz" from Redis
    → { user_id: "42", role: "admin" }
    → User is authenticated

Logout:
  Server: DEL "session:abc123xyz" from Redis
  → Session immediately invalidated
  → Next request with this session_id → 401 Unauthorized

Key insight: the token is just an ID.
  All user info is stored server-side (Redis).
  The server must look up every request.
  But revocation is instant — delete the session.

Access token expires (after 15 minutes):

  Client → API: GET /api/users/me
  Header: Authorization: Bearer <expired_access_token>
  API: 401 Unauthorized (token expired)

  Client → Auth Server: POST /auth/refresh
  Body: { refresh_token: "rt_xyz789..." }

  Auth Server:
    1. Verify refresh token exists in DB and is not revoked
    2. Check refresh token not expired (30-day TTL)
    3. Issue new access token (15-min TTL)
    4. Optionally rotate refresh token (issue new one, revoke old)
    5. Return: { access_token: "new_jwt...", refresh_token: "new_rt..." }

  Client retries original request with new access token → 200 OK

JWT Revocation (the hard problem):
  JWTs are valid until they expire — you can't "delete" them.
  Solutions:
    1. Short expiry (15 min) — limits damage window
    2. Token blocklist — check a Redis set of revoked JWTs on each request
       (adds a DB call, partially defeats the "stateless" benefit)
    3. Refresh token revocation — revoke the refresh token so no new
       access tokens can be issued (existing one still valid until expiry)

System: SaaS app with web, mobile, and public API

SOCIAL LOGIN (OAuth 2.0 + OIDC):
  1. User clicks "Login with Google"
  2. Redirect to Google → user authenticates → authorization code
  3. Backend exchanges code for tokens (server-to-server)
  4. ID token → extract email, name → find or create user in DB
  5. Issue app tokens:
     - Access token: JWT, 15-min expiry, contains { user_id, role }
     - Refresh token: opaque, 30-day expiry, stored in PostgreSQL

EMAIL/PASSWORD LOGIN:
  1. User submits email + password
  2. Backend: bcrypt.compare(password, stored_hash)
  3. If match → issue same access + refresh tokens as above
  4. If fail → 401 with rate limiting (5 attempts per 15 min)

API REQUEST FLOW:
  Client → API Gateway
  Header: Authorization: Bearer <jwt>

  API Gateway:
    1. Decode JWT header → get key ID (kid)
    2. Fetch public key from JWKS endpoint (cached)
    3. Verify signature → valid
    4. Check exp > now → not expired
    5. Extract { user_id: "42", role: "admin" }
    6. Forward request to backend service with user context
    → No database call for auth verification ✅

TOKEN REFRESH:
  Access token expires → client sends refresh token
  Auth server: verify refresh token in DB → issue new JWT
  Optionally rotate refresh token (revoke old, issue new)

LOGOUT:
  Delete refresh token from DB
  Access token still valid for up to 15 min (acceptable trade-off)
  For immediate revocation: add JWT to Redis blocklist (checked on each request)

SECURITY LAYERS:
  - Passwords: bcrypt with cost factor 12
  - Refresh tokens: stored hashed in DB (not plaintext)
  - Access tokens: RS256 signed (asymmetric — services verify with public key)
  - CSRF: SameSite cookies + CSRF token for web
  - Rate limiting: 5 login attempts per 15 min per IP