Token Blacklisting
A server-side list of revoked tokens that are checked on each request to deny access from tokens that have been invalidated before their natural expiration.
Description
Token blacklisting is a server-side mechanism that maintains a list of revoked tokens, checked during request validation to reject tokens that have been explicitly invalidated. This is primarily necessary for self-contained tokens like JWTs, which are inherently stateless and cannot be revoked without an external mechanism. The blacklist acts as a negative cache -- if a token's identifier (typically the jti claim) appears in the blacklist, the token is rejected regardless of its cryptographic validity.
The most common implementation uses Redis for its speed, atomic operations, and native TTL support. When a token is revoked, its jti is stored as a Redis key with a TTL equal to the token's remaining lifetime. Since the token would be invalid after expiration anyway, the blacklist entry naturally cleans up when it is no longer needed. This approach keeps the blacklist size bounded by the number of revoked tokens that have not yet expired. For a system with 15-minute access tokens, the blacklist at any point contains at most 15 minutes' worth of revoked tokens.
Blacklisting introduces a per-request lookup cost that must be considered for high-throughput systems. Redis performs single-key lookups in sub-millisecond time, so the overhead is minimal. For additional optimization, use a local in-memory bloom filter as a first-pass check before hitting Redis -- if the bloom filter says the token is not in the blacklist, skip the Redis lookup. For clustered deployments, use Redis Cluster or a replicated setup for both performance and availability. Monitor blacklist size and lookup latency as operational metrics, and implement fallback behavior (deny or allow) for cases when the blacklist store is unavailable.
Prompt Snippet
Implement JWT blacklisting using Redis. On token revocation, store the jti claim as a key with SETEX: SETEX blacklist:{jti} {remaining_ttl} 1. In the JWT validation middleware, after signature and claims verification, check EXISTS blacklist:{jti} in Redis -- reject with 401 if present. Calculate remaining_ttl as exp - current_time to ensure automatic cleanup. For bulk revocation (e.g., password change), store a per-user invalidation timestamp: SET user:{id}:tokens_invalid_before {timestamp}. During validation, compare the JWT's iat against this timestamp. Monitor Redis key count with pattern blacklist:* for operational visibility. Use Redis Sentinel or Cluster for high availability.Tags
Related Terms
Token Revocation
The mechanism for invalidating issued access or refresh tokens before their natural expiration, typically triggered by logout, password change, or security events.
JWT (JSON Web Tokens)
A compact, URL-safe token format that encodes claims as a JSON object, digitally signed for integrity verification and optionally encrypted for confidentiality.
JWT Refresh Token Rotation
A security strategy where each use of a refresh token issues a new refresh token and invalidates the old one, detecting token theft through reuse detection.
Session Management
The practice of securely creating, maintaining, and destroying user sessions to track authenticated state across stateless HTTP requests.
Auth Middleware / Guards
Reusable middleware or guard components that intercept requests to enforce authentication and authorization policies before they reach route handlers.