メニュー
Choose and implement auth correctly — JWT vs session vs OAuth decision, pin allowed algorithms server-side, rotate refresh tokens with reuse detection, avoid the classic JWT pitfalls. Use when adding login, integrating OAuth, or when token handling looks risky. Not for access control / permissions (use authorization) or a broader OWASP audit (use backend-security-audit).
| name | authentication |
| description | Choose and implement auth correctly — JWT vs session vs OAuth decision, pin allowed algorithms server-side, rotate refresh tokens with reuse detection, avoid the classic JWT pitfalls. Use when adding login, integrating OAuth, or when token handling looks risky. Not for access control / permissions (use authorization) or a broader OWASP audit (use backend-security-audit). |
| license | MIT |
Establish who the caller is, securely. Pick the right mechanism for the use case and avoid the well-known token pitfalls (algorithm confusion, non-rotating refresh tokens, client-trusted claims).
Universal — the JWT-vs-session-vs-OAuth decision, algorithm pinning, and refresh-rotation-with-reuse-detection are auth principles independent of language; the library differs.
1b. Require MFA / step-up for sensitive operations
Pin allowed algorithms server-side — never trust the token alg header
none algorithm bypassShort access tokens + rotating refresh tokens
Store tokens safely (coordinate with frontend)
security-audit token-storage ruleValidate token claims as untrusted input
exp, iss, aud, signature — all of themdata-validation)5b. Defend the login endpoint itself
state (CSRF) + PKCE for public clients; verify the redirect URI is on the allowlist exactly (not a prefix)alg: none and an RS256→HS256 confusion token → verify both rejected| ❌ Anti-pattern | ✅ Correct |
|---|---|
Trusting the token's alg header | Pin allowed algorithms server-side |
| Long-lived access tokens, no rotation | Short access + rotating refresh w/ reuse detection |
| Tokens in localStorage | HttpOnly + Secure + SameSite cookies |
| JWT for a simple revocable web session | Server-side session (easy revocation) |
Skipping iss/aud/exp verification | Verify all standard claims |
| Reusing the pre-login session id post-login | Rotate session id on login (session fixation defense) |
| No login rate-limit / generic 401 only by IP | Rate-limit by IP and per account; lockout after N failures |
| User-enumeration leak ("no such user" vs "wrong password") | Generic "invalid credentials" for both |
| Tier | Examples | Action SLA |
|---|---|---|
| Critical | alg: none or RS256→HS256 accepted; refresh token never rotates; tokens in localStorage; no MFA on admin / money-moving actions | Block release; fix immediately |
| Major | Long access-token TTL with no revocation; missing aud/iss checks; no login rate-limit (credential stuffing open); session id not rotated on login (fixation) | Fix this sprint |
| Minor | Session timeout untuned; OAuth state param missing on a low-risk flow; user-enumeration leak in error messages | Schedule within 2 sprints |
algorithms list on the verifier — confirm every live issuer is already on the new algorithmfeat(auth): add <mechanism> login / fix(auth): pin allowed JWT algorithms@nestjs/passport + passport-jwt; configure algorithms: ['RS256'] explicitly (pin)fastapi-users; PyJWT with explicit algorithms=[...]golang-jwt with explicit alg pinning; avoid the historical alg-confusion footgunnone-alg and RS256→HS256 classes apply to every JWT libraryauthorization — authn (who you are) precedes authz (what you can do)backend-security-audit — token handling is a top OWASP audit areadata-validation — token claims are untrusted input — validate themalg); rotate refresh tokens with reuse detection that revokes the whole family on replay. Modern auth is more than tokens: passkeys for consumer products, MFA / step-up on sensitive actions, login-endpoint rate-limit by IP and per account (credential-stuffing rotates IPs), and session-id rotation on login (fixation).Build LLM features on the backend — deterministic agent loops (round-trip every tool call by id), RAG over a vector store, token/cost accounting, streaming, eval harness, and prompt-injection defense (treat all model context as untrusted). Use when adding an AI feature, building RAG, or wiring an agent loop. Not for the AI streaming UI on the frontend (use frontend-toolkit's AI integration) or general boundary input parsing (use data-validation).
Define a schema-first API contract — standardized error envelope (RFC 9457), pagination, status codes, consistent JSON shapes. Use when establishing API conventions, before multiple teams consume an API, or when error responses are inconsistent. Not for choosing the protocol or modeling resources (use api-design) or for runtime input parsing at the boundary (use data-validation).
Choose the API protocol (REST / GraphQL / gRPC) by traffic shape and design resources, versioning, and async patterns. Use when adding a new API surface, designing a service boundary, or when clients complain about over/under-fetching. Not for the schema/error envelope details (use api-contract) or per-resource access control (use authorization).
Default to a modular monolith with enforced internal boundaries; treat microservices as a destination after boundaries prove stable, not a starting point. Use when structuring a backend, when tempted to split into services, or when module boundaries blur. Not for the actual schema-split / service-extraction migrations (use migration-strategy + schema-design).
Build reliable event-driven flows with the Transactional Outbox pattern — write state and event in one transaction, relay asynchronously, achieve at-least-once delivery + consumer idempotency. Use when an action must reliably trigger downstream work, or when events are lost on crash (dual-write problem). Not for simple background work without state+event reliability (use background-jobs) or outbound HTTP webhook specifics (use webhook-design).
Design access control — RBAC for coarse function-level checks, Postgres Row Level Security (RLS) for row-level data isolation, ABAC pushed to the app/policy layer. Use when adding permissions, building multi-user data access, or when one user can see another's data. Not for establishing who the caller is (use authentication) or tenant isolation specifically (use multitenancy-audit).