Skip to content
SHC Docs

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.

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.

Terminal window
shc config set keycloak.access_token_lifespan 3600

The 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.

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 requests offline_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:

Terminal window
shc config set keycloak.sso_session_idle_timeout 86400
shc config set keycloak.sso_session_max_lifespan 1209600

shc 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.

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.

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:

ChangeTime to take effect
User disabled / deletedtoken exp, up to 4 h
User’s role grants changedtoken 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 changednext request

Do not wait out exp. Push a realm-wide not-before, which invalidates every token issued before now:

Terminal window
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.

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):

Terminal window
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.