Token Refresh Concurrency#

When multiple requests for the same user arrive simultaneously around the time a session token needs refreshing, oauth2-proxy can attempt to redeem the same refresh token more than once. Providers that enforce refresh token rotation (one-time-use tokens) will revoke the token after the first successful redemption, causing all subsequent concurrent attempts to fail with invalid_grant. This is the primary operational risk when --cookie-refresh is configured.

How the Lock Protocol Works#

The serialization logic lives in refreshSessionIfNeeded inside pkg/middleware/stored_session.go. The flow is:

1. Acquire lock — each request calls session.ObtainLock in a tight retry loop (10 ms sleep between attempts) 1. If the lock is not obtained within 5 seconds, the refresh attempt times out 2.
2. Re-load the session — once the lock is held, the session is reloaded from the store 3. If another goroutine already refreshed it, needsRefresh returns false and the caller skips the redundant provider call 4.
3. Refresh and save — only the single lock holder calls the provider and saves the updated session 5.
4. Release lock — the lock is released in a defer block regardless of success or failure 6.

The lock is keyed per-session. The lock duration is hardcoded to 2 seconds 7, which is the maximum window the lock holder has to complete the refresh. Both timeout values have inline TODO comments noting they should be made user-configurable.

The Lock Interface and Implementations#

The Lock interface in pkg/apis/sessions/interfaces.go defines four operations: Obtain, Peek, Refresh, Release.

The cookie store never sets a Lock on the loaded SessionState 9, so ObtainLock silently initializes and uses NoOpLock 10. The locking middleware runs unconditionally, but with a cookie store it provides no protection.

For Redis, the lock is assigned during ticket-based session loading in ticket.loadSession via the initLockFunc callback, which is wired to redis.SessionStore.Lock().

Cookie Store: The Core Limitation#

With --session-store-type=cookie (the default), every concurrent request can and will attempt a provider refresh simultaneously. There is no server-side state to coordinate them. The repeated log lines:

[AuthSuccess] Refreshing session
[AuthSuccess] Refreshing session
[AuthSuccess] Refreshing session

are a diagnostic signal that this race is occurring 11. The issue is reproducible even with a single oauth2-proxy replica because the race originates from concurrent browser requests (e.g., page resources, API calls), not cross-replica coordination 11.

This limitation is acknowledged explicitly in the context of the HTTP session store feature proposal, which notes that --cookie-refresh combined with a non-Redis store has no concurrent refresh protection.

Mitigation#

Switch to --session-store-type=redis — this is the only current mitigation. The Redis-backed lock ensures exactly one goroutine per session performs the provider refresh, with all others transparently using the already-refreshed session data after the lock is released 11.

Workarounds that do not fully solve the problem:

• Increasing --cookie-refresh reduces refresh frequency but doesn't eliminate the race window.
• Disabling refresh token rotation on the provider removes the failure mode but sacrifices a security control.

Fatal vs. Non-Fatal Refresh Errors#

When a refresh does fail, isFatalRefreshError classifies the error. invalid_grant and invalid_client (per RFC 6749 §5.2) trigger immediate session invalidation and force re-authentication. Network errors and timeouts are treated as non-fatal — the existing session is preserved and validateSession determines if it is still usable 12.

Key Source Files#