Session Management in Keycloak: From Refresh to Idle Timeouts

Last updated: June 2026

How does session management work in Keycloak?

Keycloak manages sessions with three tokens (access, refresh, and ID) and a set of timeouts you tune in the Admin Console under Realm Settings -> Tokens. The two that matter most are SSO Session Idle (default 30 minutes, logs out inactive users) and Access Token Lifespan (default 5 minutes, limits exposure if a token leaks). Get these right and you balance security against how often users have to re-authenticate; get them wrong and you either frustrate users or leave sessions open too long.

This guide explains the token model, every timeout setting, and the configuration that keeps sessions both secure and usable.

Key Takeaways

• Session types: Keycloak tracks user sessions, client sessions, and authentication sessions to manage state across applications.
• Token types: access tokens (short-term authorization, ~5 min), refresh tokens (session continuity, tied to SSO idle), and ID tokens (user identity) work together.
• Timeout settings: the levers are SSO Session Idle (30 min), SSO Session Max (10 to 24 hours), and Access Token Lifespan (5 to 15 min).
• Advanced controls: token revocation, brute-force protection, and multi-level access control harden sessions further.
• Where to configure: Admin Console -> Realm Settings -> Tokens, with per-client overrides available.

How do tokens and session lifecycles work in Keycloak?

Keycloak combines a structured session architecture with token management to secure sessions while keeping authentication smooth. Understanding how the token types and timeouts interact is what lets you tune flows without breaking either security or user experience.

What are the token types in Keycloak?

Keycloak relies on three token types, each with a specific job:

• Access tokens: authenticate and authorize API requests between applications and services, carrying the permissions and user details needed for secure communication. The default 5-minute expiry limits misuse if a token is intercepted.
• Refresh tokens: provide session continuity, letting applications request new access tokens without forcing the user to log in again. They align with the SSO Session Idle window, balancing convenience and security.
• ID tokens: an OpenID Connect construct that carries user identity details such as name and email, confirming who the user is after authentication (as opposed to authorizing requests).

Together they form a layered system: access tokens handle immediate authorization with minimal exposure, while refresh tokens keep sessions alive without weakening it. For the deeper mechanics, see our guide on the JWT token lifecycle.

How do session lifecycles work?

When a user logs in, Keycloak issues all three token types at once and renews them in the background, so users do not reauthenticate manually. Access-token validity is always bounded by the refresh token’s lifespan, and the refresh token is bounded by the overall session duration, which preserves session integrity.

Keycloak adds a built-in two-minute buffer to timeouts (a 30-minute setting effectively expires at 32 minutes) to avoid cutting off active users mid-action. Realm-level timeouts take priority over client-specific ones, keeping policy consistent, though individual client idle timeouts can affect token expiration independently.

Keycloak also supports token revocation through session-state management: when a user logs out or an admin invalidates a session, all associated tokens are revoked immediately, so a compromised session cannot keep working on cached tokens. Since version 4.8.1 you can set per-client access-token lifespans in Advanced Settings, and since 10.0.0 you can override session idle and max timeouts per client. For revoking one session without ending the rest, see revoke a single Keycloak session, not all.

How do you configure session and token timeouts in Keycloak?

Configure them in the Admin Console under Realm Settings -> Tokens, where each setting controls a different part of the session lifecycle. The main categories are SSO Session Idle, SSO Session Max, and the token lifespan controls.

What are the main timeout settings?

• SSO Session Idle: how long a user can be inactive before the session is invalidated. 30 minutes is a common balance, applied across all applications in the realm session.
• SSO Session Max: the maximum session duration regardless of activity. 10 to 24 hours is typical, depending on risk tolerance.
• Access Token Lifespan: the short-term authorization window, default 5 minutes; many teams use 15 minutes or less to limit exposure on compromise.
• Client Session Idle and Client Session Max: per-application overrides. Keep these shorter than the realm-wide timeouts to maintain consistent policy.

How do you change timeout values?

Open Realm Settings -> Tokens and adjust the values. Two rules keep the configuration safe: ensure the Access Token Lifespan is equal to or shorter than the SSO Session Idle timeout, and set Refresh Token Max Reuse to 0 (combined with Revoke Refresh Token for OIDC clients) to block replay attacks.

Setting	Recommended value	Security impact
SSO Session Idle	30 minutes	Prevents inactive sessions from staying active
SSO Session Max	10 to 24 hours	Limits session duration regardless of activity
Access Token Lifespan	15 minutes or less	Reduces the risk of token compromise
Refresh Token Max Reuse	0	Blocks token replay attacks

For the full walkthrough of each field, see our Keycloak session timeout configuration guide, and for rotation specifics, the refresh token rotation guide.

How do timeout settings affect users?

Timeouts shape user experience as much as security. Shorter timeouts are safer but force more frequent re-authentication; longer ones are convenient but widen the window if a session is compromised. A 15-minute access-token lifespan is a common middle ground that avoids both constant refreshes and excessive exposure.

The SSO Session Idle timeout spans all applications in the realm: as long as the user is active in any one app, the session stays valid, but a true idle period (a lunch break) triggers re-authentication. Client session timeouts apply per application, so a client session can expire while the realm session continues, requiring re-auth only for that app. That separation lets you set stricter policies for sensitive applications without disrupting the rest.

What are Keycloak session management best practices?

Effective session management is a deliberate balance of security and convenience. The practices below build on the configuration above.

How do you find the right security balance?

Tailor timeouts to your actual workflows. Too short and users tire of re-authenticating; too long and you widen the risk window. High-security environments warrant shorter sessions; lower-sensitivity systems can be more lenient. Align the values with your organization’s risk profile rather than copying defaults blindly.

Which advanced session features should you use?

• Multi-level access control: check permissions both in Keycloak and at the application level. Use roles (Admin, Manager, User) for broad groups and attributes for fine-grained control (for example, restricting finance reports to the Finance department). This keeps access policies organized and audits simple. See RBAC.
• Brute-force protection: Keycloak tracks failed logins and temporarily locks accounts after repeated failures, blocking systematic password guessing.

How do you monitor active sessions?

Administrators can view and manage sessions across the realm, and users can see their own sessions in account management. Regular review surfaces anomalies (logins from unexpected locations, odd hours, multiple concurrent sessions) that may signal a threat. Pair automated idle-logout policies with strong password requirements, and keep Keycloak patched, since releases often improve session handling. Ship login and admin events to your SIEM via Keycloak event logging for an audit trail.

Security feature	Purpose	Implementation
Token revocation	Prevents replay attacks	Set Refresh Token Max Reuse to 0
Brute-force protection	Blocks systematic password guessing	Lock accounts after repeated failed logins
Multi-level access control	Creates multiple security barriers	Check permissions at both Keycloak and app level
Automated logout	Prevents abandoned sessions	Configure idle timeout with session cleanup

Summary

Keycloak session management comes down to a clear token hierarchy (access tokens expiring before refresh tokens), timeout durations matched to your risk profile (SSO Session Idle ~30 min, Access Token Lifespan 15 min or less), and ongoing monitoring with token revocation and brute-force protection. Configure it under Realm Settings -> Tokens, override per client where sensitivity demands, and review sessions regularly.

Frequently asked questions

What is the default session timeout in Keycloak?

By default, SSO Session Idle is 30 minutes (inactive logout) and the Access Token Lifespan is 5 minutes. SSO Session Max, the hard cap regardless of activity, defaults to 10 hours. Keycloak also adds a ~2-minute buffer, so a 30-minute idle setting effectively expires at 32 minutes. Tune all three under Realm Settings -> Tokens.

What are best practices for Keycloak session timeouts?

Keep the Access Token Lifespan short (15 minutes or less) to limit exposure, set SSO Session Idle around 30 minutes and SSO Session Max between 10 and 24 hours for usability, and set Refresh Token Max Reuse to 0 with Revoke Refresh Token enabled to block replay. Use shorter per-client timeouts for sensitive applications.

How do I revoke or end a Keycloak session?

Logging a user out or invalidating their session from the Admin Console revokes all associated tokens immediately, so cached tokens stop working. To end one session without affecting the user’s others, target that specific session, covered in our guide on revoking a single Keycloak session.

How can I monitor active sessions in Keycloak?

Admins can view and manage all realm sessions from the Admin Console, and users can review their own in account management. For security, ship login and admin events to a SIEM, watch for anomalies like unexpected locations or concurrent sessions, and enforce automated idle logout on shared devices.

Running Keycloak yourself means owning all of this tuning, patching, and monitoring. Skycloak provides production-ready managed Keycloak hosting with sane session defaults, automated patching, and a 99.995% uptime SLA, so your team configures policy instead of maintaining infrastructure. Start with the getting started guide.