Designing a Session Management System: Tokens, Storage Backends, and Revocation at Scale

Most systems ship a session implementation that works fine until it doesn’t. The happy path is straightforward: generate a token, store it, validate it on each request. The failure modes are less obvious: a user changes their password and their stolen sessions keep working for another 24 hours; a compromised Redis node exposes every active session in the system; a multi-region deploy creates split-brain session state that makes some users randomly appear logged out.

Session management is a load-bearing piece of infrastructure. Getting it wrong has direct security and reliability consequences. This article covers the decisions that matter: token format, storage backend, revocation patterns, distributed consistency, and the security properties you need to reason about before you ship.

Token Formats: Opaque vs JWT

The first design decision is what the session token actually contains.

Opaque tokens are random strings that carry no information. The server looks them up in a store to retrieve session data. A 32-byte cryptographically random token, base64url-encoded, gives you 256 bits of entropy and is not guessable.

import { randomBytes } from "crypto";

function generateOpaqueToken(): string {
  return randomBytes(32).toString("base64url");
}

interface SessionRecord {
  sessionId: string;
  userId: string;
  createdAt: Date;
  lastSeenAt: Date;
  expiresAt: Date;
  ipAddress: string;
  userAgent: string;
  metadata: Record<string, unknown>;
}

JWTs encode session data directly in the token, signed with a secret or private key. The server can verify the signature and read the payload without a storage lookup.

import { SignJWT, jwtVerify } from "jose";

interface SessionClaims {
  sub: string;        // userId
  sid: string;        // sessionId for revocation
  iat: number;
  exp: number;
  roles: string[];
}

async function issueSessionToken(
  userId: string,
  sessionId: string,
  roles: string[],
  secret: Uint8Array
): Promise<string> {
  return new SignJWT({ sid: sessionId, roles })
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(userId)
    .setIssuedAt()
    .setExpirationTime("24h")
    .sign(secret);
}

async function verifySessionToken(
  token: string,
  secret: Uint8Array
): Promise<SessionClaims> {
  const { payload } = await jwtVerify(token, secret);
  return payload as unknown as SessionClaims;
}

The critical thing to understand about JWTs: they are valid until expiry unless you maintain a revocation list. A user who logs out, changes their password, or whose account is suspended continues to hold a cryptographically valid token until it expires. If your tokens have a 24-hour expiry, your revocation window is 24 hours. For many systems, that is not acceptable.

The standard mitigation is short-lived JWTs (5-15 minutes) combined with a separate refresh token stored server-side. This restores the ability to revoke sessions at the cost of a token refresh flow. At that point you have essentially built a hybrid: the JWT carries claims for the hot path, the refresh token in storage is the revocation surface.

Storage Backends

Session storage has three dominant patterns: in-memory cache (Redis), distributed key-value (DynamoDB), and relational database. Each has a different operational profile.

Redis

Redis is the default choice for high-throughput session storage. Sub-millisecond reads, built-in TTL for automatic expiry, and support for secondary indexing via sorted sets for listing sessions by user.

import { Redis } from "ioredis";

const redis = new Redis({ host: "session-cache.internal", port: 6379 });

const SESSION_PREFIX = "session:";
const USER_SESSIONS_PREFIX = "user_sessions:";

async function createSession(session: SessionRecord): Promise<void> {
  const key = `${SESSION_PREFIX}${session.sessionId}`;
  const userKey = `${USER_SESSIONS_PREFIX}${session.userId}`;
  const ttlSeconds = Math.floor(
    (session.expiresAt.getTime() - Date.now()) / 1000
  );

  const pipeline = redis.pipeline();
  // store session as hash
  pipeline.hset(key, {
    userId: session.userId,
    createdAt: session.createdAt.toISOString(),
    lastSeenAt: session.lastSeenAt.toISOString(),
    ipAddress: session.ipAddress,
    userAgent: session.userAgent,
  });
  pipeline.expire(key, ttlSeconds);

  // track active sessions per user for bulk revocation
  pipeline.zadd(userKey, session.expiresAt.getTime(), session.sessionId);
  pipeline.expire(userKey, ttlSeconds + 60);

  await pipeline.exec();
}

async function getSession(sessionId: string): Promise<SessionRecord | null> {
  const key = `${SESSION_PREFIX}${sessionId}`;
  const data = await redis.hgetall(key);
  if (!data || !data.userId) return null;

  return {
    sessionId,
    userId: data.userId,
    createdAt: new Date(data.createdAt),
    lastSeenAt: new Date(data.lastSeenAt),
    expiresAt: new Date(data.expiresAt ?? 0),
    ipAddress: data.ipAddress,
    userAgent: data.userAgent,
    metadata: {},
  };
}

The weakness with Redis alone: it is not durable by default. If Redis goes down and your fallback is to reject all requests, you have a hard dependency on a single service. In practice this means running Redis with persistence enabled (AOF), using a replica for reads, and planning what happens on cache miss (check a secondary durable store, or fail closed).

DynamoDB

DynamoDB gives you durability and automatic TTL without the operational overhead of managing a Redis cluster. The tradeoff is latency: single-digit milliseconds vs sub-millisecond for Redis.

import { DynamoDBClient, PutItemCommand, GetItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";

const client = new DynamoDBClient({ region: "us-east-1" });
const TABLE_NAME = "sessions";

async function createSessionDynamo(session: SessionRecord): Promise<void> {
  const ttlEpoch = Math.floor(session.expiresAt.getTime() / 1000);
  await client.send(
    new PutItemCommand({
      TableName: TABLE_NAME,
      Item: marshall({
        pk: `SESSION#${session.sessionId}`,
        sk: "RECORD",
        gsi1pk: `USER#${session.userId}`,
        gsi1sk: session.createdAt.toISOString(),
        ...session,
        ttl: ttlEpoch,
      }),
      ConditionExpression: "attribute_not_exists(pk)",
    })
  );
}

The Global Secondary Index on userId is how you query all sessions for a user. DynamoDB TTL deletes items within 48 hours of expiry (not exactly at expiry), so your application layer must still check expiresAt on reads.

Database-backed

For systems where session data needs to be joined with other records, or where you want auditability by default, storing sessions in Postgres is a reasonable choice. The cost is latency on every authenticated request unless you add a caching layer.

// schema
// CREATE TABLE sessions (
//   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
//   user_id UUID NOT NULL REFERENCES users(id),
//   token_hash TEXT NOT NULL UNIQUE,
//   created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
//   last_seen_at TIMESTAMPTZ NOT NULL DEFAULT now(),
//   expires_at TIMESTAMPTZ NOT NULL,
//   ip_address INET,
//   user_agent TEXT,
//   revoked_at TIMESTAMPTZ,
//   revocation_reason TEXT
// );
// CREATE INDEX idx_sessions_user_id ON sessions(user_id) WHERE revoked_at IS NULL;

import { createHash } from "crypto";

function hashToken(token: string): string {
  return createHash("sha256").update(token).digest("hex");
}

async function validateSessionDB(
  token: string,
  db: DatabaseClient
): Promise<SessionRecord | null> {
  const tokenHash = hashToken(token);
  const row = await db.queryOne(
    `SELECT * FROM sessions
     WHERE token_hash = $1
       AND expires_at > now()
       AND revoked_at IS NULL`,
    [tokenHash]
  );
  if (!row) return null;

  // rolling window: update last_seen_at
  await db.execute(
    `UPDATE sessions SET last_seen_at = now() WHERE id = $1`,
    [row.id]
  );

  return row as SessionRecord;
}

Note that you never store the raw token. You store a SHA-256 hash. If the database is compromised, an attacker gets hashes that cannot be reversed to valid tokens.

Revocation Patterns

Individual Session Revocation

The simplest case: a user clicks “log out from this device.” Delete or mark the session record as revoked.

For opaque tokens in Redis, deletion is immediate and authoritative. For JWTs, you need a revocation list keyed by sid (the session ID embedded in the JWT). The list only needs to survive until the JWT expires.

async function revokeSession(sessionId: string): Promise<void> {
  // for opaque: delete from store
  await redis.del(`${SESSION_PREFIX}${sessionId}`);
  await redis.zrem(`${USER_SESSIONS_PREFIX}${/* userId */sessionId}`, sessionId);

  // for JWT: add to short-lived blocklist
  const jwtBlocklistKey = `jwt_revoked:${sessionId}`;
  await redis.set(jwtBlocklistKey, "1", "EX", 86400); // expire with JWT lifetime
}

Bulk Revocation

Bulk revocation is the hard case. It covers: password change (revoke all other sessions), account suspension, compromised credential scenarios, and “log out everywhere” from a security settings page.

With Redis and the user-sessions sorted set, you can retrieve and delete all session keys for a user atomically:

async function revokeAllUserSessions(
  userId: string,
  exceptSessionId?: string
): Promise<number> {
  const userKey = `${USER_SESSIONS_PREFIX}${userId}`;
  const sessionIds = await redis.zrange(userKey, 0, -1);

  const toRevoke = exceptSessionId
    ? sessionIds.filter((id) => id !== exceptSessionId)
    : sessionIds;

  if (toRevoke.length === 0) return 0;

  const pipeline = redis.pipeline();
  for (const sessionId of toRevoke) {
    pipeline.del(`${SESSION_PREFIX}${sessionId}`);
  }
  pipeline.zrem(userKey, ...toRevoke);
  await pipeline.exec();

  return toRevoke.length;
}

For JWTs without per-session tracking, bulk revocation usually means versioning the user record with a sessionVersion counter and embedding that version in the JWT. When a user’s sessionVersion increments, all previously issued JWTs fail validation.

interface VersionedSessionClaims extends SessionClaims {
  version: number;
}

async function validateVersionedJWT(
  token: string,
  secret: Uint8Array,
  getUserVersion: (userId: string) => Promise<number>
): Promise<VersionedSessionClaims | null> {
  try {
    const { payload } = await jwtVerify(token, secret);
    const claims = payload as unknown as VersionedSessionClaims;
    const currentVersion = await getUserVersion(claims.sub);
    if (claims.version < currentVersion) return null;
    return claims;
  } catch {
    return null;
  }
}

This requires a database read on every request to check the version, which partially negates the stateless benefit of JWTs. Cache the version with a short TTL (10-30 seconds) to keep the hot path fast while bounding revocation lag.

Rolling Sessions

Rolling sessions extend the expiry on each request so active users stay logged in without hitting a hard expiry. The implementation detail that breaks this: if you update expiresAt on every request, you create a write-heavy workload. Throttle the extension to once per N minutes:

const ROLLING_WINDOW_SECONDS = 300; // extend at most once per 5 minutes
const SESSION_DURATION_SECONDS = 86400; // 24h total lifetime

async function touchSession(sessionId: string): Promise<void> {
  const key = `${SESSION_PREFIX}${sessionId}`;
  const ttl = await redis.ttl(key);

  // only extend if we're within the rolling window of expiry
  if (ttl < SESSION_DURATION_SECONDS - ROLLING_WINDOW_SECONDS) {
    await redis.expire(key, SESSION_DURATION_SECONDS);
  }
}

Security Considerations

Session Fixation

Session fixation happens when an attacker pre-sets a session identifier in a victim’s browser (via URL parameter or cookie injection) and waits for the victim to authenticate. After login, the victim’s session is bound to the attacker’s known identifier.

The fix is simple and non-negotiable: always generate a new session ID on authentication success. Never reuse a pre-authentication session ID.

async function handleLogin(
  userId: string,
  preAuthSessionId: string | null
): Promise<string> {
  // always revoke any pre-auth session
  if (preAuthSessionId) {
    await revokeSession(preAuthSessionId);
  }

  const newSessionId = generateOpaqueToken();
  await createSession({
    sessionId: newSessionId,
    userId,
    createdAt: new Date(),
    lastSeenAt: new Date(),
    expiresAt: new Date(Date.now() + SESSION_DURATION_SECONDS * 1000),
    ipAddress: "", // from request context
    userAgent: "", // from request context
    metadata: {},
  });

  return newSessionId;
}

Session Hijacking

Set cookies with HttpOnly, Secure, and SameSite=Strict (or Lax for OAuth flows). HttpOnly prevents JavaScript access, which is your first line of defense against XSS-based session theft. Secure ensures the cookie is never sent over plaintext HTTP. SameSite=Strict blocks cross-site request forgery.

Bind sessions to IP address or User-Agent as a defense-in-depth measure. A mismatch on a validated session is a signal worth logging, though you should not hard-reject on IP mismatch alone since mobile users change IPs frequently.

Replay Attacks

For high-sensitivity operations, add a nonce to session tokens that is consumed once on use. This is most relevant for short-lived operation tokens (password reset, email verification), not general session tokens, but the pattern is the same: mark the token as used atomically and reject reuse.

Distributed Session Consistency

Multi-region deployments introduce replication lag. If a session is created in us-east-1 and immediately validated in eu-west-1, the validation may hit a replica that has not received the write yet.

The options are ordered by operational cost:

1. Sticky routing: Route all requests for a user to the same region. Simple, but breaks during region failover and complicates load balancing.

2. Strong read for token creation only: Write sessions to a primary and wait for replication before returning the token to the client. All subsequent reads can go to the local replica. The one-time creation latency is acceptable; the hot-path validation latency is not.

3. Read-your-writes consistency: Route the first N requests after session creation to the primary. After a grace period (e.g., 5 seconds), allow routing to replicas. Redis Cluster and DynamoDB Global Tables both support this with careful client configuration.

4. Accept stale reads with retry: If a replica returns “session not found” but the client indicates the session was just created (via a header or short-lived cookie), retry against the primary. This is the most operationally complex but requires no special routing logic.

For most systems, option 2 is the right starting point. The creation path is rare relative to the validation path, so paying the latency cost there is an acceptable tradeoff.

Tradeoffs Summary

Dimension	Opaque Token + Redis	Opaque Token + DynamoDB	JWT + Short TTL	JWT + Version Counter
Validation latency	Sub-ms (cache hit)	Single-digit ms	No I/O required	1 DB/cache read
Revocation granularity	Immediate, per-session	Immediate, per-session	On expiry only	On version increment
Bulk revocation	Delete all keys per user	Scan + delete via GSI	Increment version field	Increment version field
Durability	Configurable (AOF)	Strong (by default)	Token itself is durable	Token + version store
Storage cost	Low	Pay per read/write	None (stateless)	1 field in user record
Multi-region	Replication required	Global Tables	No sync needed	Version sync required
Operational complexity	Redis cluster ops	Managed, minimal	Key rotation	Version cache ops

Production Considerations

Key rotation. HMAC signing keys for JWTs need rotation without invalidating all live sessions. The standard pattern is to keep a key ring with multiple active keys, tag each JWT with a kid header matching the key used to sign it, and retire old keys only after their issued tokens have all expired.

Session limits per user. Enforce a maximum number of concurrent sessions per user (10 is a reasonable starting point for consumer apps). When the limit is exceeded, revoke the oldest session. This bounds the surface area of a compromised account and prevents resource exhaustion from credential stuffing.

Observability. Track: session creation rate (spike indicates brute force or credential stuffing), validation error rate by reason (expired, revoked, malformed), average session lifetime, and revocation events by trigger (logout, password change, admin, expiry). Alert on unusual geographic distribution of session creations for a single user.

Grace period on expiry. Clock skew between client and server can cause tokens to appear expired before the user expects. Allow a 30-60 second grace window on expiry validation. Do not propagate this grace window to JWTs in untrusted contexts.

Session migration on privilege change. When a user’s roles or permissions change (promotion to admin, subscription upgrade), consider forcing a session rotation so the new claims are reflected in the next token. For JWTs, this is required since claims are embedded in the token. For opaque tokens backed by a store, you can update the session record in place, but a forced rotation makes the change immediate and auditable.

Closing

Session management is mostly boring infrastructure that becomes very interesting when something goes wrong. The decisions that matter most are not in the happy path: they are in what happens when a token is stolen, when you need to revoke a million sessions in under a second, when a Redis replica is stale, or when an attacker tries to fix a session before authentication.

Get the token format right for your revocation requirements. Match the storage backend to your durability and latency constraints. Build bulk revocation before you need it. The time to design the “log out everywhere” flow is not during an incident.