Authentication Design

Purpose

An authentication design document specifies how the system verifies the identity of every actor that interacts with it: users, services, and automated agents. It covers the identity providers in use, how credentials are stored and validated, the flows for multi-factor authentication, how tokens are issued and revoked, session lifecycle management, and the security properties the system commits to.

Authentication is the foundation of all access control. Every other security mechanism—authorization, audit logging, rate limiting, incident response—depends on knowing who is performing an action. Authentication failures cascade: a compromised account enables every action that account can perform. The cost of getting authentication right is small compared to the cost of a credential compromise affecting thousands of users.

Authentication design is not trivial, and inventing it from scratch is rarely the right answer. The authentication design document should specify which established patterns and protocols are used (OAuth 2.0, OpenID Connect, SAML, WebAuthn), how they are applied to this system’s specific constraints, and why certain alternatives were rejected.

The document must cover both happy paths (successful login) and adversarial paths (credential stuffing, phishing, session hijacking). An authentication design that only documents the happy path is incomplete and misleading—the security properties of a system are defined by its behavior when under attack, not when everything goes right.

Who needs this document

What separates a good version from a bad one

Criterion 1: Token lifecycle is fully specified

✓ Strong: “JWTs expire after 15 minutes. Refresh tokens expire after 30 days and are rotated on each use (sliding expiry). Revocation via Redis blocklist checked on every token validation (not only at refresh). Token claims: sub (user UUID), role (user role), iat (issued at), exp (expiry). All tokens signed RS256 with 2048-bit keys. Keys rotate automatically every 30 days via AWS KMS key rotation. Old keys retained for 7 days to allow in-flight tokens to validate.”

✗ Weak: “Use JWT tokens with expiry. Refresh tokens should also expire.” (No expiry values, no rotation policy, no revocation mechanism, no signing algorithm. Each omission is an independent security decision left to the implementing developer—inconsistently across the team.)

Criterion 2: Credential storage is specified with algorithm and parameters

✓ Strong: “Password storage: bcrypt with cost factor 12. Minimum password requirements: 8 characters, at least one non-letter character. Passwords are checked against the HaveIBeenPwned API at registration and password change. Plaintext passwords must never appear in logs, error messages, or database queries — use parameterized queries exclusively. Password reset tokens: cryptographically random 32-byte value (base64url encoded), single-use, expire after 1 hour.”

✗ Weak: “Passwords are stored securely using hashing.” (Which algorithm? Which parameters? No security properties are verifiable from this description. “Hashed” passwords stored with MD5 satisfy this spec.)

Criterion 3: MFA flows cover enrollment, verification, and recovery

✓ Strong: “MFA support: TOTP (RFC 6238) as primary, SMS as fallback (for users without authenticator apps). Enrollment: user scans QR code, confirms with two consecutive codes. TOTP window: ±1 time step (30-second tolerance for clock skew). Recovery codes: 8 × 12-character codes generated at enrollment, stored as bcrypt hashes, each single-use. If all recovery codes are consumed, user must contact support with identity verification.”

✗ Weak: “Two-factor authentication is supported.” (Supported how? What factors? What happens when the second factor is unavailable? Recovery is the most common MFA failure mode and the one most often designed out.)

Criterion 4: Attack mitigations are specified per attack type

✓ Strong: “Credential stuffing: rate limit login to 10 attempts per IP per 10 minutes. After 5 failures for a specific account, require CAPTCHA. After 10 failures, lock account for 15 minutes and send unlock email. Phishing mitigation: set SameSite=Strict on session cookies; login page served only on the canonical domain (no subdomains). Session fixation: generate a new session ID on every successful authentication.”

✗ Weak: “The system is protected against common attacks.” (Which attacks? By what mechanism? No engineer can implement “common attack protection” from this instruction.)

Common mistakes

No token revocation mechanism. Long-lived tokens (OAuth access tokens, JWTs) without revocation are credentials that cannot be invalidated if compromised. Logging out a user, revoking compromised tokens, or terminating a session requires revocation. Design revocation before launch.

Session tokens in localStorage. LocalStorage is accessible to JavaScript, making any XSS vulnerability into a session token theft. Session tokens must be in httpOnly cookies. This is a one-character configuration difference with major security implications—the spec must be explicit.

Designing authentication only for human users. Modern systems have machine clients (webhooks, service-to-service calls, CI pipelines) that also need authentication. API keys, service tokens, and machine credentials require their own authentication model and lifecycle management.

Assuming HTTPS enforcement. Designing for HTTPS without specifying HSTS headers, certificate pinning, and upgrade redirects leaves gaps. The auth design must specify how HTTP→HTTPS redirection works and what the HSTS policy is.

How to use this document

When to create it

Write the authentication design before implementing any authentication code. For systems using an identity provider (Auth0, Cognito, Okta), the design documents how the provider is configured and integrated, not invented from scratch. For password-based auth, the design is especially critical.

Who owns it

The security lead or the engineer with the most security experience. Reviewed by the tech lead. Any change to authentication must be reviewed against the design document before implementation.

How AI agents should reference it

get_standard_docs(type="web_app", features=["auth"])
→ auth_design in documents[]
→ agent reads auth design before generating any authentication code
→ agent applies specified token lifecycle: 15-minute JWT expiry, bcrypt cost 12
→ agent uses httpOnly cookies, not localStorage, for session tokens
→ agent validates login attempt rate limiting matches specified thresholds

The prompt_snippet — “Ensure the project has an authentication design covering identity providers, credential storage, MFA flows, and token lifecycle management” — tells the agent to verify all four dimensions are covered with specific values, not vague references.

How it connects to other documents

Authentication Design is constrained by the Security & Privacy Plan (which sets the overall security posture) and the Threat Model (which identifies the specific auth attack vectors that must be mitigated). It feeds the Tenant Isolation Specification (which uses auth to enforce multi-tenancy boundaries) and all authorization/RBAC specifications that build on top of verified identity.

Recommended Reading

• The Web Application Hacker’s Handbook by Dafydd Stuttard & Marcus Pinto — Chapter on authentication covers every common attack vector the auth design must mitigate.
• OAuth 2.0 in Action by Justin Richer & Antonio Sanso — Comprehensive coverage of OAuth 2.0 and OIDC; essential for federated identity integration.
• OWASP Authentication Cheat Sheet (owasp.org) — Practitioner reference for authentication security requirements; directly applicable to writing the “attack mitigations” section.