Token Lifespans

Why lifespans matter

Every token Keycloak issues has a lifespan. Getting these right is a balance between user experience (fewer re-logins) and security (limiting damage if a token leaks). A token that never expires is dangerous — if it leaks, an attacker has indefinite access. A token that expires every 30 seconds is secure but unusable.

Token lifespans reference

Access token lifespan

Default: 5 minutes (300 seconds). Short by design — if an access token leaks, the window of misuse is small. The exp claim in the token reflects this value. Your API must reject any token where exp is in the past.

A 5-minute access token means an attacker who intercepts it has at most 5 minutes to use it before it is worthless. Combine this with HTTPS-only transport and the risk is minimal.

Refresh token lifespan

The refresh token lifespan is controlled by two session settings:

• SSO Session Idle (default: 30 minutes) — if the user is inactive for this long, the session (and refresh token) expires.
• SSO Session Max (default: 10 hours) — the hard upper limit on how long a session can last, regardless of activity.

The client can silently obtain new access tokens using the refresh token as long as the session is within these bounds.

Offline token

An offline refresh token is a special refresh token that survives server restarts and persists beyond the normal SSO session expiry. It requires the offline_access scope to be requested at login. Offline tokens are controlled by separate settings:

• Offline Session Idle — how long an inactive offline session persists.
• Offline Session Max — the hard upper limit on offline session lifetime.

Use offline tokens for mobile apps or long-running background services that need to stay authenticated without a user present.

Where to configure lifespans

There are two places to set token lifespans in Keycloak:

Realm-level (applies to all clients in the realm):

• Realm settings → Tokens tab — access token lifespan and SSO session settings.
• Realm settings → Sessions tab — offline session settings.

Client-level override (applies to one client only):

• Individual client → Advanced tab → Token Lifespan section.
• Client settings override the realm defaults for that client only. Useful when one client needs a longer or shorter lifespan than the rest.

Configuring lifespans at the realm level

1. In the admin console, click Realm settings in the left sidebar.
2. Click the Tokens tab.
3. Adjust Access Token Lifespan (recommended: 1–5 minutes for most apps; 5–15 minutes for SPAs with silent refresh).
4. Adjust SSO Session Idle — how long before an inactive session expires (default 30 minutes).
5. Adjust SSO Session Max — the hard upper limit on session length (default 10 hours).
6. Click Save.

Overriding the access token lifespan for a single client

1. In the admin console, click Clients and select your client.
2. Click the Advanced tab.
3. Scroll to the Token Lifespan section.
4. Set Access Token Lifespan to override the realm default for this client only.
5. Click Save.

Inspecting a token’s expiry

You can decode a token on the command line to check its exp and iat claims. The difference exp - iat tells you the configured lifespan in seconds.

jwt_payload=$(echo "YOUR_ACCESS_TOKEN" | cut -d '.' -f2 | base64 -d 2>/dev/null); echo $jwt_payload | python3 -m json.tool

Copy decode command ⧉

Replace YOUR_ACCESS_TOKEN with an actual token. The exp minus iat value shows you the configured access token lifespan in seconds.

🔐 Short access tokens + refresh tokens = best practice

Keep access tokens short-lived (1–5 minutes) and rely on refresh tokens to maintain sessions. A short access token limits the damage window if it is intercepted or leaked — it expires before an attacker can make significant use of it.

Trade-offs

Option	Benefit	Cost
Short-lived access token (1–5 minutes)	Limits the window a stolen token can be used in — it expires quickly before an attacker gets much value from it	Requires refreshing more often, adding round-trips to the token endpoint and load on Keycloak
Long-lived access token (30–60+ minutes)	Fewer client-side refreshes, lowering client latency and load on the token endpoint	If it leaks, an attacker can use it for much longer, because a stateless JWT access token cannot be revoked mid-flight — it has to expire on its own
Short refresh token / SSO session idle timeout	Forces a session to die quickly when the user is inactive, reducing risk from a refresh token that leaks with an abandoned device	Users must log in again more often after being away, hurting UX for apps used in short bursts
Offline token (a refresh token that survives a server restart)	Good for background jobs or mobile apps that need to keep working with no user around to log in again	Naturally long-lived; if it leaks or isn’t revoked when no longer needed, an attacker can use it for a long time

Common mistakes

• Setting the access token lifespan to an hour or more “for convenience” — the longer the lifespan, the wider the window a leaked token can be used in, because a JWT access token can’t be revoked mid-flight. Keep it short (single-digit to low double-digit minutes) and rely on the refresh token instead.
• Storing an access or refresh token in localStorage — any JavaScript running on the page can read localStorage; a single XSS gap lets an attacker steal and reuse the token immediately. Use memory or an httpOnly cookie instead.
• Putting frequently changing or sensitive data into a token claim and expecting it to be real-time (e.g. current role, balance, subscription status) — a claim is only a snapshot from when the token was issued and won’t update until the token is refreshed, so a system that trusts these claims directly can silently act on stale data.
• Not setting a reasonable SSO Session Max — letting a session renew indefinitely through refreshes with no hard ceiling keeps a session alive long after it should have died.

Real-world example

Banking apps — commonly set the access-token lifespan very short, around 5 minutes, for applications that need high security, to limit the damage if a token leaks mid-transaction.

Per-device session revocation, as used by major streaming platforms — pairs a short-lived access token with revoking the refresh token for one specific device when a user chooses “sign out this device,” cutting off a session on one TV or phone almost immediately without affecting sessions on other devices.

Where do you configure the default access token lifespan for a realm?

Clients → Advanced tab Realm settings → Tokens tab Users → Sessions tab Client scopes → Settings tab

What does SSO Session Idle control?

How long an access token is valid How long before an inactive SSO session expires How many clients can share a session The maximum number of offline tokens

What is the advantage of a short access token lifespan?

It reduces the number of database queries It forces users to log in more often It limits the misuse window if the token is leaked It makes the token signature stronger

How do you override the access token lifespan for a single client?

In Realm settings → Sessions tab In the client's Advanced tab → Token Lifespan section By adding a protocol mapper By creating a new client scope

Submit

Mark as complete