What is a session, really?

When a user successfully logs in, Keycloak creates a user session — a server-side record that says “this specific person is currently logged in, starting at this time, from this device or browser.” This session lives inside Keycloak’s own memory and storage, separate from anything the applications the user visits actually hold. A single user session can be shared across multiple applications through single sign-on, meaning one login can quietly authenticate a user into several different apps without asking them to log in again for each one.

What is a token, and how is it different from a session?

A token is a separate, physical artifact — a signed piece of text — that Keycloak hands to an application as proof that a session exists and is valid. Tokens are like photocopies of a permission slip: once handed out, the original office can’t reach into someone’s pocket and erase a photocopy directly. This distinction is the entire reason session revocation is a real engineering problem rather than a simple flag flip: killing the session record is one action, but making sure every already-issued token stops being honored is a separate, harder problem.

Why does revocation matter at all?

Without a reliable way to revoke sessions and their tokens, a stolen device, a compromised account, or a fired employee’s access could persist far longer than intended — an attacker holding a valid, unexpired token could keep acting as that user until the token’s own expiry time arrives naturally, no matter what an administrator does in the meantime. Session revocation exists to give administrators and the system itself a way to say “this access ends now,” and have that statement actually take effect promptly across the applications relying on it.

Key vocabulary, explained simply

graph TB
    ADM[Admin or User Action:
Logout / Revoke] --> SS[Session Store
marks session ended]
    SS --> SLO[Single Sign-Out
notifies connected apps]
    ADM --> NBP[Not-Before Policy
realm/client timestamp]
    NBP --> ALL[Instantly invalidates all
tokens issued before it]
    APP[Application] --> TI[Token Introspection Endpoint]
    TI --> SS
    APP --> LOCAL[Locally cached token
trusted until expiry unless checked]
    

Component breakdown

Where this is managed in the admin console

Inside the Keycloak Admin Console, administrators manage active sessions under a realm’s or a specific user’s Sessions tab, where individual sessions can be viewed and terminated directly. The Not-Before Policy is set under Realm Settings → Sessions (realm-wide) or on an individual client’s settings (client-specific), usually via a “Revoke all active sessions” style action that also updates this timestamp automatically.

Why not just rely on short token expiry alone?

Short-lived access tokens do limit how long a revoked session’s old tokens remain usable, but relying on expiry alone means there’s always a window — however small — where a revoked user can still act using an old, not-yet-expired token. Session revocation mechanisms exist precisely to shrink or eliminate that window for situations where waiting even a few minutes for natural expiry is unacceptable, such as an active security incident.

Ending a session directly

When a user logs out, or an administrator terminates their session, Keycloak marks the corresponding session record as ended in its session store. Any attempt to use the session’s refresh token afterward is immediately rejected, since Keycloak checks the refresh token against the live session record on every use — refresh tokens are not self-contained in the same way access tokens are, so this check is fast and reliable.

The access token problem

Access tokens, by design, are self-contained and signed — an application can typically validate one just by checking its signature and expiry, without calling back to Keycloak at all. This is what makes them fast and scalable, but it also means a plain access token check has no way to know a session was just revoked seconds ago. This is the fundamental trade-off at the heart of session revocation: the speed benefit of self-contained tokens comes directly at the cost of instant revocability, unless an application deliberately adds an extra check.

How the Not-Before Policy solves the access token problem

The Not-Before Policy sidesteps the self-contained-token problem entirely by attaching a timestamp to the realm or client rather than to any individual token. Applications configured to check this policy compare a token’s issued-at time against the current not-before timestamp; if the token was issued earlier, it’s rejected outright, regardless of whether its own expiry time has technically not yet passed. This gives administrators a blunt, immediate “invalidate everything issued before right now” switch, at the cost of also invalidating tokens for users who weren’t actually the target of the concern.

Step-by-step: what happens when an admin revokes a specific user’s session

sequenceDiagram
    participant Admin
    participant Keycloak
    participant App1 as Application A
    participant App2 as Application B

    Admin->>Keycloak: Revoke user's session
    Keycloak->>Keycloak: Marks session ended
    Keycloak->>App1: Back-channel logout notification
    Keycloak->>App2: Back-channel logout notification
    App1->>App1: Clears local login state
    App2->>App2: Clears local login state
    Note over App1,App2: Already-issued access tokens
remain valid until natural expiry
unless introspection is used
    

Notice the note in that diagram — it’s the single most important nuance in the whole topic. Session revocation instantly and reliably kills the session and, through it, the refresh token. But any access token already handed to an application before revocation continues to pass a plain signature-and-expiry check until it naturally expires, unless that specific application goes out of its way to call Keycloak’s introspection endpoint on every request. Designing for genuinely instant revocation everywhere means deliberately choosing shorter access token lifetimes, introspection, or both, rather than assuming revocation alone handles it.

The lifecycle of a session from login to full teardown

Why revocation speed is a genuine security metric

The gap between “we decided to revoke access” and “access is actually, fully revoked everywhere” is exactly the window an attacker (or a fired, disgruntled employee) can continue operating in. This gap is shaped directly by access token lifetime and whether sensitive applications use introspection. Organizations handling higher-risk data deliberately shorten access token lifetimes specifically to shrink this window, accepting more frequent token refreshes as the cost.

Password changes and forced re-authentication

Keycloak can be configured to automatically terminate all of a user’s existing sessions when their password changes, ensuring that a scenario where an attacker had been quietly using a stolen password doesn’t continue after the legitimate user regains control by changing it. This is a commonly overlooked but important piece of a complete account-recovery security story.

Auditing revocation events

Keycloak’s admin event log records session-termination actions, giving security teams a way to confirm when and by whom a revocation was triggered — an important piece of evidence during an incident investigation, and a useful signal for distinguishing routine logouts from deliberate, security-driven interventions.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes