Skip to main content
Skip table of contents

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 Custom custom branding


ParameterDefault valueRemarks

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:

FieldDefault valueRemarks
Keep session alive3 minutesThe 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 limit1440 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.