Skip to content
fzymgc-house Cluster Docs

Move oauth2-proxy to Valkey server-side session store

Date: 2026-07-05 Status: Accepted Decision: hl-4z56 Deciders: Sean Brandt

Context

Section titled “Context”

oauth2-proxy used the chart-default cookie session store, embedding full OAuth tokens (id/access/refresh, inflated by the groups claim) in a ~4.7 KB cookie scoped to the parent domain .fzymgc.house. That dead-weight cookie was the dominant contributor to Keycloak’s HTTP/2 header-limit outage (hl-g3sv, already patched by raising Keycloak’s max-header-list-size). This decision removes the cause of the bloat by replacing the cookie store with an operator-managed, Sentinel-HA Valkey store over TLS, shrinking the cookie to a ~150 B ticket.

Decision

Section titled “Decision”

Set oauth2-proxy sessionStorage.type=redis against an operator-managed, Sentinel-HA Valkey deployment reached over TLS (rediss://), replacing the default cookie store. cookie_domains (.fzymgc.house, for cross-app SSO) and cookie_secret are unchanged — the browser cookie becomes a small encrypted ticket.

Rationale

Section titled “Rationale”
  • Cookie bloat is a function of the session-storage strategy, not cookie scoping — narrowing cookie_domains cannot exclude one subdomain and would not fix bandwidth or token exposure.
  • Removing tokens from the browser fixes the root cause cluster-wide, not just the Keycloak symptom already patched by hl-g3sv.

Alternatives Considered

Section titled “Alternatives Considered”
  • Keep the cookie session store / status quo (rejected): no new infra, but full tokens ride to every *.fzymgc.house host — including the IdP, which never uses oauth2-proxy — driving header-size bloat and widening the token-leak blast radius.
  • Narrow cookie_domains instead (rejected): a parent-domain cookie technically cannot exclude a single subdomain; would break cross-app SSO without fixing bandwidth or exposure.
  • Server-side store — Valkey, Sentinel HA, TLS (chosen): cookie shrinks ~4.7 KB to ~150 B, tokens leave the browser, aligns with oauth2-proxy best practice, and is mesh-neutral (Traefik forwardAuth today, Envoy ext_authz later). Cost: a new stateful HA dependency that becomes availability-critical.

Consequences

Section titled “Consequences”
  • Positive: the cookie is a ~150 B ticket and tokens never reach the browser, shrinking the leak blast radius; header-size headroom is restored cluster-wide.
  • Negative: Valkey/Sentinel becomes an availability-critical dependency for every oauth2-proxy-protected app — quorum loss locks out already-authenticated users (per-request forwardAuth), not just new logins, so its effective SLO must meet or exceed theirs.
  • Neutral: one-time forced re-login for all users at cutover; fully reversible by reverting the store config.