Before diagrams and architecture, let’s build a precise mental model of what each timer actually measures.

The problem: “how long should a login last?” has two different answers

When a user logs into Keycloak once and then moves between several applications without logging in again, they’re relying on a single, shared SSO session behind the scenes. But “how long should that session last?” isn’t one question — it’s two. Should it last as long as the user keeps using it? And separately, should there be an absolute cutoff no matter how actively it’s being used? Keycloak answers both questions with two independent realm-level settings.

SSO Session Idle, precisely defined

SSO Session Idle is the maximum period of inactivity Keycloak allows before automatically ending the SSO session. Every time the user interacts with Keycloak — logging into another application through SSO, or refreshing a token — this idle timer resets. As long as the user (or an application acting for them) keeps generating activity within the idle window, the session can, in principle, continue indefinitely.

SSO Session Max, precisely defined

SSO Session Max is the absolute maximum lifetime of the SSO session, measured from the moment it was created. Unlike Idle, this timer never resets — no amount of activity extends it. Once this duration elapses, the session ends, full stop, even if the user has been continuously active the entire time.

Why “session” here means more than one login screen

It’s worth being precise about what “session” refers to in this context. When a user authenticates once through Keycloak and then moves between several separate applications without being prompted to log in again, all of that access is happening under one shared SSO session on the server side. Idle and Max don’t apply per application — they apply to that single, shared session, which is exactly why activity in any one connected application can keep the whole thing alive.

Where these settings live in practice

Both values are configured as a duration — commonly expressed in minutes, hours, or days depending on the admin console’s unit selector — under the realm’s Sessions configuration. They apply as the default for every client in that realm unless a specific client has been given its own override, a topic covered in more depth later in this post.

These two timers don’t operate in isolation — they sit inside Keycloak’s broader session model, alongside client-level sessions and token lifespans.

The realm as the configuration home

SSO Session Idle and SSO Session Max are configured at the realm level, under the Sessions tab of realm settings. Every user session created within that realm inherits these values by default, though individual clients can override them for their own client sessions when a specific application needs different behavior.

How the pieces fit together

Picture the User Session as a master ticket for a theme park, and each Client Session as a wristband for a specific ride queue inside the park. The master ticket has its own overall closing time (SSO Session Max) and its own “leave if you haven’t scanned it in a while” rule (SSO Session Idle). Individual ride queues can, in some parks, impose their own stricter rules on top — but they can never let you stay in the park longer than the master ticket allows.

flowchart TD
    RS[Realm Settings] -->|defaults| US[User Session
SSO Session Idle + Max]
    US --> CS1[Client Session A
optional override]
    US --> CS2[Client Session B
optional override]
    US -->|expires when| END{Idle exceeded
OR Max reached}
        

Remember Me as a parallel timer set

Keycloak provides a second, usually longer, pair of Idle and Max values specifically for sessions created via the “Remember Me” option, letting administrators offer a genuinely persistent login experience for users who opt into it, without changing the default, shorter-lived behavior for everyone else.

Session storage and clustering

In a clustered Keycloak deployment, session state — including the creation timestamp and last-activity timestamp that Idle and Max depend on — must be visible consistently across every node handling requests for that user. Keycloak relies on its distributed session cache to keep this state synchronized, which is why the accuracy of these two timers depends not just on their configured values but on the underlying session storage being healthy and correctly replicated across the cluster.

What actually happens inside Keycloak’s session engine as these two timers tick?

Why activity from any client counts

Because the Idle timer lives on the shared User Session rather than on any single Client Session, activity in one application resets the idle clock for every other application sharing that SSO session. A user actively working in one tool keeps their entire single sign-on session alive across every other tool they’re logged into, even ones they haven’t touched recently.

Why the two checks run independently rather than sequentially

It’s tempting to imagine Keycloak checking Idle first and only checking Max if Idle passes, but in practice both conditions are simply two independent facts about the same session, evaluated together whenever a check is needed. There’s no ordering dependency between them — a session can fail the Max check even while comfortably within its Idle window, and vice versa. Thinking of them as two separate, simultaneously-true-or-false conditions rather than a sequence avoids a common source of confusion when reasoning about edge cases.

What triggers an idle or max check

Keycloak doesn’t necessarily run a constant background sweep checking every session every second. Instead, these checks are commonly evaluated at meaningful touchpoints — when a token refresh is attempted, when a new authentication request arrives for a client sharing the session, or during periodic cleanup passes that remove genuinely expired sessions from storage to free up resources.

Let’s trace a realistic scenario across a full working day to see exactly how these two timers interact.

sequenceDiagram
    participant User
    participant KC as Keycloak
    User->>KC: Log in at 9:00 AM
    KC->>KC: Create session
created=9:00, lastActive=9:00
    User->>KC: Active use throughout the morning
    KC->>KC: lastActive keeps updating
    Note over KC: Idle timer never triggers
because user stays active
    Note over KC: Max timer keeps counting
from 9:00 regardless
    User->>KC: Continues working past Max duration
    KC-->>User: Session forcibly ended at Max limit
even though still active
        

Lifecycle stages of a session under both timers

How client sessions inherit and diverge

Each Client Session tracks its own activity for that specific application but is ultimately bound by the overall User Session’s expiry. If a client configures a stricter idle or max override, that client’s session can end earlier than the broader SSO session — but it can never outlive it; once the User Session itself expires, every Client Session tied to it expires as well.

A worked example across the two timers

Suppose a realm is configured with a 30-minute Idle timeout and a 10-hour Max timeout. A user logs in at 9:00 AM and works steadily, refreshing tokens every few minutes, never leaving a 30-minute gap. Under Idle alone, this session could theoretically run forever. But because Max is fixed at 10 hours from creation, the session will end at 7:00 PM regardless of how recently the user was active — even mid-task, if that’s when the clock runs out. This is precisely the scenario Max exists to guarantee: an upper bound that activity alone cannot extend.

Idle and Max don’t operate alone — several neighboring settings shape the full picture of session behavior.

How these settings stack

A note on token lifespan versus session lifespan

It’s easy to conflate “how long is my access token valid” with “how long is my session valid,” but these operate at different layers. An access token’s own lifespan is typically much shorter than either session timer, and expired access tokens are routinely replaced through a refresh — as long as the underlying session is still within both its Idle and Max windows. Once the session itself expires under either rule, no further refresh is possible, and the user must authenticate again from scratch.

It’s worth seeing this two-timer model next to the simpler approaches teams sometimes assume are equivalent.

The two-timer model exists precisely because neither extreme serves every situation well. Idle alone rewards continuous activity with unlimited session length, which can be a genuine risk for sensitive applications. Max alone punishes active users by cutting them off mid-task on a fixed schedule. Combining both lets an administrator express “stay logged in while you’re working, but never longer than this absolute ceiling” — a much closer match to how most organizations actually want session risk managed.

Why not just make Access Token Lifespan very short instead?

Some teams wonder whether a very short access token lifespan alone could substitute for session-level controls entirely. It can’t, because the refresh token tied to the session is what actually determines whether a new access token can keep being issued — and that refresh capability is governed by the session’s own Idle and Max limits, not by how short the access tokens themselves are. Shortening access tokens reduces the exposure window of any single stolen token, but it doesn’t touch the question of how long the overall login can be extended through refreshing.

Configuring these two timers is a balancing act between user convenience and session risk exposure.

The cost of getting it wrong in either direction

Setting Idle too short generates a steady stream of “I got logged out for no reason” complaints, often from users who were reading a long document or on a call without touching their keyboard. Setting Max too long, on the other hand, rarely generates complaints at all — which is exactly what makes it dangerous; nobody notices a session that’s been open for three days until something goes wrong with it. Tuning both values well is as much about listening for the absence of a problem as it is about responding to visible complaints.

Session duration is a direct security control — the longer a session lives, the longer a stolen or hijacked session can be misused.

Matching timeout values to sensitivity

Higher-sensitivity applications — those handling financial transactions, personal health information, or administrative control — generally warrant shorter Idle and Max values than lower-sensitivity, read-mostly applications. Keycloak’s per-client override capability exists precisely so this differentiation doesn’t require compromising the realm-wide defaults used by everything else.

Session hijacking and the value of a short Max

If an attacker manages to steal a valid refresh token — through malware, a compromised network, or a leaked log file — the window during which that stolen credential remains useful is bounded by the session’s Max setting, not by how quickly the theft is detected. A shorter Max value directly limits the damage a successful theft can do, independent of any other detection or response capability the organization has in place. This is one of the clearest, most concrete reasons Max deserves deliberate configuration rather than being left at a permissive default.

Session expiry behavior is easy to configure and forget — but worth watching once real users depend on it.

What to watch

What to log

Recording the reason a session ended — idle expiry, max expiry, explicit logout, or administrative revocation — turns a vague “why was I logged out?” support ticket into a quick, factual answer, and helps administrators tell whether their configured timeouts are actually serving the users they were designed for.

Distinguishing complaints from genuine misconfiguration

Not every “I got logged out unexpectedly” report reflects a poorly tuned setting — some are simply the Max ceiling working as intended after a genuinely long, continuous work session. Correlating the logout reason against session duration at the time of the event separates these two very different situations: a session that expired well before its configured Idle value might point to a clock synchronization or session replication issue, while one that expired right at the configured Max value is functioning exactly as designed.

Some ways of setting these timers work well in practice. Others create confusing, hard-to-diagnose logout behavior.

Patterns worth adopting

A checklist-style chapter distilling the operational wisdom from the sections above.

Coordinating with frontend session-warning behavior

Because Keycloak’s own Idle and Max timers run on the server, a well-designed frontend application typically implements its own client-side warning slightly before either limit is reached, giving users a visible countdown and a chance to extend their session proactively. This coordination between server-enforced limits and a considerate frontend experience is what separates a security control users tolerate from one they actively resent.

These two timers show up wherever session duration is a genuine security or compliance concern.

No — continuous activity only prevents the Idle timer from triggering. SSO Session Max still applies and will end the session once its fixed duration is reached, regardless of activity.

Both matter, but they address different risks: Idle limits exposure from unattended sessions, while Max limits how long any single login — including a compromised one — can remain valid overall.

Yes — a token refresh updates the session’s last-activity timestamp, which is why applications that refresh tokens silently in the background can keep a session alive well beyond a user’s actual engagement.

Yes — Keycloak supports per-client Idle and Max overrides, letting a sensitive application enforce stricter limits without changing the realm-wide defaults used elsewhere.

Remember Me sessions use a separate pair of Idle and Max values, typically longer than the defaults, applied only when the user explicitly opts into the persistent login option at authentication time.

No — Max is measured from the original session creation time and never resets, even though logging into another application through SSO does count as activity for the Idle timer.

Every Client Session tied to that User Session expires along with it, meaning each connected application will require re-authentication the next time it needs a valid token — even ones the user hasn’t actively touched recently.

Yes — an administrator can revoke a session directly, or a user can explicitly log out; both actions end the session immediately without waiting for either timer to elapse naturally.

SSO Session Idle and SSO Session Max govern the same session but ask two different questions. Idle asks, “has this session gone quiet for too long?” and resets every time genuine activity occurs. Max asks, “has too much total time passed since login?” and never resets, no matter how engaged the user has been. Together, they let an administrator express a session policy that’s both forgiving of natural pauses in use and firmly bounded by an absolute ceiling — a balance that a single flat timeout could never achieve on its own.

Getting the most out of these two settings means treating them as a matched pair rather than configuring each in isolation: choose an Idle value that matches how people actually work, choose a Max value tied to a real business or compliance requirement rather than an arbitrary default, and keep enough distance between the two that Idle actually gets to do its job before Max cuts in. Applied thoughtfully, this pair of timers becomes one of the most direct, easily explained security controls available in the entire realm configuration.