Configure session handling

A proper session handling contributes to security and enhances user experience.

In the application.yml, uncommented parameters (with a #) need to be out-commented to become active configuration.

Involved components

All requests from the user client to the censhare Server are routed through the Cloud Gateway.

 When logging in to censhare, the user is authenticated at Keycloak. With successful authentication, the censhare Server creates an active session with the respective user permissions. An active user session requires a valid JWT Token that is generated by Keycloak. This token can be shared across all services (Keycloak, Cloud Gateway, and censhare Server).

When the user logs out, or a connection is lost, or the session times out, the session gets terminated, and JWT token gets invalidated. The user is redirected to the login page and must authenticate again. 

Basic configuration

Without this configuration, your censhare applications won't work properly. Basic configuration includes log out and start pages. They guide the user how to log in back to the censhare Web Client enabling users to continue their work after the session has been terminated. Such configuration needs to be performed in the configuration file for the Cloud Gateway as well as in your Keycloak realm. 

Cloud Gateway

In the core-cloud-gateway/application.yml file on your host, you need to enter the following parameters:

Parameter	Default value	Remarks
cg.censhareLogoutUrl	http://CENSHARE-SERVER-HOST:PORT/forward/rest/service/webserver/rest/csLogout	Adjust the CENSHARE_SERVER_HOST:PORT accordingly. The default port for non-SSL access is 9000.  If Keycloak, Cloud Gateway and censhare Server are installed on the same host, the entry localhost:9000 works. However, we do not recommend to use localhost entries. Instead, use an alias for the censhare Server.

Keycloak

In Keycloak, you must configure the correct redirect URLs to ensure that the users are redirected back to the login page when their session has expired, before they can resume their work in censhare. For more information, see Configure Keycloak.

Secure session handling

Overview and purpose

Secure session handling is targeted against network instabilities and malicious attacks. Although optional for a baseline functioning of the censhare system, the proposed configuration should be considered as mandatory since it is crucial for security and user experience. More specifically, it fulfils two main purposes, preventing that:

• Someone else uses an already opened but idle user session for malicious intents.

• User session is interrupted and the user has to re-login and/or loses their work.

Main configuration features that enable secure sessions are the following:

• Closing idle sessions

  • Timeouts ensure that the session is closed if the user is idle for some time. 

  • Back-channel logout propagation logs out the user from all components and services (that are configured accordingly) after being logged out from just one. 

• Keeping active sessions alive

  • Fresh token propagation

• CGW re-tries serves both purposes: CGW repeats its requests a few times (as long as you specified). This should ensure that the idle or closed sessions are properly closed, and that the active sessions are not closed "unintentionally". 

To make these features work, you need to configure both CGW and Keycloak. The present section explains how. 

Timeouts

You can configure timeouts that determine when a web session is closed due to inactivity via the client connection, lost client connection, or closing the web client. The session termination upon these events ensures that the session is properly disconnected. By default, active users are required to periodically reconnect and authenticate. This prevents session hijacking attempts. It also helps to reduce the amount of memory that is used when a large number of idle sessions are open simultaneously. 

You need to keep in mind that the fact that the session timed out is not alone sufficient for closing this session and logging out the user. The censhare Server needs to check for expired sessions proactively, and the session needs to be terminated both in the Server and in Keycloak. 

Your RPM installation arrives with the default values for secure session handling. However, you might want to change them in accordance with your needs and any specifics of your setup.

Cloud Gateway configuration for timeouts

To change the configuration of the Cloud Gateway, edit the core-cloud-gateway/application.yml file on your host:

Parameter	Default value	Remarks
cg.expiredSessionFullLogout	true	Ensures that the session is terminated from censhare Server and Keycloak. If set to false, Keycloak keeps the session alive.
cg.sessionTimeoutSec	1800 (equals 30 mins)	To avoid waiting 30 minutes for each attempt, adjust this value according to the live span of the access token and the refresh token. Ensure that: The session timeout value in Keycloak is higher than the cg.sessionTimeoutSec value The token live cycle value is lower than the cg.sessionTimeoutSec value For more information, see the Keycloak documentation.
cg.sessionCheckIntervalMs	60000 (equals 1 minute)	The interval, in which censhare checks for expired sessions. Decreasing this value below the threshold of 10000 can affect the performance of the application!
cg.maxSessions	10000	The maximum number of parallel sessions allowed in the Cloud Gateway. Normally, one session per user can be calculated, but it is possible that one user has multiple active sessions simultaneously.  Increasing this value can affect the performance of the application!
cg.useSecureSessionCookie	true	Sets a session cookie with a security attribute. To check: Log into censhare Web with "https://" and use the browser tools to ensure that the SESSION cookie has a Secure attribute.

Keycloak configuration for timeouts

In Keycloak, you need to enter the following values. Keep in mind the limitations specified in the table below.

Access token lifespan can also be set on the client level. This is even necessary in case of the CI HUB integration.

 Optional | Handling network instabilities

To eliminate consequences of any network instabilities, e.g., interrupted TCP connections, as well as other causes of random disconnections, we implemented robust session handling for your censhare system. 

CGW re-tries configuration

You can additionally configure the Cloud Gateway to re-try its requests. This will be affective for any kinds of outgoing requests originating in CGW, incl. but not limiting to for logging out expired sessions. 

Fresh token propagation configuration (in CGW)

As already mentioned, if you continue using default values for session termination, this will force your users to re-login from time to time. Another reason why users may be kicked off the web Client is unstable network. It is possible to change this and make the session more user-friendly by avoiding session terminations. The diagram below illustrates  a fresh token flow. The fresh token "tells" application components that the current session should be kept active.

In this case, the timed out sessions will still be terminated, but no faulty session termination will happen. 

Each component must be subscribed to the fresh token flow to be able to "listen" to it.

It is mostly important to add the actual censhare Server as the fresh token listener. Other services are optional. You can also modify the default value for how often the new fresh token should be propagated. 

Keep in mind, that these parameters need to be aligned with the parameters for session termination, namely, cg.sessionCheckIntervalMs and cg.sessionTimeoutSec.

Optional | Back-channel logout propagation

From the user perspective

Please make sure that your users are informed about this feature to avoid any lost work. 

When the user logs out from one application or service, they will be logged out from all other services and applications. Indeed, this feature is a sophisticated instrument and needs to be properly configured for this. The configuration is done in the application.yml file of the Cloud Gateway. 

Technical Background

Starting from the Cloud Gateway version 3.1.8., we added a back-channel logout handler that propagates the logout signal from Keycloak to all services that are subscribed to such notification.

Enable and configure back-channel logout propagation

There are several configuration steps that must be done to activate this feature, in the CGW application.yml and in Keycloak.

Cloud Gateway

Please make sure you added all services and applications where you want the single sign out to be effective. 

Parameter	Default value	Remarks
Parameters for backchannel logout (under  spring.cloud.gateway.routes:)	- id: censhare5_backchannel_logout uri: http://CLOUD-GATEWAY-HOST:PORT predicates: - Path=/backchannel/logout filters: - BackchannelLogout	You need to set the correct uri: attribute of the CGW route definition. You can set censhare5_backchannel_logout to any value, this is just an id to differentiate between multiple logout routes/applications.
cg.logoutListeners		A valid URL to the existing endpoint of another service that will receive a call each time when the user performs a logout: personally or enforcedly by the Administrator from the Keycloak Admin console.  To add more than one listener, add multiple URLs here in an array, one per each listener. Please make sure to use ", " as a separator between URLs.

Keycloak

E.g. for Keycloak 21 these settings must be set up separately for each client. Follow these steps:

• Navigate to the "Clients" section

• Select the proper client 

• On the "Settings" tab, scroll to the "Logout settings" section:

  • Put a valid URL into the "Backchannel logout URL" following this template:
    http://CLOUD-GATEWAY-HOST:PORT/backchannel/logout

  • The "Backchannel logout session required" must be ON

As a result of this configuration, the handlers added at step 2 will receive a logout token on each user logout, and the corresponding service will process this signal according to its logic.

More details for configuring the back-channel logout can be found in the Keycloak official documentation.

Enable logging for the back-channel logout propagation

It is possible to observe CGW logs related to propagation of logout token - one should add the following in the application.yml and restart the CGW afterwards:

logging.level.com.censhare.core.cloudgateway.BackchannelLogoutGatewayFilterFactory:TRACE
logging.level.com.censhare.core.cloudgateway.LogoutProcessor:TRACE
logging.level.com.censhare.core.cloudgateway.LogoutSignalSender:TRACE

Web session limits for internal API connections

Configuration

On the censhare Server, you can configure the web session limits for internal API connections. 

We strongly recommend not to change the default settings for web session timeouts! If you do so, test your configuration thoroughly to ensure that they work in combination with the Configure session handling#Cloud Gateway settings! 

The following default setting can be changed in the censhare Admin Client, under Configuration/Services/API:

Monitoring sessions

You can monitor session behavior in the censhare system asset and censhare log files. Check session creation/cleaning to analyze creation trends and detect irregular numbers of session creation. See also Configure the system asset - censhare Web

Monitor Keep sessions alive timeouts

See a sample log with Keep alive timeout set to 2 minutes. After closing the browser window, the session is closed after 2 minutes:

Monitor Session inactivity limit timeouts

See a sample log with a session inactivity limit set to 5 minutes. A session cleaner closes the session after 5 minutes of session inactivity.