Single sliding session cookie¶
Split out of #2934, where the prod log audit and the scored options live. Decision record: ADR-020, which amends ADR-012's "optional refresh tokens" mitigation.
Review decisions of 2026-09-25: renewals are audited; GET /session
answers 200 with user: null for anonymous callers; the login page stays;
settings keep their names; no compatibility window: the maintainer
preferred to experience the cut-over on dev and stage rather than carry a
two-week dual path. Soak on dev, then stage, for several days before prod.
Why¶
Every anonymous page load was GET /v1/session 401 then POST /v1/session
401: the SPA cannot see the httponly cookies, so it asked, got a 401, and
the ky retry hook tried a refresh that also 401'd. Every returning user
after 8 h idle paid the same two round trips before the app rendered.
Both cookies were stateless JWTs signed with the same key with no revocation table (ADR-012 lists a JTI denylist as "future | optional"). A refresh token normally buys revocation; ours bought only the client-side dance. The 24 h bound on a session came from the refresh cookie's lifetime, and that bound is the one thing kept.
What shipped¶
Backend¶
One httponly cookie, auth_token (name unchanged). Claims: sub, email,
institutional_id, provider, type: access, plus:
exp= now +ACCESS_TOKEN_EXPIRE_MINUTES(2880), the idle window. The setting keeps its name; the comment inconfig.pysays what it now means.auth_time(OIDC standard claim) = the login instant, set once by/auth/callbackand/auth/login-test, carried unchanged through every renewal.REFRESH_TOKEN_EXPIRE_HOURS(168) keeps its name and is the hard cap onauth_time.
app/core/security.py:
issue_session_cookie(response, *, sub, email, institutional_id, provider, auth_time)mints the cookie withexp = min(now + idle, auth_time + cap).session_needs_renewal(payload, now): past half the idle window and a new cookie would end later than the current one. A token withoutauth_timepredates the change and is never renewed.get_optional_user(request, response, background_tasks, db, auth_token): no cookie →None; a cookie that fails validation → 401 (a refused credential is not "anonymous"); otherwise the detached user, and when renewal is due the cookie is re-issued on this response and two background tasks are queued, each with its own DB session:audit_session_renewal(app/tasks/session_tasks.py, one "Session renewed" audit row,audit_failuremarker on error) andtrigger_role_sync_for_user(same cadencePOST /sessionused to give it, plan 2539).get_current_useris nowget_optional_user+ 401 whenNone.get_jwt_from_cookieis gone.decode_jwtcatches everyJoseError, not three of them: before, analg=nonetoken on a protected route was a 500 that only the session route's broadexceptused to hide.
app/api/v1/auth.py:
GET /session→ 200 always for a valid or absent cookie;user: null(dropped from the JSON byresponse_model_exclude_none), emptyunitsandconfigured_yearswhen anonymous. The route no longer decodes the cookie itself: it depends onget_optional_user, so the bootstrap call renews a session past half-life like any other request.POST /sessiondeleted, withcreate_refresh_token,TOKEN_TYPE_REFRESHand the refresh cookie.DELETE /sessionclears one cookie.request_origin.AUTH_COOKIE_NAMESno longer listsrefresh_token.
Frontend¶
http.ts:retry: 0, nobeforeRetry, noAPI_REFRESH_URL, noisRefresh. The 401 branch keeps one exemption: the bootstrap GET.auth.tsbootstrap(): one request; 200 withoutuseror a 401 means anonymous; anything else propagates to the guard instead of being read as "logged out".SessionPayload.useris optional.openapi.d.tsregenerated from the app (SessionRead.usernullable,POST /sessiongone). The committed snapshot had drifted, so the diff carries other endpoints' doc changes too.
Behaviour change: session length¶
The old pair was not "8 h idle, 24 h cap". Every POST /session re-minted
both cookies, so the refresh cookie got a fresh 24 h each time the 8 h
access token lapsed. In practice a user stayed logged in indefinitely as
long as they came back within 24 h, with no cap at all.
With the values every environment runs today (480 min / 24 h):
| user | before | after |
|---|---|---|
| works 9:00–18:00, back next morning (15 h idle) | silently continued | login page |
| active all day, every day | never logged out | logged out 24 h after login |
| idle more than 24 h | login page | login page |
Two ways to go, both config-only:
- Keep the new shape (8 h idle, 24 h cap): a morning login per day, Entra SSO usually makes it one silent redirect.
- Match the old UX:
ACCESS_TOKEN_EXPIRE_MINUTES=1440(24 h idle, renewed after 12 h), and either keep a cap (REFRESH_TOKEN_EXPIRE_HOURS= 168 for one week) or accept no practical cap. Renewal audit rows drop to about one per user per 12 h of activity.
Decided 2026-09-25, after dev testing: 2880 min idle / 168 h cap,
set in the dev, stage and prod overlays (openshift-app-config#73) and as
the defaults in config.py, helm/values.yaml and .env.example. 480 / 24
had brought back the complaints the old rolling refresh was set up to fix:
a login every morning, and a lost save after 8 h idle or at hour 24. 48 h
idle renews after 24 h, so anyone back within 24 h stays logged in, a hard
guarantee the old logic only gave for about 16 h. 1440 min was rejected:
it renews only after 12 h, so a 15 h overnight gap could still log out. A
week's cap means at most one login a week.
Verification done before review¶
- Rollout matrix replayed against both code versions: six cookie states on the dev and this branch's backend, and the real dev and new frontends in Playwright against the other backend's answers. Every combination either works or ends on the login page; none errors.
- Renewal watched locally at a 1-minute idle window (fires after 30 s), in Chromium and Safari. Real Entra login checked.
Renewal side effects¶
- Every response shape carries the cookie. FastAPI merges a
dependency's headers only into plain-data returns, so the renewed
Set-Cookieis parked onrequest.stateandSessionRenewalMiddleware(app/core/session_renewal.py, raw ASGI, outermost) appends it at response start: 304s, downloads, SSE streams and redirects included. - Concurrent renewals. A page load fans out several requests with the
same past-half-life cookie; each re-issues it (harmless, stateless) and
each writes one "Session renewed" row. Accepted: a handful of rows per
user per renewal window, grouped when reading by
renewed_expin the snapshot, theexpof the cookie they replaced. Revisit if the audit table volume says otherwise.
Rollout¶
Users holding the old cookie pair at deploy time: auth_token still
validates (same claims minus auth_time) but is not renewed; it lives out
its remaining idle window (8 h at most) and the user logs in once, which
their access token would have required anyway. The stale refresh_token
is ignored and expires on its own within 24 h.
An old frontend bundle still open in a tab keeps working while its cookie is valid. When anonymous it gets a 200 it reads as "no user" and shows the login page; on an expired cookie its refresh attempt hits a 405 and it lands on the login page as well. Nobody is stuck, but there is no dual path: this is the accepted cost of a single step.
Tests¶
Backend (tests/unit/v1/test_unit_auth.py, tests/integration/v1/test_auth*.py,
tests/unit/core/test_get_current_user_releases_connection.py):
- anonymous
GET /session→ 200, nouser, noSet-Cookie - token younger than half-life → no
Set-Cookie - token past half-life →
Set-Cookie auth_token, sameauth_time, laterexp, oneaudit_session_renewalcall - token at the hard cap → 200, no
Set-Cookie - token without
auth_time→ 200, never renewed - a
type: refreshJWT presented asauth_token→ 401 alg=noneand wrong-alg tokens → 401 through the dependency- callback sets one cookie; logout clears one; the end-to-end flow ends on an anonymous 200
Frontend (frontend/tests/unit/session-bootstrap.spec.ts, Playwright CT):
- 200 without
user→ anonymous, exactly one GET - 401 → anonymous, exactly one GET, no refresh
- a payload with
userhydrates the store - a 500 is an error, not a logged-out user
Verification¶
uv run pytest tests/unit/v1/test_unit_auth.py tests/integration/v1/test_auth.py tests/integration/v1/test_auth_security.py tests/unit/core/test_get_current_user_releases_connection.pynpx playwright test -c playwright-ct.config.ts tests/unit/session-bootstrap.spec.ts- dev, then stage, for several days each: log in, work past the 4 h renewal point, confirm no logout and one "Session renewed" audit row; leave a tab idle past 8 h and confirm the login page, not an error
- after prod:
scripts/loki-dump.sh prodfor a day; expect zeroPOST /v1/sessionand a 401 on/v1/sessiononly for expired cookies