Configure session handling

Session handling comprises the internal censhare Server session, Keycloak and Cloud Gateway configuration.

Introduction

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. All requests from the user client to the censhare Server are routed through the Cloud Gateway. For a secure session handling, all involved components must be accordingly configured.

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. 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.

An active user session requires a valid JWT Token. This token can be shared across all services (Keycloak, Cloud Gateway, and censhare Server). When a session terminates after the user logs out, when a connection is lost, or after the session times out, the JWT token is invalidated. The user is redirected to the login page and must authenticate again.

Configuration

Cloud Gateway

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

If you want to use a custom-branded censhare Web, see also the necessary configuration of the application.yml file in (2022.1) Create custom branding.

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.
cg.censhareStartPageUrl	http://WEB-CLIENT-HOST:PORT/censhare5/client	Adjust the CENSHARE_CLIENT_HOST:PORT accordingly. The default port for non-SSL access is 9000. For the standard branding, leave the /censhare5/client part as is. If you use a custom branding, change according to the URL to access the custom branding.
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!
Access Token Lifespan ( Keycloak ) (Realm Setting -> Realm -> Token tab)	300000 (equals to 5 minutes - usually, customizable)	The maximum time before access token expired.This value recommended to be short relative to the SSO timeout. For more information, see the Keycloak documentation.
SSO Session Idle ( Keycloak ) (Realm Setting -> Realm -> Token tab)	cg.sessionTimeoutSec + cg.sessionCheckIntervalMs + Access Token Lifespan	Setting session on Keycloak The SSO Session Idle is higher than the cg.sessionTimeoutSec value The SSO Session Idle is higher than the cs.sessionCheckIntervalMs The SSO Session Idle is higher than the Access Token Lifespan cs.sessionCheckIntervalMs must be less than cg.sessionTimeoutSec This formula provide session timeout work regularly. For more information, see the Keycloak documentation.
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

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.

censhare Server

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 Cloud Gateway settings!

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

Field	Default value	Remarks
Keep session alive	3 minutes	The maximum time to keep a web session alive after users have closed all browser windows without any user log out or the browser connection has been lost.
Session duration limit	1440 minutes (equals 1 day)	The maximum idle time of a web session without any user activity. After this period, the session is closed by a session cleaner. For security and performance reasons, we recommend selecting an idle time that is not too long. The appropriate minimum value possible depends on the context of the application or tasks.

Timeout behavior with different connection protocols

For details on different connection protocols and their behavior regarding timeouts, see this FAQ.

Monitor web session timeouts

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. For more information, see Monitoring.

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.