fix(auth): align cookie lifetimes with session and refresh token boundaries

[ralf157]

Description & motivation 💭

Fixes two bugs in auth session and cookie handling:

1. maxSessionDuration not configurable in Docker deployments (#3223)
The field existed in the config struct but was missing from docker.yaml, making it impossible to enforce session expiry via environment variable. Adds TEMPORAL_MAX_SESSION_DURATION (default 2m) and aligns user* cookie MaxAge to min(60s, remaining session time) so cookies never outlive the session boundary.

2. Refresh cookie lifetime incorrectly derived from access token expiry (#3210)
oauth2.Token.Expiry is populated from expires_in in the token response, which per RFC 6749 5.1 and OIDC Core 3.2.2.5 represents the access token lifetime — not the refresh token's. This caused the refresh cookie to expire alongside the access token, making token refresh fail with 401 (confirmed on Keycloak).

The refresh cookie MaxAge is now derived via a priority chain:

1. JWT exp claim decoded from the refresh token payload — covers Keycloak and other JWT-issuing IdPs automatically
2. refreshTokenDuration configured per provider (TEMPORAL_AUTH_REFRESH_TOKEN_DURATION) — covers opaque tokens
3. 7-day default when neither is available

Design Considerations 🎨

• refreshTokenDuration is placed on AuthProvider (not Auth) since refresh token lifetime is an IdP-specific characteristic
• JWT exp is decoded without signature verification — only used for cookie lifetime, not for trust decisions
• Config value acts as an explicit override for operators who know their IdP's refresh token lifetime (e.g. opaque token issuers)

Testing 🧪

How was this tested 👻

• Unit tests added
• E2E tests added
• Manual testing

E2E test suites

Mock OIDC stack (tests/e2e-auth/, docker-compose.e2e-auth.yaml) — short TTLs: access=5s, refresh=30s, session=15s. Covers code paths unique to the mock (opaque token fallback, session timing):

Spec	Assertions
refresh-token-duration.spec.ts	JWT exp takes priority over refreshTokenDuration config value
session-expiry.spec.ts	Refresh succeeds at 6s (access token expired, session alive); user* MaxAge decreases after refresh; refresh fails at 16s (session expired)

Real Keycloak stack (tests/e2e-keycloak/, docker-compose.e2e-keycloak.yaml) — Keycloak 26 with realm import, access=5s, ssoSession=30s, maxSession=25s:

Spec	Assertions
login-cookies.spec.ts	refresh MaxAge from Keycloak JWT exp (~30s, no config fallback); user* MaxAge ≤ 25s; session_start MaxAge = 25s; HttpOnly flags

Run locally:

# Mock OIDC (9 tests)
docker compose -f docker-compose.e2e-auth.yaml up -d
pnpm test:e2e:auth

# Real Keycloak (5 tests)
docker compose -f docker-compose.e2e-keycloak.yaml up -d
pnpm test:e2e:keycloak

Session expiry:

1. Set TEMPORAL_MAX_SESSION_DURATION=30s in your Docker environment
2. Log in to the Temporal UI
3. Wait 30 seconds — verify you are redirected to re-login with no stale cookie window

Refresh token lifetime (Keycloak or JWT-issuing IdP):

1. Configure auth with a Keycloak provider, no refreshTokenDuration set
2. Log in and inspect the refresh cookie MaxAge in browser devtools
3. Verify it matches the refresh token's exp claim, not the access token lifetime

Refresh token lifetime (opaque token IdP):

1. Set TEMPORAL_AUTH_REFRESH_TOKEN_DURATION=24h for your provider
2. Log in and verify the refresh cookie MaxAge is 86400 seconds

Checklists

Draft Checklist

• maxSessionDuration exposed in docker.yaml
• refreshTokenDuration added to AuthProvider config
• jwtExp helper implemented and unit tested
• Priority chain implemented and all cases tested
• E2E test suite implemented (9 tests, all passing)
• Real Keycloak E2E suite added (5 tests via docker-compose.e2e-keycloak.yaml)
• AUTHENTICATION.md updated

Merge Checklist

• Tested against a live Keycloak instance (Keycloak 26 E2E suite)

Issue(s) closed

Closes #3223
Closes #3210

Docs

AUTHENTICATION.md updated to document TEMPORAL_MAX_SESSION_DURATION and TEMPORAL_AUTH_REFRESH_TOKEN_DURATION environment variables, the refreshTokenDuration provider config field, and the refresh token lifetime priority chain including a troubleshooting section for opaque vs JWT refresh tokens.

[vercel]

@ralf157 is attempting to deploy a commit to the Temporal Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[alexander-maksymiw-snke]

Any update on this? Would be great if this bug could be fixed / bugfix merged, as it forces us to relogin to the UI every hour when used together with Entra ID (access token lifetime ~1hour, refresh token several days)

[Etibru]

Any update ?

[tskibinski]

I've been struggling with this lately as well and I'm eagerly awaiting the release.

[rossnelson]

Thanks for this — the diagnosis is right on both counts, and I confirmed both bugs are still present on main.

Since this was opened from a fork's main branch it can't be updated in place, and main has moved a fair bit since March (SetUser has gained a secure parameter). I've rebuilt it on current main as #3940, carrying over your analysis and credit.

Two changes worth flagging:

• TEMPORAL_MAX_SESSION_DURATION now defaults to unset rather than 2m. The 2m looks to have come from with-auth.yaml, where it's a deliberately short value for exercising refresh locally. As a docker.yaml default it would have started logging every Docker deployment out every two minutes. There's a test pinning it now.
• The new E2E infrastructure isn't carried over. The two docker-compose stacks and the Keycloak realm are a lot of surface next to the repo's existing tests/e2e + utilities/oidc-server setup, and weren't wired into CI. Instead fix(auth): align cookie lifetimes with session and refresh token boundaries #3940 drives the real /auth/refresh handler against a real token endpoint over HTTP in a Go test, which covers both bugs and runs in the existing CI job.

The one thing I can't reproduce is your live Keycloak run — if you're able to check #3940 against your Keycloak 26 instance, that would be much appreciated.