Before opening the admin console, let’s fix the plain-English idea in place.

In Keycloak, when a user logs in, two related but distinct things get created behind the scenes: a user session, representing the fact that this person is authenticated with Keycloak at all, and one client session for every specific application the user then goes on to access during that same login. A client session is the record of one particular client application’s relationship with an already-authenticated user — tracking things like which client it belongs to, what was granted, and when this specific application was last active.

The relationship is one-to-many: a single user session can have several client sessions hanging off it at once, one per application the user has touched since logging in. Log into Keycloak once, then visit three separate applications that all trust the same realm, and you typically end up with one user session and three client sessions underneath it.

These two terms are easy to confuse, so it’s worth putting them side by side.

Neither one is useful entirely on its own. The user session alone can’t tell you which specific applications a person is actively using, and a client session alone can’t exist without a parent user session backing it — every client session is always tied back to exactly one user session.

This split isn’t accidental complexity — it’s the exact mechanism that makes single sign-on and clean logout possible.

If Keycloak only tracked one flat session per user, there would be no natural way to answer questions like “which applications has this user actually used during this login?” or “can I log this user out of just one application, without touching the others?” By separating the broad user session from the many narrower client sessions beneath it, Keycloak gets a natural home for both realm-wide concerns (like the overall SSO session timeout) and per-application concerns (like which specific app to notify during logout).

Here’s the moment-by-moment sequence behind the scenes.

flowchart TD
    A["User visits App A"] --> B{"User session
already exists?"}
    B -- No --> C["User logs in
User Session created"]
    B -- Yes --> D["SSO — no login prompt needed"]
    C --> E["Client Session created
for App A"]
    D --> E
    E --> F["Tokens issued to App A"]
    F --> G["User later visits App B"]
    G --> H["New Client Session created
for App B, under same User Session"]
        

Notice that visiting App B doesn’t require App A’s client session to be touched at all — the two client sessions coexist independently, both anchored to the same underlying user session.

A client session isn’t just a marker that says “this app was used” — it carries meaningful state of its own.

This is why a client session matters beyond bookkeeping: it’s the anchor Keycloak uses every time that specific application needs to refresh a token, and it’s the specific record that gets invalidated if that one application is logged out individually.

Tokens and sessions are related but not identical concepts, and the client session sits right at that boundary.

An access token is a self-contained, short-lived credential — once issued, Keycloak doesn’t necessarily need to look anything up to validate it, as long as its signature and expiry check out. A refresh token, by contrast, works by pointing back at a session record. When a client presents a refresh token to get a new access token, Keycloak looks up the corresponding client session (and its parent user session) to confirm it’s still valid before issuing anything new.

A client session’s lifespan is shaped by both its own settings and the boundaries of its parent user session.

A client session can never outlive its parent user session — once the overall user session ends, every client session beneath it ends too, automatically. Within that boundary, individual client timeouts and activity also matter: if a particular client session sits idle without being used to refresh a token, it can expire on its own, even while the broader user session and other client sessions under it remain active.

Where this session data actually lives matters once Keycloak runs across more than one server.

Client sessions, like regular user sessions, live primarily in Keycloak’s distributed in-memory cache (Infinispan), replicated across cluster nodes so any node can serve a request for an active session without a single point of failure. This is different from offline sessions, which are deliberately persisted to the database so they can survive far longer than any in-memory cache is designed to hold data.

The client-session model is what makes both full logout and selective logout possible.

sequenceDiagram
    participant U as User
    participant K as Keycloak
    participant A as App A
    participant B as App B

    U->>K: Initiates logout
    K->>K: Find User Session
    K->>K: Find all Client Sessions under it
    K->>A: Back-channel logout notification
    K->>B: Back-channel logout notification
    A-->>K: Session invalidated locally
    B-->>K: Session invalidated locally
    K->>K: Terminate User Session
    K-->>U: Logout complete across all apps
        

This is the mechanism behind Single Logout (SLO): because Keycloak knows exactly which client sessions exist under a given user session, it can notify every one of those applications — often through a back-channel logout request — so each can clean up its own local state, rather than relying on the user manually logging out of every application one by one.

Because client sessions sit at the heart of both SSO and logout, a few practices keep that machinery trustworthy.

The two-layer session model is elegant, but it does add a bit of conceptual overhead.

A few recurring habits distinguish teams who work smoothly with this model from those who get tripped up by it.

A short, practical checklist for teams building or debugging applications on top of Keycloak’s session model.

The client session model quietly powers everyday experiences across many kinds of deployments.

Because session behavior is central to both user experience and security, visibility into it is valuable.

No. Every client session is always tied to exactly one parent user session, and it’s automatically terminated when that user session ends.

Generally, one client session per client per user session is the standard model, representing that application’s single relationship with the user during that login.

Not necessarily. Whether a logout ends just one client session or the entire user session (and all client sessions under it) depends on which type of logout is triggered.

In the Keycloak admin console, under a user’s Sessions tab, or under a specific client’s own Sessions view, both of which reflect the same underlying data from different angles.

No. Regular client sessions live in fast, in-memory storage and are tied to normal SSO behavior, while offline sessions are deliberately persisted to the database to survive far longer, independent of the standard client-session lifecycle.

Nothing happens to the client session itself just because an access token expires — the client session remains valid and can be used to obtain a fresh access token via the refresh token, as long as its own timeout hasn’t been reached.

A client session is Keycloak’s record of one specific application’s relationship with an already-authenticated user, nested under that user’s broader user session. This two-layer design is what makes single sign-on across many applications possible, gives administrators precise visibility into exactly which apps a user has touched during a login, and enables both full single logout and targeted, per-application session termination. Understanding the difference between a user session and the client sessions living beneath it clears up a surprising amount of confusion about how Keycloak-backed logins and logouts actually behave in practice.