Redis Session Management#

oauth2-proxy's Redis session store separates session data from the browser cookie: the cookie carries only a signed ticket (a pointer + per-session encryption key), while the full SessionState is stored encrypted in Redis. This design keeps cookie size small and session data server-side, enabling distributed locking for safe token refresh.

Key packages:

Cookie-to-Session Mapping (Ticket System)#

Each session is identified by a ticket stored as the cookie value. A ticket contains two parts 1:

1. Ticket ID — a {cookie-name}-{16-byte hex random} string, used as the Redis key.
2. Ticket secret — a random 16-byte AES key unique to this session.

The cookie value is encoded as v2.{base64(ticketID)}.{base64(secret)} and signed with the shared cookie-secret before being sent to the browser 2 3.

On each request, Manager.Load:

1. Reads and validates the signed cookie.
2. Decodes the ticket to extract the ID and per-session secret.
3. Uses the ID to fetch ciphertext from Redis and the secret to decrypt it.

On save, Manager.Save reuses an existing ticket if one is present in the request cookie, or generates a new one. The ticket ID becomes the Redis key; TTL is set from --cookie-expire.

Encryption / Decryption#

Session data is encrypted with AES-GCM using the per-session ticket secret 4. This is distinct from the shared cookie-secret used only to sign the cookie carrying the ticket.

• Save path: ticket.saveSession encodes the SessionState (MessagePack + optional LZ4 compression, then AES-GCM), then calls Store.Save to write the ciphertext to Redis with the configured TTL.
• Load path: ticket.loadSession fetches ciphertext from Redis, reconstructs the AES-GCM cipher from the ticket secret, decodes the session, and attaches a Lock object to SessionState.Lock.

The Redis Store methods themselves are thin wrappers — Save, Load, Clear — that delegate directly to the Redis client with no additional transformation.

Distributed Locking for Token Refresh#

To prevent multiple concurrent requests from double-refreshing the same token (a critical issue with providers that rotate refresh tokens), oauth2-proxy uses a per-session distributed lock in Redis.

Lock key format: {ticketID}.lock 5

Lock implementation: redis.Lock wraps bsm/redislock 6 and implements the sessions.Lock interface with four operations: Obtain, Peek, Refresh, Release.

The lock is wired during session load: ticket.loadSession calls the initLockFunc callback (bound to redis.SessionStore.Lock()) and assigns the result to sessionState.Lock.

Refresh flow in refreshSessionIfNeeded:

1. Acquire — retry-loop calling session.ObtainLock with a 2-second lock TTL 7. Timeout after 5 seconds if the lock cannot be obtained 8.
2. Reload — once locked, re-fetch the session from Redis; if another goroutine already refreshed it, skip the provider call 9.
3. Refresh & save — call the provider, update CreatedAt, and persist via Store.Save 10.
4. Release — deferred session.ReleaseLock runs on exit regardless of outcome 11.

Both timeout constants have TODO comments noting they should become user-configurable 12.

Deployment Modes#

NewRedisSessionStore selects the client type based on flags 13; --redis-use-sentinel and --redis-use-cluster are mutually exclusive 14:

TLS is supported via --redis-ca-path and --redis-insecure-skip-tls-verify 15. The --redis-connection-idle-timeout must be set strictly less than the Redis server's own timeout setting (docs).

Configuration Quick-Reference#

Enable Redis with --session-store-type=redis. Cookie expiry (--cookie-expire, default 168h) sets Redis key TTL; --cookie-refresh controls how frequently sessions are refreshed (and the lock exercised). See the official session storage docs for the full option list.