Keeping Tokens Off the Browser:
The BFF Session Pattern

The problem with browsers holding JWTs

The standard SPA auth pattern looks like this: user logs in, the browser receives a JWT access token, stores it in localStorage or memory, and sends it as Authorization: Bearer <token> on every request. It works. But it has a property that's easy to overlook until it isn't: the token contains your user's identity and permissions, and it's sitting in a JavaScript runtime that is one XSS vulnerability away from exfiltration.

Once an attacker has your access token, they can impersonate you until it expires. The JWT expiry window becomes a window during which the breach is silent — there's no server-side switch to flip.

The BFF pattern: move the tokens server-side

The Backend-for-Frontend (BFF) pattern solves this by keeping tokens on the server. The browser holds an opaque session identifier — a random value with no claims, no expiry, no user data. The server maps that identifier to the actual JWT and refresh token stored in Redis.

Why this is our own code, not a proxy binary

There's a well-known off-the-shelf option for this — a reverse proxy that sits in front of your app, handles the OIDC dance, and stores sessions in Redis. It's a fine choice in production. We're deliberately not naming or featuring one here, for the same reason the rest of this site avoids naming specific vendor products as the point of a demo: the pattern is what matters, not the brand.

Building the ~150-line FastAPI session-service ourselves also made the mechanics visible in a way a black-box proxy wouldn't: the opaque session ID generation, the Redis key structure, the auto-refresh logic, the revocation path.

Building it surfaced the architecture questions early: What happens when the resolve call can't reach Redis? (Fail-closed — no session found means no access.) What's the revocation model? (DELETE the Redis key → instant, no JWT expiry window.) How does auto-refresh work transparently? (Check exp on every resolve, call Keycloak's refresh endpoint if within 30s.)

What session-service actually does

Instant revocation: the biggest win

With pure JWT authentication — the gateway pattern demo, for example — revoking access requires waiting for the token to expire. A 2-minute access token means a 2-minute window after logout during which the user can still access protected resources, because logout there is purely client-side (clear localStorage; the JWT itself doesn't know it's been "logged out").

With the BFF pattern and Redis, revocation is instant:

The same model works for admin-initiated revocation: delete the Redis key server-side and the user is locked out immediately. For a terminated employee or a compromised account, the revocation window is measured in milliseconds, not minutes.

Full architecture

Internet
    │
    ▼
[Caddy :80/443]
    │
    ├── /auth/*         → [Keycloak :8080] → Postgres
    │
    ├── /session-api/*  → [session-service :8000] → [Redis :6379]
    │                          (JWT + refresh token, per-session, TTL'd)
    │
    ├── /gateway-demo/*  ┐
    │  /demo-api/*       ├── [APISIX :9080]  ← real JWKS verification
    │  /todo-api/*       │        │
    └── /sidecar-demo/*  ┘        ├── [OPA :8181]              ← gateway pattern
                                  ├── [Demo API :3000] ← [OPA sidecar]  ← sidecar pattern
                                  └── [Todo API :3001] ← [OPA sidecar]  ← sidecar pattern

    └── /*              → [Demo UI]  ← Astro static site

Tradeoffs and when to use this pattern

Enterprise IDP federation

In the demo, Keycloak is both the IdP and the SP. In a real enterprise deployment, your company's existing IDP becomes the upstream. Keycloak federates to it via OIDC or SAML, enriches the token with additional claims (user_tier, department, region), and issues the JWT that session-service stores.

Nothing downstream changes. session-service doesn't care which IdP issued the JWT — it only talks to Keycloak. OPA evaluates the claims. Your applications get the same resolved user context regardless of whether the user authenticated with a local Keycloak account, their corporate SSO, or a federated external IdP.