| name | verifiable-token-based-authentication-pattern |
| description | Security pattern for self-contained token authentication (e.g., JWT). Use when implementing stateless authentication, designing tokens with embedded claims, or building systems where tokens contain principal information and can be verified without server-side storage. Specialization of Authentication pattern. |
Verifiable Token-Based Authentication Security Pattern
A subject is authenticated using a token that itself contains the necessary information to determine the principal. The system verifies the token is valid (not tampered, not expired) without needing to look up stored evidence.
Core Components
| Role | Type | Responsibility |
|---|
| Subject | Entity | Provides token with action requests |
| Enforcer | Enforcement Point | Ensures token verification before processing |
| Verifier | Decision Point | Manages token validity verification |
| Cryptographer | Cryptographic Primitive | Verifies token integrity |
| Key Manager | Entity | Manages cryptographic keys |
| Registrar | Entity | Issues tokens after initial authentication |
Data Elements
- token: Self-contained credential with principal and metadata
- principal: Identity extracted from valid token
- expiration: Token validity period
- signature/MAC: Cryptographic integrity protection
Token Structure
A verifiable token must contain:
- Principal identifier (username, user ID, email)
- Expiration date/time
- Cryptographic signature or MAC
- Optional: Additional claims (roles, permissions, metadata)
Token Integrity Verification
Two approaches:
Digital Signature (Asymmetric)
- Token signed with private key
- Verified with public key
- Enables verification without sharing signing key
- Use RSA (min 2048 bits) or ECDSA (min 256 bits)
MAC (Symmetric)
- Token authenticated with shared secret
- Same key for creation and verification
- Use HMAC with min 128-bit keys
Recommendation: Use cryptographic keys with at least 128 bits of entropy.
Verification Flow
Subject → [action + token] → Enforcer
Enforcer → [token] → Verifier
Verifier → [get key] → Key Manager
Key Manager → [key] → Verifier
Verifier → [verify integrity] → Cryptographer
Cryptographer → [result] → Verifier
Verifier → [check expiration, extract principal] → Verifier
Verifier → [principal or error] → Enforcer
Verification steps:
- Verify integrity (signature/MAC)
- Check expiration date
- Check revocation status (if implemented)
- Extract and return principal
Token Registration (Issuance)
- Subject authenticates via other means (e.g., password)
- Registrar generates token with:
- Principal identifier
- Expiration date
- Additional claims
- Cryptographic signature/MAC
- Token returned to Subject
Security Considerations
Token Lifetime
- Shorter = more secure, less convenient
- Include absolute expiration
- Consider refresh token pattern for long sessions
Token Revocation
- Stateless tokens cannot be directly revoked
- Options: short lifetimes, revocation lists, token versioning
Token Storage (Client-Side)
- Web: HttpOnly, Secure cookies or secure storage
- Mobile: Secure enclave/keychain
- Never store in localStorage for sensitive apps
Token Transmission
- Always use HTTPS
- Consider token binding
No Token Reset
- Tokens should never be reset on request
- Subject must re-authenticate for new token
Integrity is Paramount
- Never accept tampered tokens
- Verify signature before trusting any claims
Common Implementation: JWT
JSON Web Tokens follow this pattern:
- Header: algorithm, type
- Payload: claims (principal, exp, iat, etc.)
- Signature: cryptographic verification
Warning: Always verify signature; never use "none" algorithm.
Implementation Checklist
References
