Be JWT Auth Patterns

Skill: JWT / Token Authentication

Universal token-based authentication patterns for any backend + frontend project. Use when implementing authentication, configuring the auth middleware/filter chain, or deciding where and how to store tokens on the client.

Authentication flow

[Client] → POST /api/auth/login {credentials}
               ↓
[Auth service]
  1. Verify credentials (password hash — see sec-secrets-management)
  2. Generate JWT with a unique JTI (UUID) claim
  3. Return {token, expiresIn}
               ↓
[Client] → sends token on each request: Authorization: Bearer <token>
               ↓
[Auth middleware/filter] (on each protected request)
  1. Extract token from header
  2. Validate signature and expiration
  3. Check that the JTI is not in the blocked-tokens store
  4. Populate the request's security context

Signing and secrets

• Never hardcode the signing secret — read it from an environment variable or secrets manager (see sec-secrets-management).
• HMAC-SHA256 (HS256) with a 256-bit random secret is sufficient for a single-service backend. Generate with openssl rand -hex 32.
• Use asymmetric signing (RS256/ES256) when multiple services must verify tokens without sharing the signing key.
• Always set an expiration (default: ≤ 24h; shorter + refresh tokens for sensitive systems).

Logout / revocation — blocklist

Stateless JWTs cannot be invalidated by themselves. To support real logout:

• Store the JTI of revoked tokens in a blocked_tokens store (jti, expires_at).
• The auth middleware rejects any token whose JTI is present.
• Purge rows where expires_at < now() periodically — the table stays small because entries only need to live until the token would expire anyway.

Client-side token storage

Rule: never localStorage. Use sessionStorage for SPAs, HttpOnly + Secure + SameSite cookies for SSR.

Common mistakes

Resources

• examples-java-spring.md — Spring Security configuration snippet and blocklist SQL schema.