Keycloak Sessions: Authentication State Management

When you log into an application protected by Keycloak, it doesn’t just verify your credentials and forget about you—it creates a network of session objects that track who you are, which applications you’ve accessed, and how long you’ve been active. Understanding these sessions is important for anyone building secure applications or troubleshooting authentication issues.

This guide covers Keycloak’s session management—from the temporary authentication sessions created during login, to the long-lived offline sessions that enable mobile apps to work without constant re-authentication. We’ll examine the source code, understand the data structures, and see how all these pieces fit together to provide single sign-on across your applications.

Session Types Overview

Before looking at the details, let’s establish a mental model of how Keycloak organizes sessions. Think of it as a hierarchy: when you start logging in, Keycloak creates temporary Authentication Sessions to track your progress through the login flow. Once you successfully authenticate, these transform into a User Session that represents your overall login to Keycloak. Then, as you access different applications, each one gets its own Client Session attached to your user session.

This hierarchy is the foundation of Keycloak’s single sign-on (SSO) capability. Because your user session is separate from individual client sessions, you only need to authenticate once—Keycloak then creates client sessions automatically as you access different applications. Let’s explore each type in detail.

User Session

The User Session is the heart of Keycloak’s authentication model. It represents your overall login to Keycloak itself (the Identity Provider), not to any specific application. When you enter your credentials and successfully authenticate, Keycloak creates exactly one user session for your browser.

Key characteristics:

• One per browser login – Created when user authenticates to Keycloak
• Contains user identity (userId, loginUsername)
• Login metadata (ipAddress, authMethod, rememberMe)
• Timestamps (started, lastSessionRefresh)
• Session state (LOGGED_IN, LOGGING_OUT, LOGGED_OUT, LOGGED_OUT_UNCONFIRMED)
• Broker info for federated identity (brokerSessionId, brokerUserId)
• Parent container – holds references to all client sessions

Source files:

• UserSessionModel.java – Main interface
• UserSessionProvider.java – Session provider interface

Client Session

While the user session tracks who you are, client sessions track which applications you’ve accessed. Every time you visit a new application protected by Keycloak, a new client session is created and attached to your existing user session. This is what enables the “single” in single sign-on—the user session proves you’re authenticated, so Keycloak can issue tokens for new applications without asking for credentials again.

Key characteristics:

• One per application – Created when user accesses a specific client/app
• Which client (clientId)
• Protocol-specific data (redirectUri, action)
• Token metadata (refresh token reuse tracking)
• Client-specific notes and timestamps
• Child of user session – always attached to a parent user session

Source files:

• AuthenticatedClientSessionModel.java – Client session interface

Session Relationship Diagram

The relationship between user sessions and client sessions follows a parent-child pattern. This entity relationship diagram shows how they connect in the database:

Authentication Sessions

Before we have a user session, we have authentication sessions. These are temporary, transient sessions that exist only during the login process. They track your progress through potentially complex authentication flows—maybe you’ve entered your password but still need to complete MFA, or you’re halfway through a social login redirect.

Keycloak handles multiple browser tabs by giving each tab its own authentication session (identified by a “tab ID”), but they all share a common “root” authentication session tied to your browser. This prevents confusion when you have the login page open in multiple tabs.

• Temporary sessions during the login flow (before authentication completes)
• Has a RootAuthenticationSessionModel parent representing the browser
• Uses tab IDs to handle multi-tab browsing
• Cleared after successful login

Source files:

• AuthenticationSessionModel.java – Auth session interface
• RootAuthenticationSessionModel.java – Root auth session

Offline Sessions

So far, we’ve discussed sessions that live for hours—maybe a workday. But what about mobile apps that need to stay logged in for weeks? Or background services that refresh data overnight? That’s where offline sessions come in.

When a client requests the offline_access scope, Keycloak creates a parallel set of sessions with much longer lifespans. These offline sessions survive regular logout and can last for days or weeks. They’re stored persistently in the database, ensuring they survive server restarts.

• Created when offline tokens are requested (offline_access scope)
• Have longer lifespans than online sessions
• Linked to online sessions via CORRESPONDING_SESSION_ID note

Source files:

• OfflineUserSessionModel.java – Offline session interface

Storage Architecture

Now that we understand what sessions exist, let’s look at where they’re stored. Keycloak uses a two-tier architecture: a fast distributed cache (Infinispan) for active sessions, and a persistent database for durability.

Frequently accessed sessions are kept in the cache, while the complete set is stored in the database. When a session is needed, Keycloak first checks the cache—only querying the database if necessary.

Infinispan Cache (Primary/Hot Storage)

Infinispan serves as the primary storage for active sessions. It’s a distributed cache, meaning session data is replicated across Keycloak nodes in a cluster. This provides both speed (no database roundtrip for most operations) and resilience (if one node fails, sessions aren’t lost).

Cache names (defined in InfinispanConnectionProvider.java):

Source files:

• InfinispanConnectionProvider.java – Cache configuration
• InfinispanUserSessionProvider.java – Session provider implementation

JPA Database (Persistent Storage)

While Infinispan handles the hot path, the database provides durability. Offline sessions are always persisted, and online sessions can be persisted too for recovery after restarts. The database schema stores sessions as JSON blobs, allowing flexible storage of session notes and metadata.

Source files:

• JpaUserSessionPersisterProvider.java – JPA persistence provider
• PersistentUserSessionEntity.java – User session entity
• PersistentClientSessionEntity.java – Client session entity

Realm Session Settings

Keycloak provides fine-grained control over session lifetimes through realm-level settings. These settings form a hierarchy where client-specific settings can override realm defaults, and “remember me” sessions can have different timeouts than regular ones.

Timeout Hierarchy

Understanding this hierarchy is essential for configuring session behavior correctly. Client session timeouts fall back to SSO session timeouts if not explicitly set, and remember-me sessions have their own separate configuration:

SSO Session Settings (User Sessions)

These settings control how long user sessions remain valid. The idle timeout expires sessions after inactivity, while the max lifespan provides an absolute limit regardless of activity.

Defined in RealmModel.java:

Offline Session Settings

Offline sessions typically have much longer timeouts since they’re designed for scenarios like mobile apps that need persistent access.

Defined in RealmModel.java:

Client Session Settings

Individual clients can have their own timeout settings that override the realm defaults. When set to 0, they inherit from the realm-level SSO settings.

Defined in RealmModel.java:

Related files:

• RealmAttributes.java – Attribute constants

Session Expiration

Sessions don’t live forever—they expire based on either inactivity (idle timeout) or absolute time limits (max lifespan). Understanding how this works helps when troubleshooting “mysterious” logouts.

How lastSessionRefresh Works

The lastSessionRefresh field is the key to idle timeout calculations. Every time you do something active—refresh a token, access a new application—this timestamp gets updated. When the difference between now and lastSessionRefresh exceeds the idle timeout, your session expires.

1. Initial value: Set when user session is created
2. Updated on activity: When a user performs an action (e.g., refreshes a token)
3. Batch update: updateLastSessionRefreshes() updates multiple sessions at once
4. Used for expiration: Sessions filtered by comparing lastSessionRefresh with idle timeout

Source files:

• SessionExpirationUtils.java – Expiration calculation utilities
• SessionTimeouts.java – Cache timeout utilities

Expiration Flow

Here’s what happens during the expiration check:

Session State Machine

Sessions don’t just exist or not exist—they have states that track the logout process. This is important because logout can involve notifying multiple client applications, which takes time.

User Session vs Client Session: Key Differences

This comparison table summarizes the fundamental differences between these two session types:

Cascade Behavior

When sessions are removed, the cascade behavior differs between online and offline scenarios. For online sessions, removing the user session automatically removes all client sessions. For offline sessions, removing the last client session for a particular client can trigger removal of the offline user session.

Session Lifecycle

Let’s trace through a complete session lifecycle, from initial login through activity and finally logout. This shows how all the pieces we’ve discussed fit together in practice:

Disabling offline_access for Specific Clients

Not every application should have the ability to request offline tokens. A web application that users access daily probably doesn’t need month-long offline sessions, while a mobile app might. Keycloak provides several ways to control this.

Option 1: Remove from Client’s Optional Scopes (Recommended)

The cleanest approach is to simply remove the offline_access scope from clients that shouldn’t have it:

1. Go to Clients ? Select your client
2. Go to Client scopes tab
3. Find offline_access in Assigned optional client scopes
4. Remove it

Option 2: Role-Based Restriction

For more nuanced control, you can require specific roles to request offline access:

1. Go to Client scopes ? offline_access
2. Go to Scope tab
3. Assign specific roles that are required
4. Only users with those roles can request offline tokens

Option 3: Remove from Realm Default Optional Scopes

To disable offline access realm-wide by default:

1. Go to Realm settings ? Client scopes tab
2. Remove offline_access from Default Optional Client Scopes

Offline Access Control Flow

This diagram shows how Keycloak decides whether to grant offline access:

Related Source Files Summary

For quick reference, here’s a consolidated list of the key source files we’ve discussed:

Authentication Sessions (Details)

This section covers authentication sessions—the temporary sessions that manage the login flow. Understanding these is important if you’re customizing authentication flows or debugging login issues.

What is an Authentication Session?

An Authentication Session is a short-lived, transient session that tracks the state of an in-progress authentication. It exists from the moment a user initiates login until authentication completes (success or failure). It stores the progress through potentially complex authentication flows.

“Represents the state of the authentication. If the login is requested from different tabs of same browser, every browser tab has it’s own state of the authentication.”
— AuthenticationSessionModel.java:25-31

Key characteristics:

• Transient: Not persisted to database, only in distributed cache
• Short-lived: Expires after ~30 minutes (configurable)
• Per-tab: Each browser tab has its own authentication state
• Cleared on completion: Removed after successful authentication

Two-Level Architecture

Authentication sessions use a two-level architecture to handle the complexity of modern browser behavior. At the top level, a Root Authentication Session represents your browser. Underneath it, individual Authentication Sessions represent each browser tab where you might be logging in.

Tab ID Concept

Each browser tab gets a unique TabId – a Base64Url encoded random identifier (8 bytes ? 10-11 characters). This allows Keycloak to track multiple concurrent login attempts from the same browser without confusion.

Generation:

// From RootAuthenticationSessionAdapter.java:127
String tabId = Base64Url.encode(SecretGenerator.getInstance().randomBytes(8));

Compound ID Format: rootSessionId.tabId.clientUUID

• Used for cluster-wide lookups and cross-datacenter synchronization
• Parsed by AuthenticationSessionCompoundId

Multi-Tab Handling

Here’s what happens when you have the login page open in multiple tabs:

Tab Limit: Maximum 300 concurrent tabs per root session (configurable)

• When limit reached, oldest tab is automatically removed
• Configuration: InfinispanAuthenticationSessionProviderFactory:72

Authentication Session Lifecycle

An authentication session goes through several states as the user progresses through login:

Lifespan Calculation:

// From SessionExpiration.java:27-36
int lifespan = Math.max(
    realm.getAccessCodeLifespanLogin(),      // Default: 30 min
    Math.max(
        realm.getAccessCodeLifespanUserAction(), // Default: 5 min
        realm.getAccessCodeLifespan()            // Default: 1 min
    )
);

Data Stored in Authentication Session

Authentication sessions store various types of data to track login progress.

Execution Status

Each authenticator in your flow gets a status that tracks its outcome:

Three Types of Notes

Authentication sessions maintain three separate note collections, each with different lifecycles:

// Auth Notes - cleared when auth restarts
authSession.setAuthNote("acr", "gold");
authSession.getAuthNote("acr");

// Client Notes - persist through restarts
authSession.setClientNote(OIDCLoginProtocol.NONCE_PARAM, nonce);

// User Session Notes - transferred to UserSession on success
authSession.setUserSessionNote("custom_claim", "value");

Required Actions

The session tracks which required actions the user must complete:

authSession.addRequiredAction("UPDATE_PASSWORD");
authSession.addRequiredAction("CONFIGURE_TOTP");
Set<string> actions = authSession.getRequiredActions();
authSession.removeRequiredAction("UPDATE_PASSWORD");

Key Interfaces and Methods

AuthenticationSessionModel

RootAuthenticationSessionModel

Storage Implementation

Authentication sessions live only in the Infinispan distributed cache—they’re never persisted to the database. Since they’re short-lived, regenerating them from a cookie is straightforward.

Cache Configuration:

Implementation Classes:

AuthSession vs UserSession Comparison

Knowing when you’re dealing with an authentication session versus a user session is useful for debugging:

Transition to User Session

When authentication succeeds, data flows from the authentication session to the newly created user session:

Transfer happens in:

• AuthenticationSessionManager.updateAuthenticationSessionAfterSuccessfulAuthentication()

Configuration Options

Related Source Files

Session Cookies (Details)

Cookies tie browser sessions to Keycloak’s server-side session objects. Without them, Keycloak couldn’t remember who you are between requests. This section documents all session-related cookies based on source code analysis.

Cookie Definitions

All cookies are defined in CookieType.java. Let’s examine each one and understand its role.

Active Cookies

Legacy Cookies (Auto-Expired)

These cookies are automatically expired on startup for backward compatibility cleanup:

• AUTH_SESSION_ID_LEGACY
• KEYCLOAK_IDENTITY_LEGACY
• KEYCLOAK_SESSION_LEGACY

Cookie Security Scopes

Keycloak assigns each cookie to a security scope that determines its SameSite and HttpOnly attributes. This is defined in CookieScope.java:

Secure Flag Logic:

• If SameSite=None and context is HTTP (not HTTPS), automatically downgrade to SameSite=Lax
• Secure flag is always set to match the request context (HTTP/HTTPS)

Cookie Attributes Summary

* Downgraded to Lax if not in secure (HTTPS) context

Cookie Details by Purpose

1. AUTH_SESSION_ID – Authentication Session Cookie

This cookie tracks the in-progress authentication session. It’s signed to prevent tampering and includes routing information for clustered deployments.

Encoding Process (AuthenticationSessionManager.java:108-116):

// 1. Sign with INTERNAL signature algorithm
String signature = signatureProvider.sign(authSessionId.getBytes());
String signedValue = authSessionId + "." + Base64Url.encode(signature);

// 2. Base64Url encode the signed value
String encoded = Base64Url.encode(signedValue);

// 3. Add sticky session route for cluster affinity
String withRoute = stickyEncoder.encodeSessionId(encoded, authSessionId);
// Result: "NWUxNjFlMDAt...signature.node1"

Cookie Format:

Without route: base64(sessionId.signature)
With route:    base64(sessionId.signature).node1

Lifecycle:

2. KC_AUTH_SESSION_HASH – JavaScript Session Detection

This short-lived hash enables JavaScript-based session detection in iframes.

Purpose:

• Allows JavaScript to detect if authentication session exists
• Used for silent authentication checks in iframes
• Short TTL (60 seconds) prevents stale detection

Value: SHA256(authSessionId) ? Base64Url encoded (no padding)

// From AuthenticationSessionManager.java:121-127
String hash = HashUtils.sha256(authSessionId);
String encoded = Base64Url.encode(hash);
cookieProvider.set(CookieType.AUTH_SESSION_ID_HASH, encoded);

3. KEYCLOAK_IDENTITY – User Identity Cookie (SSO Cookie)

This is the primary SSO cookie. It contains a JWT with user identity information, allowing Keycloak to recognize you without re-authentication.

Token Structure (IdentityCookieToken.java):

public class IdentityCookieToken extends AccessToken {
    // Inherits from AccessToken but with:
    // - type = "keycloak-id" (not "Bearer")
    // - Contains session binding info
    // - state_checker for CSRF protection
}

Creation (AuthenticationManager.java:822-859):

IdentityCookieToken token = new IdentityCookieToken();
token.id(KeycloakModelUtils.generateId());
token.issuedNow();
token.subject(user.getId());
token.issuer(Urls.realmIssuer(uriInfo.getBaseUri(), realm.getName()));
token.type(TOKEN_TYPE_KEYCLOAK_ID);
token.exp(expiration);  // Based on SSO max or remember-me lifespan

// Add CSRF protection
token.setSessionState(userSession.getId());
token.setStateChecker(Base64Url.encode(SecretGenerator.randomBytes()));

Max Age Calculation:

if (rememberMe && realm.getSsoSessionMaxLifespanRememberMe() > 0) {
    maxAge = realm.getSsoSessionMaxLifespanRememberMe();
} else {
    maxAge = realm.getSsoSessionMaxLifespan();
}

4. KEYCLOAK_SESSION – Session Hash Cookie

This cookie enables OIDC session management through iframe-based session checks.

Purpose:

• OIDC session management spec compliance
• Allows check_session_iframe to detect session changes
• Intentionally NOT HttpOnly (JavaScript accessible)

Value: SHA256(userSessionId) ? URL encoded

Usage in check_session_iframe:

// Browser periodically calls check_session_iframe
// Iframe reads KEYCLOAK_SESSION cookie
// Compares with OP iframe session state
// Posts 'changed' or 'unchanged' to RP

5. KC_RESTART – Login Restart Cookie

This cookie handles a common scenario: what happens when your authentication session expires because you took too long to log in?

The Problem KC_RESTART Solves

When a user starts login but takes too long (reading terms of service, phone call, coffee break), the authentication session expires in Infinispan cache (default 30 minutes). Without KC_RESTART, the user would see an error and be sent back to the application to start over.

Content Structure

From RestartLoginCookie.java:

{
    "cid": "my-client-app",           // Client ID - which app initiated login
    "pty": "openid-connect",          // Protocol type
    "ruri": "https://myapp.com/cb",   // Redirect URI - where to go after auth
    "act": "authenticate",            // Action being performed
    "notes": {                        // Client notes (protocol state)
        "scope": "openid profile",
        "nonce": "abc123",
        "state": "xyz789"
    }
}

Encoding

1. Serialize to JSON
2. Encode as JWT with TokenCategory.INTERNAL
3. Encrypt with JWE (direct encryption + signature using realm keys)

The cookie is encrypted (not just signed) because it contains potentially sensitive protocol state like OIDC nonce and state parameters.

Why Not Just Extend Auth Session TTL?

The cookie approach is stateless – the server doesn’t need to keep the session alive, but can recreate it on-demand from the cookie data.

Cookie Lifecycle Flow

Here’s the complete flow showing how cookies are set, used, and expired during a typical login session:

Sticky Session Routing

For clustered deployments, Keycloak uses cookie-based routing to maintain session affinity, ensuring requests go to the node that has the session in its local cache.

Interface: StickySessionEncoderProvider.java

interface StickySessionEncoderProvider {
    // Encode session ID with route info
    String encodeSessionId(String message, String sessionId);

    // Decode and extract route
    SessionIdAndRoute decodeSessionIdAndRoute(String encodedSessionId);

    // Get route for session
    String sessionIdRoute(String sessionId);

    // Check if route should be attached
    boolean shouldAttachRoute();
}

Route Format:

Cookie value:    base64(sessionId.signature).node1
                                              ?
                                         Route suffix

Cookie Validation

Identity Cookie Validation (AuthenticationManager.java:909-919):

Non-Secure Context Warning

When cookies are set in HTTP (non-HTTPS) context, Keycloak logs a warning (DefaultCookieProvider.java:76-100):

"Non-secure context detected; cookies are not secured,
and will not be available in cross-origin POST requests."

Behavior changes in HTTP:

• SameSite=None cookies downgraded to SameSite=Lax
• Secure flag set to false
• Federation cookies may not work in cross-origin scenarios

Related Source Files

Token-Session Relationship (Details)

Tokens and sessions are bound in Keycloak—every token carries a reference to its parent session. This binding has important implications for token validation and revocation.

Session ID (sid) Claim

Every access token and ID token includes a sid (session ID) claim that binds the token to a specific user session. This is the thread that connects the stateless JWT world to Keycloak’s stateful session management.

Token Structure:

Source: TokenManager.java:663-671

// Session ID is always added to tokens
token.setSessionId(userSession.getId());
token.setSessionState(userSession.getId());  // Legacy compatibility

Token Creation Flow

When Keycloak creates a token, it always ties it to the current session context:

Token-Session Binding Points

Token Introspection and Session Validation

When a resource server introspects a token, Keycloak validates that the bound session is still active. This means tokens become invalid the moment their session expires or is revoked—even if the token’s own expiration time hasn’t been reached.

Implementation: TokenManager.validateToken()

public TokenValidation validateToken(String tokenString) {
    // 1. Decode and verify signature
    AccessToken token = verifyAccessToken(tokenString);

    // 2. Check session binding
    String sessionId = token.getSessionId();
    if (sessionId != null) {
        UserSessionModel session = sessionProvider.getUserSession(realm, sessionId, false);
        if (session == null || session.getState() != State.LOGGED_IN) {
            throw new OAuthErrorException("invalid_token", "Session not active");
        }

        // 3. Check session expiration
        if (isSessionExpired(session)) {
            throw new OAuthErrorException("invalid_token", "Session expired");
        }
    }

    return new TokenValidation(token, session);
}

Refresh Token and Session Updates

Each time you refresh a token, the client session timestamp is updated, keeping the session alive:

Refresh Token Reuse Detection:

Keycloak tracks refresh token usage to detect potential token theft. If someone tries to reuse an old refresh token after a new one has been issued, it’s a sign that the token may have been stolen.

// From TokenManager.java - refresh token tracking
String currentRefreshToken = clientSession.getCurrentRefreshToken();
int currentRefreshTokenUseCount = clientSession.getCurrentRefreshTokenUseCount();

if (refreshToken.equals(currentRefreshToken)) {
    // Same token being reused - increment counter
    currentRefreshTokenUseCount++;
    if (currentRefreshTokenUseCount > maxReuseCount) {
        // Potential token theft - revoke session
        userSessionProvider.removeUserSession(realm, userSession);
        throw new OAuthErrorException("invalid_grant", "Maximum reuse exceeded");
    }
} else {
    // New refresh cycle
    clientSession.setCurrentRefreshToken(newRefreshToken);
    clientSession.setCurrentRefreshTokenUseCount(0);
}

Token Revocation Impact

When a session is terminated—whether by logout, admin action, or expiration—all bound tokens become invalid:

Transient Sessions (Stateless Tokens)

For scenarios where you don’t want the overhead of session management, Keycloak supports stateless tokens with “transient” sessions. These sessions exist only for the duration of the request and are never persisted.

Configuration: Set client’s “Use Refresh Tokens” to OFF and enable “Transient Sessions”

// From UserSessionModel.SessionPersistenceState
public enum SessionPersistenceState {
    PERSISTENT,     // Normal persistent session
    TRANSIENT       // In-memory only, no database persistence
}

Transient Session Behavior:

• Session exists only in memory during request
• Tokens are fully self-contained (no sid lookup needed)
• Refresh tokens not issued
• Token introspection works without session lookup

Related Source Files

Session Logout & Revocation (Details)

When it’s time to end a session, Keycloak doesn’t just delete some data—it goes through a process to notify all affected parties. Understanding the logout mechanisms is important for implementing applications that properly clean up session state.

Logout Mechanisms Overview

Session State Machine During Logout

The logout process isn’t instantaneous—sessions transition through states as Keycloak notifies all affected clients:

State enum from UserSessionModel.java:42-47:

public enum State {
    LOGGED_IN,              // Active session
    LOGGING_OUT,            // Logout in progress
    LOGGED_OUT,             // Fully logged out
    LOGGED_OUT_UNCONFIRMED  // Logout with unconfirmed clients
}

Direct Logout (RP-Initiated)

The standard OIDC logout flow starts when a user clicks “logout” in an application:

Implementation: LogoutEndpoint.java

Backchannel Logout

Backchannel logout is server-to-server communication—Keycloak directly calls each client’s logout endpoint. This is more reliable than frontchannel because it doesn’t depend on the user’s browser.

Logout Token Structure:

Implementation: BackchannelLogoutAction.java

Frontchannel Logout

Frontchannel logout uses the user’s browser to notify clients via iframes. This works when backchannel isn’t available but is less reliable since it depends on the browser.

Admin Session Revocation

Administrators can forcibly revoke sessions through the Admin API:

Implementation: UserResource.java

Token Revocation Endpoint

Clients can revoke tokens directly, which terminates the associated session:

Logout Configuration Options

Related Source Files

Offline Sessions (Details)

This section provides more detail on offline sessions. These long-lived sessions are what make “stay logged in” functionality work for mobile apps and background services.

What are Offline Sessions?

Offline sessions are special sessions created when a client requests the offline_access scope. They’re designed for scenarios where users need persistent access without frequent re-authentication—think mobile apps that sync data in the background or services that run overnight jobs.

Key Characteristics:

• Created alongside regular sessions when offline_access scope is requested
• Have separate, longer timeout configurations
• Survive regular session logout (unless explicitly revoked)
• Stored in separate cache and database tables
• Each client has its own offline session (can be removed independently)

Offline Session Creation

When a client requests offline_access, Keycloak creates parallel session structures:

Implementation: TokenManager.java

// Check if offline_access scope requested
if (TokenUtil.hasScope(tokenScopes, OAuth2Constants.OFFLINE_ACCESS)) {
    // Create offline session from online session
    UserSessionModel offlineSession = session.sessions()
        .createOfflineUserSession(userSession);
    session.sessions()
        .createOfflineClientSession(clientSession, offlineSession);
}

Offline vs Online Session Relationship

Online and offline sessions are linked but independent. You can log out of your online session (ending browser-based access) while your mobile app continues working with its offline session.

Linking via Notes:

// When creating offline session, link to online session
offlineSession.setNote(
    UserSessionModel.CORRESPONDING_SESSION_ID,
    onlineSession.getId()
);
onlineSession.setNote(
    UserSessionModel.CORRESPONDING_SESSION_ID,
    offlineSession.getId()
);

Offline Session Storage

Offline sessions use separate caches and are always persisted to the database for durability:

Offline Session Expiration

Offline sessions have their own expiration rules, typically much longer than online sessions:

Timeout Configuration:

Lazy Loading of Offline Sessions

Offline sessions are loaded lazily from the database—they’re not all kept in memory. This allows Keycloak to handle millions of offline sessions without exhausting memory:

Offline Token vs Regular Refresh Token

Related Source Files

User Sessions (Details)

This section covers the UserSessionModel interface—the core abstraction for representing authenticated users in Keycloak.

UserSessionModel Interface

The interface is defined in UserSessionModel.java:

User Session Fields

User Session Creation

Here’s what happens when a new user session is created:

Creation method from InfinispanUserSessionProvider.java:

public UserSessionModel createUserSession(
    RealmModel realm,
    UserModel user,
    String loginUsername,
    String ipAddress,
    String authMethod,
    boolean rememberMe,
    String brokerSessionId,
    String brokerUserId) {

    String id = KeycloakModelUtils.generateId();
    int timestamp = Time.currentTime();

    UserSessionEntity entity = new UserSessionEntity(id);
    entity.setRealmId(realm.getId());
    entity.setUserId(user.getId());
    entity.setLoginUsername(loginUsername);
    entity.setIpAddress(ipAddress);
    entity.setAuthMethod(authMethod);
    entity.setRememberMe(rememberMe);
    entity.setStarted(timestamp);
    entity.setLastSessionRefresh(timestamp);
    entity.setState(State.LOGGED_IN);
    entity.setBrokerSessionId(brokerSessionId);
    entity.setBrokerUserId(brokerUserId);

    // Store in cache
    cache.put(id, entity);

    return wrap(realm, entity, false);
}

User Session Notes

Notes provide a flexible way to attach metadata to sessions:

// Setting notes
userSession.setNote("ACR", "gold");
userSession.setNote("AUTH_TIME", String.valueOf(Time.currentTime()));

// Reading notes
String acr = userSession.getNote("ACR");
Map<string, string=""> allNotes = userSession.getNotes();

Session Refresh Mechanism

Keycloak doesn’t update lastSessionRefresh on every single activity—that would create too much cache/database traffic. Instead, it uses a threshold:

Refresh threshold:

• Updates happen if time since last refresh exceeds SESSION_REFRESH_INTERVAL (default: 60 seconds)
• Prevents excessive updates during rapid activity

User Session Events

Related Source Files

Client Sessions (Details)

While user sessions represent the overall authentication, client sessions track the relationship between a user and specific applications. Let’s examine the AuthenticatedClientSessionModel interface in detail.

AuthenticatedClientSessionModel Interface

The interface is defined in AuthenticatedClientSessionModel.java:

Client Session Fields

Client Session Creation

Client sessions are created when a user first accesses a client application:

Client Session Notes

Refresh Token Tracking

Client sessions track refresh token usage to detect potential token theft:

Implementation:

// Tracking current refresh token
clientSession.setCurrentRefreshToken(newRefreshTokenId);
clientSession.setCurrentRefreshTokenUseCount(0);

// On reuse detection
int count = clientSession.getCurrentRefreshTokenUseCount();
if (count > maxCount) {
    // Token theft detected - revoke everything
    sessionProvider.removeUserSession(realm, userSession);
    throw new OAuthErrorException("invalid_grant", "Token reuse detected");
}

Detaching Client Sessions

The detachFromUserSession() method is used during refresh token rotation to create a snapshot for comparison:

// Detach creates a snapshot for comparison
clientSession.detachFromUserSession();

// After generating new tokens, reattach
userSession.getAuthenticatedClientSessions().put(clientId, clientSession);

Client Session Cascade Behavior

Related Source Files

Persistent Sessions (Details)

To survive restarts and provide durability, Keycloak persists sessions to the database. This section covers the JPA persistence layer that makes this possible.

Database Schema

Persistent Entities

PersistentUserSessionEntity

From PersistentUserSessionEntity.java:

@Entity
@Table(name = "OFFLINE_USER_SESSION")
@NamedQueries({
    @NamedQuery(name = "findUserSessionById",
        query = "SELECT s FROM PersistentUserSessionEntity s WHERE s.userSessionId = :sessionId"),
    @NamedQuery(name = "findUserSessionsByUser",
        query = "SELECT s FROM PersistentUserSessionEntity s WHERE s.userId = :userId"),
    @NamedQuery(name = "removeUserSessionsByRealm",
        query = "DELETE FROM PersistentUserSessionEntity s WHERE s.realmId = :realmId")
})
public class PersistentUserSessionEntity {
    @Id
    @Column(name = "USER_SESSION_ID")
    private String userSessionId;

    @Column(name = "REALM_ID")
    private String realmId;

    @Column(name = "USER_ID")
    private String userId;

    @Column(name = "LAST_SESSION_REFRESH")
    private int lastSessionRefresh;

    @Column(name = "OFFLINE_FLAG")
    private String offlineFlag;  // "0" = online, "1" = offline

    @Column(name = "DATA")
    private String data;  // JSON serialized session data
}

PersistentClientSessionEntity

From PersistentClientSessionEntity.java:

@Entity
@Table(name = "OFFLINE_CLIENT_SESSION")
@IdClass(PersistentClientSessionKey.class)
public class PersistentClientSessionEntity {
    @Id
    @Column(name = "USER_SESSION_ID")
    private String userSessionId;

    @Id
    @Column(name = "CLIENT_ID")
    private String clientId;

    @Id
    @Column(name = "OFFLINE_FLAG")
    private String offlineFlag;

    @Column(name = "TIMESTAMP")
    private int timestamp;

    @Column(name = "DATA")
    private String data;  // JSON serialized client session data
}

Persistence Provider

The JpaUserSessionPersisterProvider handles all database operations:

public class JpaUserSessionPersisterProvider implements UserSessionPersisterProvider {

    // Create new persistent session
    public void createUserSession(UserSessionModel userSession, boolean offline) {
        PersistentUserSessionEntity entity = new PersistentUserSessionEntity();
        entity.setUserSessionId(userSession.getId());
        entity.setRealmId(userSession.getRealm().getId());
        entity.setUserId(userSession.getUser().getId());
        entity.setLastSessionRefresh(userSession.getLastSessionRefresh());
        entity.setOfflineFlag(offline ? "1" : "0");
        entity.setData(serializeSessionData(userSession));

        em.persist(entity);
    }

    // Load session from database
    public UserSessionModel loadUserSession(
        RealmModel realm, String sessionId, boolean offline) {

        PersistentUserSessionEntity entity = em.find(
            PersistentUserSessionEntity.class, sessionId);

        if (entity == null) return null;

        return deserializeToModel(realm, entity);
    }

    // Batch update lastSessionRefresh
    public void updateLastSessionRefreshes(
        RealmModel realm, int lastSessionRefresh,
        Collection<string> sessionIds, boolean offline) {

        em.createNamedQuery("updateSessionRefreshes")
            .setParameter("lastSessionRefresh", lastSessionRefresh)
            .setParameter("sessionIds", sessionIds)
            .setParameter("offlineFlag", offline ? "1" : "0")
            .executeUpdate();
    }
}

Data Serialization

Session data is stored as JSON in the DATA column, enabling flexible storage of notes and metadata:

Lazy Loading Architecture

Sessions are loaded from the database on-demand to conserve memory:

Cache-Database Synchronization

Configuration for Persistence

Related Source Files

Conclusion

This document covered Keycloak’s session management. From the temporary authentication sessions that track your progress through login, to the long-lived offline sessions that keep mobile apps working for weeks, each component plays a role in providing secure authentication.

Key takeaways:

1. Sessions form a hierarchy: Authentication sessions ? User sessions ? Client sessions, each serving a distinct purpose.

2. Two-tier storage: Infinispan provides fast, distributed caching while the database ensures durability.

3. Cookies are the glue: Multiple cookies with different security profiles tie browser state to server-side sessions.

4. Tokens and sessions are bound: The sid claim creates a tight coupling between stateless JWTs and stateful sessions.

5. Logout is orchestrated: Backchannel and frontchannel mechanisms ensure all parties are notified when sessions end.

Understanding these internals will help you configure Keycloak correctly, debug authentication issues, and build applications that work harmoniously with Keycloak’s session management. When something goes wrong, you’ll now know exactly where to look—whether it’s cache eviction, cookie misconfiguration, or timeout settings.