Managing User Sessions

When users log into realms, Keycloak maintains a user session for each user and remembers each client visited by the user within the session. Realm administrators can perform multiple actions on each user session:

• View login statistics for the realm.
• View active users and where they logged in.
• Log a user out of their session.
• Revoke tokens.
• Set up token timeouts.
• Set up session timeouts.

Administering sessions

To see a top-level view of the active clients and sessions in Keycloak, click Sessions from the menu.

Signing out all active sessions

You can sign out all users in the realm. From the Action list, select Sign out all active sessions. All SSO cookies become invalid. Keycloak notifies clients by using the Keycloak OIDC client adapter of the logout event. Clients requesting authentication within active browser sessions must log in again. Client types such as SAML do not receive a back-channel logout request.

*Clicking Sign out all active sessions does not revoke outstanding access tokens. Outstanding tokens must expire naturally. For clients using the Keycloak OIDC client adapter, you can push a revocation policy to revoke the token, but this does not work for other adapters.

Viewing client sessions

Procedure

1. Click Clients in the menu.
2. Click a client to see that client’s sessions.
3. Click the Sessions tab.
   

Viewing user sessions

Procedure

1. Click Users in the menu.
2. Click a user to see that user’s sessions.
3. Click the Sessions tab.
   

Revoking active sessions

If your system is compromised, you can revoke all active sessions and access tokens.

Procedure

1. Click Sessions in the menu.
2. From the Actions list, select Revocation.
   

3. Specify a time and date where sessions or tokens issued before that time and date are invalid using this console.
   • Click Set to now to set the policy to the current time and date.
   • Click Push to push this revocation policy to any registered OIDC client with the Keycloak OIDC client adapter.

Session and token timeouts

Keycloak includes control of the session, cookie, and token timeouts through the Sessions and Tokens tabs in the Realm settings menu.

*The following logic is only applied if persistent user sessions are not active: For idle timeouts, a two-minute window of time exists that the session is active. For example, when you have the timeout set to 30 minutes, it will be 32 minutes before the session expires. This action is necessary for some scenarios in cluster and cross-data center environments where the token refreshes on one cluster node a short time before the expiration and the other cluster nodes incorrectly consider the session as expired because they have not yet received the message about a successful refresh from the refreshing node.

Offline access

During offline access logins, the client application requests an offline token instead of a refresh token. The client application saves this offline token and can use it for future logins if the user logs out. This action is useful if your application needs to perform offline actions on behalf of the user even when the user is not online. For example, a regular data backup.

The client application is responsible for persisting the offline token in storage and then using it to retrieve new access tokens from the Keycloak server.

The difference between a refresh token and an offline token is that an offline token never expires and is not subject to the SSO Session Idle timeout and SSO Session Max lifespan. The offline token is valid after a user logout. You must use the offline token for a refresh token action at least once per thirty days or for the value of the Offline Session Idle.

If you enable Offline Session Max Limited, offline tokens expire after 60 days even if you use the offline token for a refresh token action. You can change this value, Offline Session Max, in the Admin Console.

When using offline access, client idle and max timeouts can be overridden at the client level. The options Client Offline Session Idle and Client Offline Session Max, in the client Advanced Settings tab, allow you to have a shorter offline timeouts for a specific application. Note that client session values also control the refresh token expiration but they never affect the global offline user SSO session. The option Client Offline Session Max is only evaluated in the client if Offline Session Max Limited is Enabled at the realm level.

If you enable the Revoke Refresh Token option, you can use each offline token once only. After refresh, you must store the new offline token from the refresh response instead of the previous one.

Users can view and revoke offline tokens that Keycloak grants them in the User Account Console. Administrators can revoke offline tokens for individual users in the Admin Console in the Consents tab. Administrators can view all offline tokens issued in the Offline Access tab of each client. Administrators can revoke offline tokens by setting a revocation policy.

To issue an offline token, users must have the role mapping for the realm-level offline_access role. Clients must also have that role in their scope. Clients must add an offline_access client scope as an Optional client scope to the role, which is done by default.

Clients can request an offline token by adding the parameter scope=offline_access when sending their authorization request to Keycloak. The Keycloak OIDC client adapter automatically adds this parameter when you use it to access your application’s secured URL (such as, http://localhost:8080/customer-portal/secured?scope=offline_access). The Direct Access Grant and Service Accounts support offline tokens if you include scope=offline_access in the authentication request body.

Keycloak will limit its internal cache for offline user and offline client sessions to 10000 entries by default, which will reduce the overall memory usage for offline sessions. Items which are evicted from memory will be loaded on-demand from the database when needed. See the server configuration guide to change this default.

Transient sessions

You can conduct transient sessions in Keycloak. When using transient sessions, Keycloak does not create a user session after successful authentication. Keycloak creates a temporary, transient session for the scope of the current request that successfully authenticates the user. Keycloak can run protocol mappers using transient sessions after authentication.

The sid and session_state of the tokens are usually empty when the token is issued with transient sessions. So during transient sessions, the client application cannot refresh tokens or validate a specific session. Sometimes these actions are unnecessary, so you can avoid the additional resource use of persisting user sessions. This session saves performance, memory, and network communication (in cluster and cross-data center environments) resources.

At this moment, transient sessions are automatically used just during service account authentication with disabled token refresh. Note that token refresh is automatically disabled during service account authentication unless explicitly enabled by client switch Use refresh tokens for client credentials grant.