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.