Token lifespans and session windows
How long an SHC login stays good, why the numbers are what they are, and what they cost. One access token lifespan, three session windows, how they interact, and one consequence that is not obvious from any of them.
keycloak.access_token_lifespan: 14400 s (4 h)keycloak.sso_session_idle_timeout: unsetkeycloak.sso_session_max_lifespan: unsetkeycloak.offline_session_idle_timeout: unset
The default: 4 hours
Section titled “The default: 4 hours”SHC seeds accessTokenLifespan = 14400 (4 hours) on every realm it
provisions (the master realm and every tenant realm) and re-asserts it each
time the leader renders the realms. Keycloak’s own default is 300 s (5 minutes).
The reason is not API convenience. On a gated app the access token lifetime is how often the gate goes back to Keycloak. The forward-auth gate keeps the access token and a refresh token in its own memory, hands the browser an opaque session cookie, and renews with the refresh token only when the access token is about to expire. The cookie lives for the shorter of the gate’s 8 h session ceiling and the refresh token’s lifetime, and never less than the access token’s. Before the gate held a refresh token, the cookie was the access token itself, so at Keycloak’s 300 s default every gated app bounced the browser through a full OIDC redirect round-trip every five minutes, per app.
4 hours keeps the gate’s trips to Keycloak to a couple in a working day.
Overriding it
Section titled “Overriding it”shc config set keycloak.access_token_lifespan 3600The key resolves through the normal scope cascade, so it can be set globally
or narrowed per tenant. 0 or null means “the SHC default” (4 h), never a
zero-second token. The leader writes the new value onto every realm on its
next reconcile pass, without a restart; see applying it to existing
realms.
Note this is the realm default. Service clients minted by
shc auth create-service-client carry their own per-client
access.token.lifespan (default 3600 s, max 86400 s, set with
--token-lifespan) and are unaffected by this key.
Session windows
Section titled “Session windows”Keycloak realms also carry ssoSessionIdleTimeout (ships at 1800 s, 30 min)
and ssoSessionMaxLifespan (36000 s, 10 h). SHC asserts neither by
default. Set keycloak.sso_session_idle_timeout or
keycloak.sso_session_max_lifespan and the provisioner writes it onto master
and every tenant realm on each reconcile; leave a key unset and the realm
keeps whatever it has.
The idle window is what decides whether a renewal works. A regular (not
offline) refresh token is only good while its SSO session is alive, and the
session dies after ssoSessionIdleTimeout without a Keycloak round trip, or at
ssoSessionMaxLifespan however active it is. Who holds one:
- Gated apps: the forward-auth gate renews once, as the 4 h access token expires. Inside those 4 h it never talks to Keycloak, so using the app does not keep the SSO session alive. With the 30-minute default the session has idled out by the renewal, the renewal fails, and the user signs in again about every 4 h.
- Apps doing their own OIDC (Nextcloud, Matrix and similar native-SSO apps): the same, on the same 4 h clock.
shc auth login(CLI): unaffected. The device flow requestsoffline_access, so its refresh token lives on the offline clocks.
So a renewal at the 4 h mark needs an idle window of at least the access
token lifespan, and the max caps the idle window: an idle timeout above
ssoSessionMaxLifespan is cut short at the max. For a session that lasts about
a day idle and two weeks at most:
shc config set keycloak.sso_session_idle_timeout 86400shc config set keycloak.sso_session_max_lifespan 1209600shc config set refuses a max below the idle timeout already set
(X400068CFGMIN), so raise the max first when you raise both by hand. The
shc_config resource writes a document’s keys in sorted order, idle before
max, so one apply that raises or lowers both works.
Both keys are live class: the leader writes them onto every realm on its next
reconcile pass. No restart.
The trade: a longer idle window keeps an unattended browser usable for that much longer, and a longer max lets an active user ride silent renewals that long without a password prompt. That is why neither is defaulted: it is a security posture decision, not a derived value.
Offline sessions
Section titled “Offline sessions”A refresh token issued for offline_access lives on its own idle clock,
offlineSessionIdleTimeout (ships at 2592000 s, 30 days), and
keycloak.offline_session_idle_timeout sets it. Keycloak ships the offline
max lifespan switched off, so an offline session ends only by going unused,
and SHC has no key for it.
Revocation lag
Section titled “Revocation lag”Disabling a Keycloak user does not immediately lock them out. Their existing token keeps working until it expires, now up to 4 hours.
This is a direct, proportional consequence of the default: the window grew from ~5 minutes to 4 hours, a 48× increase.
Why: the daemon verifies bearers offline against a cached JWKS. It checks
the signature, exp/nbf, audience, and issuer, and it reads the user’s
roles out of the token’s own claims. It does not look the user up. There
is no introspection call, no revocation list, no session-liveness check, and
no back-channel logout consumer. The userinfo endpoint (the one call that
would notice a disabled user) is only reached as a fallback when JWKS
verification fails, which in a healthy daemon never happens.
The forward-auth gate calls the daemon for a verdict on every single request, so it is tempting to assume that shortens the window. It does not. That per-request verdict runs the same offline validation, so it re-checks the token, not the user.
What the per-request verdict does shorten:
| Change | Time to take effect |
|---|---|
| User disabled / deleted | token exp, up to 4 h |
| User’s role grants changed | token exp, up to 4 h (roles ride in the token) |
| Authorization policy changed (role → permission map) | 60 s (keycloak.policy_cache_ttl), up to 15 min if served stale |
| Host → deployment mapping changed | next request |
Revoking access immediately
Section titled “Revoking access immediately”Do not wait out exp. Push a realm-wide not-before, which invalidates every
token issued before now:
docker compose -p master_default_keycloak exec -T keycloak sh -c ' KC=http://localhost:8080${KC_HTTP_RELATIVE_PATH%/} TOKEN=$(curl -sf "$KC/realms/master/protocol/openid-connect/token" \ -d client_id=admin-cli -d grant_type=password \ -d "username=$KEYCLOAK_ADMIN" \ --data-urlencode "password=$KEYCLOAK_ADMIN_PASSWORD" \ | sed -n "s/.*\"access_token\":\"\([^\"]*\)\".*/\1/p") curl -s -o /dev/null -w "%{http_code}\n" \ -X POST "$KC/admin/realms/<realm>/push-revocation" \ -H "Authorization: Bearer $TOKEN"'This logs out everyone in the realm, so it is an incident tool, not
routine offboarding. For a single user, disable the account and terminate
their sessions (/admin/realms/<realm>/users/<id>/logout), but note that
neither step invalidates an already-issued access token held by the gate, so
the 4-hour ceiling still applies to that user’s existing browser cookie.
If a shorter revocation window matters more to you than the redirect traffic,
lower keycloak.access_token_lifespan. That is the only lever that moves this
number.
Applying a change to existing realms
Section titled “Applying a change to existing realms”The leader renders every realm once after shcd starts and again on the next
reconcile pass after any realm setting changes, so a shc config set on one of
the keycloak.* realm keys reaches existing realms on its own, usually within a
minute or two. The journal says reconcile.keycloak realm settings changed, rendering the realm again for each realm it renders for that reason.
To apply it immediately without waiting for a reconcile, PUT the realm
directly. Run this once per realm (including master):
docker compose -p master_default_keycloak exec -T keycloak sh -c ' KC=http://localhost:8080${KC_HTTP_RELATIVE_PATH%/} TOKEN=$(curl -sf "$KC/realms/master/protocol/openid-connect/token" \ -d client_id=admin-cli -d grant_type=password \ -d "username=$KEYCLOAK_ADMIN" \ --data-urlencode "password=$KEYCLOAK_ADMIN_PASSWORD" \ | sed -n "s/.*\"access_token\":\"\([^\"]*\)\".*/\1/p") for REALM in master corp; do curl -s -o /dev/null -w "$REALM %{http_code}\n" -X PUT "$KC/admin/realms/$REALM" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"realm\":\"$REALM\",\"accessTokenLifespan\":14400}" done'Replace master corp with your realm list (shc tenant ls names the tenant
realms). A 204 per realm is success; the PUT is idempotent, so re-running it
converges rather than erroring.
The body is a partial realm representation on purpose: Keycloak applies
only the fields present, so this leaves ssoSessionIdleTimeout,
ssoSessionMaxLifespan, and every other realm setting untouched. Add
,"ssoSessionIdleTimeout":86400,"ssoSessionMaxLifespan":1209600 to the body
if you have also decided to move the session windows. The provisioner sends
the same fields for the keys you set.
Existing sessions are not retroactively extended: a token already issued
keeps its original exp, so the new lifespan applies from each user’s next
login.
See also
Section titled “See also”- config-keys.md: the full key reference
shc auth login: device flow,offline_accessshc auth create-service-client: per-client--token-lifespanfor automation