Opaque Token-Based Authentication Security Pattern

A subject is authenticated based on a unique, opaque token provided with action requests. The system maintains a mapping of valid tokens to principals. Token secrecy is crucial as it's the sole proof of identity.

Core Components

Role	Type	Responsibility
Subject	Entity	Provides token with action requests
Enforcer	Enforcement Point	Ensures token verification before processing
Verifier	Decision Point	Validates token and retrieves principal
Principal Provider	Entity	Maintains token-to-principal mapping
Registrar	Entity	Issues tokens after initial authentication
Token Generator	Cryptographic Primitive	Generates secure random tokens

Data Elements

token: Opaque identifier (no embedded meaning)
principal: Identity associated with token
credential factor: "Something you have"

Token Characteristics

Opaque tokens:

Contain no meaningful information themselves
Require server-side lookup to determine principal
Must be cryptographically random
Should be unique across all active sessions

Token Generation Requirements

Entropy

Minimum 64 bits of entropy to prevent guessing
Generate tokens of at least 128 bits using CSPRNG
Use cryptographically secure pseudo-random number generator

Secure Generators by Language

Java: java.security.SecureRandom
Python: secrets module
Node.js: crypto.randomBytes()
.NET: RNGCryptoServiceProvider

Authentication Flow

Subject → [action + token] → Enforcer
Enforcer → [token] → Verifier
Verifier → [get_principal(token)] → Principal Provider
Principal Provider → [principal or error] → Verifier
Verifier → [principal or error] → Enforcer
Enforcer → [action + principal] → System (if valid)

Token Registration (Issuance)

Subject authenticates via primary method (password, etc.)
Registrar requests new token from Principal Provider
Token Generator creates secure random token
Principal Provider stores token→principal mapping
Token returned to Subject

Important: Check for duplicate tokens before issuing; regenerate if collision detected.

Token Lifecycle Management

Timeout Policies

Idle timeout: Invalidate after period of inactivity
Absolute timeout: Maximum lifetime regardless of activity
Recommended: Both idle AND absolute timeouts

Token Invalidation

On logout: Remove from Principal Provider
On re-authentication: Invalidate old tokens before issuing new
On credential change: Invalidate all tokens for that principal

Lost Tokens

Cannot be "reset" - Subject must re-authenticate
No recovery mechanism should exist

Security Considerations

Token Secrecy

Transmit only over HTTPS
Store securely (HttpOnly, Secure cookies)
Never log tokens
Never expose in URLs

Guessing Prevention

Sufficient entropy (128+ bits)
Rate limit token verification attempts
Monitor for brute-force patterns

Session Fixation Prevention

Always issue new token after authentication
Never accept client-provided tokens as session identifiers

Token Binding

Consider binding to client characteristics (IP, user-agent)
Balance security vs. usability (mobile networks change IPs)

Common Implementation: Session IDs

Web session identifiers follow this pattern:

Generated on successful login
Stored in secure cookie
Server maintains session store
Invalidated on logout

Comparison with Verifiable Tokens

Aspect	Opaque Token	Verifiable Token
Principal storage	Server-side	In token
Revocation	Immediate	Requires strategy
Scalability	Requires shared storage	Stateless
Token size	Small	Larger

Implementation Checklist

References

Source: https://securitypatterns.distrinet-research.be/patterns/01_01_004__opaque_token_based_authentication/
OWASP Session Management Cheat Sheet

opaque-token-based-authentication-pattern