ADR-020: Single sliding session cookie¶
Status: Accepted (issue #2943, 2026-09-25) Date: 2026-09-24 Deciders: Development Team Amends: ADR-012, mitigation "optional refresh tokens for session continuity"
TL;DR¶
Keep JWT-in-httponly-cookie (ADR-012). Drop the second cookie. The backend renews the one cookie inside the auth dependency when it is past half its idle life, and refuses renewal once the login is older than the hard cap. The SPA never calls a refresh endpoint and never sees a 401 on its session bootstrap.
Context¶
ADR-012 chose stateless JWTs and listed short-lived access tokens plus optional refresh tokens as the expiration strategy. The implementation issued both as stateless JWTs with no revocation store, so the refresh token carries none of the revocation benefit it exists for. What it does carry is a client-driven flow: the SPA cannot see httponly cookies, so on every anonymous page load and every return after idle it sends a session check that 401s and a refresh that 401s or succeeds. Those two 401 lines per login were the trigger (#2934); the round trips and the retry machinery in the HTTP client are the cost.
Decision¶
- One cookie,
auth_token, idle lifetimeACCESS_TOKEN_EXPIRE_MINUTES(2880). - The token carries
auth_time(OIDC claim) set at login. Renewal setsexp = min(now + idle, auth_time + REFRESH_TOKEN_EXPIRE_HOURS); when that is in the past the request is 401 and the user logs in again. Sessions cannot slide forever. - Renewal happens in
get_current_userwhenexp - now < idle / 2, so at most once per 24 h per user, and it is where role sync is triggered. - Every renewal writes an audit row ("Session renewed"), from a background task with its own session, so the trail of who kept a session alive from where is as complete as it is today for refreshes.
GET /v1/sessionreturns 200 withuser: nullfor anonymous callers. "What session do I have" has "none" as a valid answer. 401 keeps its meaning on every other route.- No refresh endpoint, no refresh cookie, no client retry.
- Settings keep their names (
ACCESS_TOKEN_EXPIRE_MINUTESis the idle window,REFRESH_TOKEN_EXPIRE_HOURSthe hard cap); a docstring, not a rename, because a rename touches every env file and ops overlay.
Alternatives considered¶
Keep both cookies, refresh server-side inside GET /session. Removes
the 401 pair but keeps two tokens whose only difference is a type claim.
Half the deletion for the same behaviour.
Readable has_session marker cookie so the SPA skips the bootstrap.
Second source of truth for "logged in" that must expire and clear in step
with the real cookie; still 401s when the marker outlives the session.
SPA-driven OAuth (authorize URL fetched as JSON, code posted back). Removes the two 302s as well, at the price of moving state/PKCE handling to the browser and rewriting every login path. The redirect flow is the one Entra documents.
Consequences¶
Positive: one cookie, one code path in the guard, no auth branches in the HTTP client beyond "401 on a real request → login page", a faster return after idle (no refresh round trip), zero session 401s in the log.
Negative: session length changes. The old refresh endpoint re-minted a
fresh 24 h refresh cookie on every refresh, so a user returning within
24 h stayed logged in with no cap. With 480 min idle and a 24 h cap, an
overnight gap now means a login each morning, and a session ends 24 h
after login whatever the activity. Setting ACCESS_TOKEN_EXPIRE_MINUTES
to 2880 (48 h, renewed after 24 h) with a 168 h cap keeps "back within
24 h, still logged in" and bounds the rest to a week; that is what dev,
stage and prod run (2026-09-25, plan 2943, "Behaviour change").
A cookie that is present but refused (expired after idle,
tampered, retired refresh type) is still a 401 on the session check, so
"every user's first morning load" writes one 401 line. That is a real
event, not the two-line dance of before. Revocation is unchanged from
ADR-012: none before expiry.
Rollout, in one step (maintainer's call, 2026-09-25, no compatibility
window): an auth_token minted before the change validates but is not
renewed (it carries neither auth_time nor iat), so each user logs in
once more within 8 h of the deploy, which their access token would have
required anyway; the stale refresh_token expires within 24 h. An old
frontend bundle left open reads the anonymous 200 as "no user" and shows
the login page; its refresh attempt on an expired cookie meets a 405 and
ends on the login page too.