Learn Keycloak - Session Management

#Introduction

Over the last ten episodes you built the authentication and authorization foundation with Keycloak. Episode 11 ties it all together: session management. You already know how tokens are created and rotated, but behind the tokens there's a piece of state called the session — which determines when a user is considered "logged in" at Keycloak and at its applications.

#Session Types in Keycloak

When a user logs into an application using Keycloak, several sessions are actually running at the same time:

The SSO session is the brain of everything. Once a user logs in at one application, Keycloak records this session, and other applications in the same realm can reuse the same session — that's what's called single sign-on. The client session records which applications are participating in that SSO session.

#Session Lifecycle

A session is born when the user successfully passes full authentication at Keycloak. From there the session lives its lifecycle:

1. Session creation — happens on the first login, when credentials are verified.
2. Session refresh — any activity that touches Keycloak updates the session's last activity time.
3. Session timeout — the session ends when its idle or maximum limit is reached.
4. Session termination — explicit logout by the user, an admin, or another mechanism.

The key to understanding this lifecycle: access tokens and refresh tokens are just mirrors of the session. As long as the SSO session lives, the refresh token can exchange new access tokens. Once the session dies, all its descendants die with it.

#Timeout Configuration

The two main numbers governing session lifetime live in Realm settings → Sessions:

• SSO Session Idle — how long a session may sit idle without activity. A session hitting this limit expires even if it hasn't reached the maximum.
• SSO Session Max — the absolute cap on session age since creation. After that, the user must log in again regardless of activity.

All the main session settings are summarized in the following table:

Notice the same pattern in every row: the idle value can be extended by activity, the max value is a hard limit. For offline sessions, both values are usually set much longer — because offline sessions are designed to survive without the user's presence, like a mobile app opened rarely.

The distinction between the two matters: idle is reset by activity, max never is. Security-sensitive applications press down on max; comfort-oriented applications give both more room. There are also separate settings for offline sessions and for Remember me mode as in episode 7.

#Single Logout

If single sign-on means logging in once for all applications, single logout (SLO) is the inverse: log out once, all applications log out. Keycloak supports several SLO mechanisms:

• Front-channel logout — the browser is redirected to each application's logout URL in turn via redirects. Simple and compatible with non-OIDC applications.
• Back-channel logout — Keycloak notifies applications via server-to-server calls, without involving the browser. More reliable, suited to applications without an active browser session.
• RP-initiated logout — the application itself initiates logout by redirecting the user to the end_session_endpoint.

The pattern used is set in the client configuration — Backchannel logout URL for back-channel, and the Front channel logout option on the client. For a healthy application ecosystem, enable both.

#RP-initiated Logout and Logout Tokens

The simplest way to start a logout from an application is to redirect the user's browser to the end_session_endpoint:

curl -s "https://kc.example.com/realms/my-realm/protocol/openid-connect/logout" \
  -d "client_id=my-app" \
  -d "client_secret=4f9a2c8d..." \
  -d "id_token_hint=eyJhbGciOi..."

protocol/openid-connect/logout is the end_session_endpoint listed in the discovery metadata from episode 9. The id_token_hint parameter ensures the logout truly belongs to the same user, and the post_logout_redirect_uri parameter returns the user to the application when finished.

For back-channel logout, Keycloak sends a logout token — a special JWT of type logout+jwt that tells the application the user's session has ended. The receiving application must validate this token like an ID token: check the signature, iss, aud, sub, sid, and the events claim containing logout.

#Monitoring Sessions

The admin console offers a direct view of all sessions:

• Active sessions — in the Realm settings → Sessions menu, or per client in the Sessions tab of the client details, you can see the list of active sessions and the clients involved.
• Session analytics — per-client session statistics help understand usage patterns and spot anomalies.
• Session revocation — sessions can be ended manually one by one or all at once; there's also Revocation with a not-before policy that forces all tokens before a given point in time to be considered invalid.

Device tracking completes the picture: on the user page, you can see the devices a user has used and revoke sessions per device. This is very useful when a user reports a lost device or an account used by someone else.

For automation, all these operations are also available via the Admin REST API — sessions can be listed and revoked without touching the console:

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://kc.example.com/admin/realms/my-realm/users/9c4d5e6f-.../sessions"

admin/realms/my-realm/users is the root of all user operations, including reading and revoking sessions. Combine it with alerting scripts — e.g. detecting a session from another country triggers immediate revocation — to make session monitoring reactive rather than just a report.

#Closing

Episode 11 closed the OIDC chapter with session management: session types and their roles, the lifecycle from birth to logout, idle and maximum timeout configuration, single logout mechanisms including front-channel, back-channel, and RP-initiated logout, logout tokens, and monitoring and revoking sessions from the admin console.

Key takeaways:

• Tokens are mirrors of sessions — when the SSO session dies, all its descendants die with it.
• Idle is reset by activity, max never is — understand the difference when setting timeouts.
• Single logout must be planned — front-channel for compatibility, back-channel for reliability.
• Sessions can be monitored and revoked — device tracking and revocation are security enforcement tools.

In the next episode (episode 12), we switch worlds: SAML 2.0 — the XML-based enterprise protocol that predates OIDC. You'll see its components, how SAML compares to OIDC, and how Keycloak stands as an identity provider for legacy applications.