Session management
The session coordinator is responsible for managing the session lifecycle using the local and remote session stores.
The two key phases or states of the nevisAuth session are:
- Unauthenticated session (also mentioned as initial session)
- Authenticated session
The authentication engine uses two different inactivity timeouts depending on the authentication phase. The session coordinator enforces the current inactivity timeout and an absolute session lifetime.
The different timeouts are:
-
initial inactivity timeout
The user is performing a multistep authentication and has not yet fully established an authenticated session. This timeout is compared against the last access time.
-
established inactivity timeout
The user has successfully logged in. This timeout is compared against the last access time during the authentication process.
-
absolute session timeout
The session cannot be valid longer than the specified timeout. This timeout is compared against the creation time. This timeout is overridden by the time-to-live attribute of the TokenAssembler, if the session was created via the AuthEngine.
When nevisAuth does not receive any session "hits", the established inactivity timeout needs to be equal to the absolute session timeout (the longest acceptable global session lifetime). Session hits may be performed by any client that gets requests from the authenticated user.
As nevisProxy instances know about every request a user is sending, the global authentication session is usually controlled by nevisProxy instances. The above session timeouts therefore are only relevant for limiting unauthenticated sessions and for clearing sessions where no termination notifications from nevisProxy instances arrive.
A simple session store configuration, in conjunction with the timeouts enforced by the AuthEngine, looks as follows:
<SessionCoordinator
sessionInitialInactivityTimeout="600"
sessionInactivityTimeout="28800"
sessionInitialMaxLifetime="1200"
sessionMaxLifetime="28800"
sessionIdRandomBytes="32">
<LocalSessionStore
maxSessions="100000"
reaperPeriod="60" />
<TokenAssembler name="default">
<Selector default="true"/>
<TokenSpec version="CSSO-1.0" ttl="28800" algorithm="SHA256withRSA">
...
</TokenSpec>
<Domain name="SSO1" default="true"
reauthInterval="0"
inactiveInterval="1800">
...
</Domain>
This example enforces:
- A maximum inactivity timeout to perform a login step of 600 seconds (only relevant for stateful multistep authentications), to be enforced by nevisAuth.
- The "screen lock" timeout (i.e., the inactivity timeout, that triggers a reauthentication on an existing session with some minimal credential requirements) is disabled.
- An inactivity timeout of 1800 seconds (i.e., the reverse proxy or client terminates the session and notifies nevisAuth, if the user does not send any requests during this period), to be enforced by the nevisProxy. Note that this setting only applies if the InactivePolicy of the IdentityCreationFilter is set to "global".
- A maximum session lifetime of 1200 seconds for Unauthenticated sessions.
- A maximum session lifetime of 28800 seconds for authenticated sessions, enforced by the lifetime of the security token. This is also the maximum lifetime for the authentication state within the session in nevisProxy.
Re-authentication (lock/unlock) can be enabled by setting reauthInterval to a value higher than 0 (zero). However, note that spontaneously locking sessions during application usage is non-trivial for many modern web applications and compatibility with this behavior should therefore be examined for each application.
SessionCoordinator configuration
The following list provides an overview of the SessionCoordinator configuration attributes for the two main groups regarding session management: lifetime and identifier.
-
sessionInitialInactivityTimeout(Integer, seconds, optional, 600)Default value:
600The session's initial inactivity timeout, which is raised to inactivityTimeout as soon as the initial login is completed. A user needs to perform a login step within this period. Otherwise, the user is forced to start over.
-
sessionInactivityTimeout(Integer, seconds, optional, 28800)Default value:
28800The session's inactivity timeout. When nevisAuth does not get any session events during this period, the session is killed.
Kill the session if: lastAccessTime + inactivityTimeout
<=nowcautionThis attribute must have the same value as the maxLifeTime attribute.
-
sessionInitialMaxLifetime(Integer, seconds, optional, 1200)Default value:
1200The session's initial absolute timeout (applies to unauthenticated sessions), which is raised to maxLifetime as soon as the initial login is completed (e.g. when the authentication flow reaches
AUTH_DONE). A user needs to complete the login within this period. Otherwise, the user is forced to start over. -
sessionMaxLifetime(Integer, seconds, optional, 28800)Default value:
28800The session's absolute timeout. (applies to authenticated sessions)
Kill the session if:
creationTime + maxLifeTime <= nowThis attribute must have a value that is greater than or equal to the maximum of all TokenAssembler's ttl attribute because expired SecTokens already define the maximum lifetime of an authentication session.
-
sessionIdRandomBytes(Integer, byte, optional, 32)Default value:
32The session generates session IDs that are being used as global session identification and are part of the SecToken. The ID is generated by base64 encoding the specified number of true random bytes. The default of 16 bytes therefore represents 128 true random bits. The session ID length therefore is: sessionIdRandomBytes * 4 / 3 + $instance name length$
infoThe session ID inside nevisAuth is prefixed with the nevisAuth instance ID to distinguish sessions generated by different nevisAuth instances.
-
sessionIdPreGenerate(Boolean, optional, true)Default value:
trueUnder normal circumstances, a session receives its final ID only after the state
AUTH_DONEis reached for the first time. At this point, the previous (temporary) session ID is changed to a randomly generated ID as configured usingsessionIdRandomBytes.Under some circumstances, it is desirable to know the final session ID during the authentication process. This can be achieved by setting
sessionIdPreGenerateto "true". The session variablech.nevis.esauth.sess.id.pregeneratewill then be filled with the future session ID upon creation of the session.
Choosing the session lifetime
It is recommended for nevisAuth and nevisProxy to have a same session lifetime. With this configuration, nevisAuth and nevisProxy sessions will be automatically in sync.
In case if different session lifetimes are configured in nevisAuth and nevisProxy the sessions between those components must be kept in sync. This synchronization can be enabled by setting EnablePollTerminatedCalls to true in the esauth4Connector in nevisProxy. In this usecase also the syncPullInitial must be enabled in the RemoteSessionStore in nevisAuth.
Note that as nevisProxy is coordinating the sessions at a higher level. Depending on the nevisProxy configuration RecheckAuthentication of the IdentityCreationFilter, nevisProxy might not contact nevisAuth again once a session becomes authenticated. This does not affect the EnablePollTerminatedCalls.
On the top of the session lifetime configuration the secToken also plays into the lifetime of a session. When the secToken expires the session practically ends. Therefore, the ttl of the TokenSpec in the TokenAssembler should match the configured session lifetimes in the SessionCoordinator and nevisProxy settings.
Some AuthStates, such as AccessTokenConsumer, cap the session lifetime and the SecToken ttl by setting the session attribute ch.nevis.session.notOnOrAfter. nevisProxy does not adapt its session timeouts to this limit. It only applies the SectokenExpireStrategy of the IdentityCreationFilter when a request accesses the session.
Additionally, the inactiveInterval attribute of the Domain element can be used to instruct nevisProxy to enforce an inactivity timeout on the nevisProxy level.
Terminated session polling
As mentioned before different session lifetime configuration in nevisProxy and nevisAuth requires syncrhonization.
An other use-case where nevisProxy is not aware of session modifications done in nevisAuth is when you use a nevisAuth REST service or nevisAdapt to kill sessions in nevisAuth. In such case you should set EnablePollTerminatedCalls to true in the esauth4Connector in nevisProxy to synchronize sessions.
Technically nevisProxy calls nevisAuth using the poll_terminated_sessions soap operation where nevisAuth will wait for maximum 30 seconds to respond. In case there are session terminations initiated by the caller nevisProxy instance, the reponse with terminated sessions will be returned immediately. In case there are no expired sessions, nevisAuth will send an empty response once 30 seconds passed. nevisProxy will remove the received sessions itself and it will reconnect again to listen for more sessions to be removed.
Terminated session polling assumes that whichever nevisProxy node consumes a termination notification is also the node responsible for enforcing it. This holds when nevisProxy resolves every session from a shared database, for example with the PostgreSQLSessionStoreServlet or MySQLSessionStoreServlet. It does not hold when nevisProxy nodes rely on a local session cache, such as with the MultiLevelSessionStoreServlet: the first node that polls and receives the termination event acknowledges it as handled, even if that node does not hold the session locally. In such case, the node actually serving the active session never receives the event, so the session remains active. For clustered nevisProxy deployments that require reliable backend-triggered session termination, use a remote-only session store instead of the hybrid MultiLevelSessionStoreServlet.
Session indexing
nevisAuth can index sessions by session attributes. With the index, nevisAuth finds the sessions of a user without reading all sessions. The session management API, the ThrottleSessionsState, and OpenID Connect logout use the index. Enable indexing by adding the SessionIndexing element to the SessionCoordinator.
-
attributes(String, comma-separated list of session attribute names, optional,ch.nevis.session.loginid)Default value:
ch.nevis.session.loginidThe session attributes to index. nevisAuth stores the indexed values as SHA-256 hashes. If you set
attributesand need the login ID index, listch.nevis.session.loginidas the first entry. nevisAuth uses the first entry for lookups without an attribute name.
OpenID Connect logout requires the following indexed attributes:
ch.nevis.session.oidc.sidandch.nevis.session.oidc.subfor the end-session service (RP-initiated logout).ch.nevis.session.rp.oidc.sidandch.nevis.session.rp.oidc.subfor the back-channel logout service.
<SessionIndexing attributes="ch.nevis.session.loginid,ch.nevis.session.oidc.sid,ch.nevis.session.oidc.sub,ch.nevis.session.rp.oidc.sid,ch.nevis.session.rp.oidc.sub"/>
Consider the following points:
- If you enable indexing or add an attribute, nevisAuth does not index the sessions that already exist. Lookups by attribute do not find these sessions until they end. For the upgrade to nevisAuth 9.2611, see Session index in the database.
- All nevisAuth instances that share a remote session store must use the same
SessionIndexingconfiguration. - With a remote session store, nevisAuth also writes the hash of the first entry of
attributesto the columnSESSION_INDEX, for earlier versions of nevisAuth. During a rolling upgrade from an earlier version, index only the attribute that the earlier version indexes. See Upgrading nevisAuth instances that share a session database. - nevisAuth checks that the attributes that a feature queries are indexed. The ThrottleSessionsState fails at startup if its
queryAttributeis not indexed. The session management API responds with HTTP 400 ifattributeNameis not indexed. The end-session service and the back-channel logout service reject requests if their attributes are not indexed. - Each lookup uses one indexed attribute. For example, the session management API finds sessions by one attribute and value per request.
- With a remote session store, nevisAuth stores the index in the table
session_index. The schema is created with the nevisauth-dbschema image.
The attributes attribute and attributeMapping of earlier versions are removed. For the migration, see Migrating to nevisAuth 9.2611.
Local session store
nevisAuth uses an in-memory session store to hold authentication sessions. This session store uses an inactivity timeout mechanism with a session reaper mechanism to get rid of expired sessions. The session store has an upper limit to prevent uncontrolled session creation and heap space growth.
The use of the LocalSessionStore is required for the operation of nevisAuth, it cannot be disabled.
The following list provides an overview of the LocalSessionStore configuration attributes.
-
maxSessions(Integer, maximum number, optional, 100000)Default value:
100000The maximum number of session entries allowed. This parameter is the upper limit for parallel global authentication sessions. If the reverse proxy is solely using nevisAuth as an authentication infrastructure, only this number of authenticated clients are able to pass the reverse proxy at a time.
Note that once the maximum amount is reached no new session will be created until an existing session expires. To detect this situation, and to get a warning before the limit is reached, see Monitoring of the local session store.
-
reaperPeriod(Integer, seconds, optional, 60)Default value:
60The reaper thread locks the session cache regularly (defined by this period) to clean up expired sessions.
-
reaperEvictSyncedSessions(Boolean, optional, true)Default value:
trueWhen enabled, the local session reaper evicts sessions that have been successfully synchronized to the remote session store, reducing the memory footprint of the local session store. Only relevant when a
RemoteSessionStoreis configured.
Monitoring of the local session store
When the local session store reaches maxSessions, nevisAuth cannot create new sessions until existing sessions expire or are invalidated. Requests that require a new session fail during this time. Monitor the number of sessions in the local session store to detect a growing session count before the limit is reached.
nevisAuth provides the following indicators:
| Indicator | Source | Warns before the limit is reached |
|---|---|---|
| Session reaper log | INFO message in the LocalSessionStore log category after each reaper run | Yes |
| Limit exceeded log | ERROR message in the LocalSessionStore log category | No |
| Readiness endpoint | localSessionStore check of the readiness endpoint | No |
Session reaper log
After each run, the session reaper writes the current number of sessions to the LocalSessionStore log category on level INFO:
Session reaper: full scan time: 15ms; used sessions: 81250 -> 80730; victims: 520; free mem: 412345678; total mem: 1073741824
The values after used sessions: are the number of sessions before and after the reaper run. The second value is the number of sessions that remain in the local session store. The reaper runs every reaperPeriod seconds. The free mem and total mem values are the free and the currently allocated heap memory of the Java virtual machine (JVM) in bytes.
To get a warning before the limit is reached, configure an alert in your log management system. Trigger the alert when the second used sessions value exceeds a threshold, for example 80 percent of the configured maxSessions.
The default logging configuration writes the LocalSessionStore category on level INFO. If you set the category to WARN or higher, the session reaper log is not written. For more information, see Logging configuration.
Limit exceeded log
When a new session cannot be created because the local session store is full, nevisAuth writes the following message to the LocalSessionStore log category on level ERROR:
The number of MaxSessions (100000) has been exceeded.
The message is written for every rejected session creation. Use it to raise an alert when the limit is reached.
Readiness endpoint
The localSessionStore check of the readiness endpoint reports DOWN when the local session store is full. With api-version 2.0, the readiness endpoint then returns the HTTP status code 503. If you use the endpoint as a Kubernetes readiness probe, Kubernetes stops routing traffic to the instance. The check reports UP again as soon as the number of sessions drops below maxSessions, for example after the session reaper removed expired sessions. The check does not warn before the limit is reached.
The management endpoints are disabled by default. To enable them and to configure the probes, see Management Endpoints.
Remote session store
Typical reasons for storing sessions remotely are, to provide resilience, and to share sessions between nevisAuth instances.
Whenever a session event is fired, for example when a session is deleted or updated, all session listeners are informed about the recent change. As a listener the remote session store will attempt to synchronize the current state of the session with the remote session database.
The RemoteSessionStore element encapsulates the configuration options for the synchronization features and the cleanup of expired sessions. It references a database connection pool for the database connection. The remote session store is enabled by defining the RemoteSessionStore element. To disable it, either remove the element or comment it out.
By default, setting both authenticated and unauthenticated sessions are synchronized. This can be changed, so only authenticated session are stored.
Session synchronization
The remote session store shares the sessions with the database in an ignorant way, even if the synchronization failed, the authentication flow will not be disrupted.
In case syncFailRetryCount is configured the synchronization will be attempted again the set number of times. Related configuration option is the syncFailRetryPeriod, in case it is configured to be greater than 0 the future retries of the synchronization will be handled with a delay period asynchronously, because of this, the authentication flow can continue without waiting for the retry.
Note, that it doesn't make sense to configure this retry delay period to be high in environments where multiple nevisAuth instances are used as the continued authentication flow can end up on the other instance which doesn't yet have state of the session.
Relation between the local and remote session store
When remote session store is not configured, the local session store acts as the "single source of truth".
In case the remote session store is configured, the local session store behaves the same, however the SessionCoordinator operates in a way that the overall behaviour changes. The local session store is only used for the following purposes:
- Cache sessions during the evaluation of an authentication step.
- Keep nevisProxy informed about expired sessions. (polled terminated sessions)
nevisAuth keeps track, if a session has been synchronized to the remote session store or not. In case the synchronization fails, the authentication flow is not disrupted. The session remains in the local session store as a not synchronized session. For those sessions the source of truth will always be the local session store, once all retries are exhausted.
Stateless behaviour
Default configuration values in the RemoteSessionStore are set to make nevisAuth stateless with some resilience in case there is a synchronization issue to the remote session store.
Configuration
The following table provides an overview of the component's configuration properties.
-
provider(String, required, "jdbc")Default value:
jdbcSpecifies the provider handling synchronization connections.
Only
jdbcprovider is supported, synchronizing to MariaDB or PostgreSQL database. -
connectionPoolRef(String, required, -)The name of the
<DatabaseConnectionPool>that the remote session store uses to connect to the database. The connection pool contains the JDBC URL, the credentials, and the pool settings. For more information, see Database connection pools. -
syncPullInitial(Boolean, optional, false)Default value:
falseConfigures if all sessions should be pulled from the database on nevisAuth startup. This can be disabled if the terminated session polling is disabled in nevisProxy. The loading of sessions happens in the background in a non-blocking way.
-
syncFailRetryPeriod(Integer, msec, optional, 100)Default value:
100This period is used to re-queue a session after a failed synchronization. The period should allow a server to recover from some temporary problem.
-
syncFailRetryCount(Integer, optional, 1)Default value:
1This counter defines how many retries should be performed after a failed synchronization. The counter is decremented with each try.
-
reaperPeriod(Integer, seconds, optional, 60)Default value:
60The period in seconds in which to execute the run method of the RemoteSessionReaper.
-
reaperTimeoutTolerance(Integer, seconds, optional, 10% of max session lifetime)Default value:
calculated: 10% of max session lifetimeThe tolerance (in seconds) is added to the
ABS_TOvalue of the session. It must ensure that the RemoteSessionReaper is only used to reap remote sessions that were not killed explicitly. Changing it will not affect existing sessions. -
reaperInitialDelay(Integer, seconds, optional, -)Default value:
reaperPeriodTime elapsed before the first clean up of the remote session store with the RemoteSessionReaper is triggered after startup.
-
reaperThreads(Integer, optional, 1)Default value:
1The number of threads to use to clean up the remote session store with the RemoteSessionReaper.
-
reaperInvalidateSessionBeforeDelete(Boolean, optional, true)Default value:
trueWhen enabled, the remote session reaper loads expired sessions from the database, fires session termination events for each, and then bulk-deletes them from the database. This ensures proper session lifecycle handling for sessions that expire remotely. When enabled, the legacy connector-level reaper is disabled and all reaping is handled by the
RemoteSessionStore. SeereaperMaxSessionsPerRunandreaperBatchSizeInRunto tune the reaper behaviour. -
reaperMaxSessionsPerRun(Integer, optional, 5000)Default value:
5000Maximum number of expired sessions to process per reaper run. Only used when
reaperInvalidateSessionBeforeDeleteis enabled. -
reaperBatchSizeInRun(Integer, optional, 500)Default value:
500Number of sessions loaded and processed per batch within a reaper run. Must be between 1 and 1000. Smaller batches reduce memory pressure but require more database round-trips. Only used when
reaperInvalidateSessionBeforeDeleteis enabled. -
storeUnauthenticatedSessions(Boolean, optional, true)Default value:
trueWhen disabled, only authenticated session are stored in the remote session store.
Session eviction scenarios
The reaperEvictSyncedSessions attribute on LocalSessionStore and reaperInvalidateSessionBeforeDelete attribute on RemoteSessionStore work together to control how sessions are retained in memory and how expiry is handled. Three relevant combinations exist:
| Mode | reaperEvictSyncedSessions | reaperInvalidateSessionBeforeDelete |
|---|---|---|
| Consistency (default) | true | true |
| Performance | true | false |
| Legacy | false | false |
Consistency (both true, default): The local reaper evicts synced sessions from memory. When sessions expire in the remote store, the remote reaper fires session termination events before bulk-deleting them from the database. This keeps nevisProxy informed via polled terminated sessions and ensures the complete session lifecycle is observed. Recommended when running multiple nevisAuth instances with a shared remote session store and terminated session polling is enabled.
Performance (reaperEvictSyncedSessions=true, reaperInvalidateSessionBeforeDelete=false): The local reaper evicts sessions that have been synced to the remote store, reducing the in-memory footprint. However, the remote reaper still deletes expired sessions directly from the database without firing termination events. As a result, nevisProxy is not notified of remotely expired sessions, and no session lifecycle events are generated for them. Suitable only when terminated session polling in nevisProxy is not required.
Legacy (both false): Sessions synced to the remote store remain in the local in-memory store for their full lifetime. The remote reaper deletes expired sessions from the database directly without firing termination events.
Remote SQL session database setup
The database schema of the remote session store is created and migrated with the nevisauth-dbschema image. The image contains the Flyway migrations for all nevisAuth tables, including the remote session store, the SqlOOCDService, and the tables used by the AuthorizationServer. In Kubernetes-based deployments, nevisOperator runs the image for you, or your database administrator runs it as a migration job. For the available approaches and the required database users, see Database Management.
The automatic table creation by nevisAuth (connectionAutomaticDbSchemaSetup, connectionSchemaUser, and connectionSchemaPassword) is deprecated since nevisAuth 9.2611.0 and is planned for removal in the May 2027 Rolling Release. This follows the move to Kubernetes and SaaS deployments, where the dbschema images manage the database schema, and is in line with the Classic Deployment retirement. The automatic table creation does not apply schema changes to existing tables. Use the nevisauth-dbschema image to create and migrate the database schema, and set connectionAutomaticDbSchemaSetup to "false".
nevisAuth synchronizes the session properties into the table TNSSA_AUTH_SESSION_CACHE. Sessions that expired in the database are not resynchronized to a nevisAuth instance. Instead, the remote session reaper removes them regularly. The user configured in connectionUser only requires SELECT, INSERT, UPDATE, and DELETE access rights on the tables.
MariaDB time zone prerequisite
nevisAuth sets the time zone of each MariaDB database connection to UTC to avoid issues during daylight saving time switches. This requires the time zone tables of the MariaDB server to be loaded. This is a database server setting and is not covered by the nevisauth-dbschema image. If SELECT * FROM mysql.time_zone_name; returns no rows, ask your database administrator to load the time zone tables, for example with mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql -p.
Session store example use-cases
Short living sessions where resilience is not important
The simplest and best performing configuration for short-lived sessions with no session sharing.
<SessionCoordinator
...>
<LocalSessionStore
maxSessions="100000"/>
Multiple nevisAuth instances
In case you would like to share sessions between multiple nevisAuth instances therefore synchronization should be done to a database immediately to have most up-to-date information. To achieve stateless behaviour, enable storing of unauthenticated sessions.
<ConnectionPools>
<DatabaseConnectionPool name="SessionDb"
connectionUser="nss_auth"
connectionPassword="nss_auth"
connectionUrl="jdbc:mariadb://localhost:3306/NSS"
connectionAutomaticDbSchemaSetup="false"/>
</ConnectionPools>
<SessionCoordinator
...>
<LocalSessionStore
maxSessions="100000"/>
<RemoteSessionStore
provider="jdbc"
connectionPoolRef="SessionDb"
syncPullInitial="false"
syncFailRetryPeriod="100"
syncFailRetryCount="1"
storeUnauthenticatedSessions="true"/>
Multiple nevisAuth instances with resilience
More resilience can be achieved by using a replicated MariaDB setup and increasing retry failure. Note that increasing the rerty period and number will have some affects on memory usage in case of high load and prolonged syncronization issues.
<ConnectionPools>
<DatabaseConnectionPool name="SessionDb"
connectionUser="nss_auth"
connectionPassword="nss_auth"
connectionUrl="jdbc:mariadb:sequential//host-db1:3306,host-db2:3306/NSS"
connectionAutomaticDbSchemaSetup="false"/>
</ConnectionPools>
<SessionCoordinator
...>
<LocalSessionStore
maxSessions="100000"/>
<RemoteSessionStore
provider="jdbc"
connectionPoolRef="SessionDb"
syncPullInitial="false"
syncFailRetryPeriod="200"
syncFailRetryCount="3"
storeUnauthenticatedSessions="true"/>
Configuring Resilient Session Sharing with MariaDB
This chapter is about resilience towards outages of session sharing database nodes, which differs from resilience towards failures of nevisAuth instances. To achieve resilience towards failures of nevisAuth instances, configure two nevisAuth instance addresses in nevisProxy. Such a configuration enables failover to the second nevisAuth instance if nevisProxy cannot connect to the first nevisAuth instance. For more information, see the nevisProxy reference guide (InetAddress parameter of the HttpConnectorServlet).
Resilience to Database Instance Outage
This chapter explains how to set up two MariaDB instances for session sharing with replication . The advantages of this solution are:
- Sharing of sessions between nevisAuth instances and support of nevisProxy for failover for the nevisAuth instances.
- Resilience towards outage of one of the MariaDB instances or its host (e.g., in case of a power outage).
- Resilience towards a failure of the network infrastructure between nevisAuth and one of the MariaDB instances (e.g., in case of a data center outage).
The above statements hold only as long as at least one of the two MariaDB instances is running and reachable. Simultaneous outage of both database instances hinders nevisAuth from sharing sessions.
Known limitations
Most sessions will remain undisturbed in case of a database outage. However, sessions that are undergoing multi-step authentication operations at the moment of the database outage may experience failures. If so, the operations have to be restarted. There are two known reasons for such session failures:
-
Session information loss
If nevisAuth cannot synchronize the session with the remote session store (because the database instance has become unavailable at that precise time), it will possibly read an older state of the same session later on. This will result in the loss of the step-up authorization.
-
Session loss
Session loss may occur in case of recurring loss of connectivity to database instances, or when both database nodes are restarted in short succession. In such a case, nevisAuth may read session information from a database node that does not contain the session yet (because replication from the other node is not finished yet).
Therefore, when restarting database instances for maintenance, we recommend waiting a few minutes between restarting one database instance and stopping the other.
Components involved
This section describes the setup of a fail-safe remote session store for nevisAuth using two MariaDB database hosts with data replication. This setup is tested with MariaDB version 10.3.7.
For a discussion of the nevisProxy connection to the nevisAuth configuration, see the nevisProxy reference guide HttpConnectorServlet section.
The database hosts are called host-db1 and host-db2 in this guide. The replication is enabled in both directions (master/master setup), so that each host is a replication master and a replication slave at the same time. The replication is enabled for a single database called "NSS". Unless otherwise stated, the instructions have to be performed on both hosts.
Implementation overview
Regular clustering solutions provide all fault-tolerant features themselves. Therefore, the connecting application has no clue about the resilient setup. The suggested solution takes a different approach. In this setup, the connecting application becomes part of the resilient setup in terms of configuration.
Two key features to achieve resilience
- Connectivity (MariaDB JDBC driver) - configure a JDBC URL, where you define the DB nodes in priority order:
jdbc:mariadb:sequential//host-db1:3306,host-db2:3306/NSS
-
Data consistency (MariaDB replication) - configure master-to-master replication.
infoReplication is done by the database. The application and the JDBC driver are not aware of it at all.
Overview of database users
The replicated session store is managed by several database users to separate concerns. The creation of the users is explained below.
| Username | Purpose | Required permissions |
|---|---|---|
| nss_auth | Account used by nevisAuth for session management. | ALL PRIVILEGES, on the replicated database to manage sessions. |
| replication_user | Account used by the slave node to log into the master node. | REPLICATION SLAVE, to be able to replicate data. |
| binarylog_user | Account used for binary log management. | SUPER permission, to be able to purge the binary logs. |
Step-by-step setup of the replicated session store
This chapters assumes that the remote session store is already set up based on the section Remote SQL session database setup.
- Creation of the replication user
CREATE USER IF NOT EXISTS replication_user IDENTIFIED BY 'replicationpassword';
GRANT REPLICATION SLAVE ON *.* TO replication_user;
- Creation of the binary logs user
CREATE USER IF NOT EXISTS binarylog_user IDENTIFIED BY 'binarylogspassword';
GRANT SUPER ON *.* TO binarylog_user;
- Configuration of MariaDB service.
To configure the MariaDB service, add the following entries to the file
/etc/my.cnfas super user. The two configuration files (host-db1 and host-db2) differ at some points. The different lines are marked with (*).
-
Configure the MariaDB service on host-db1:
[mariadb]# Enabling binary loglog-bin# The ID of this master (*)server_id=1# The ID of the replication stream created by this master (*)gtid-domain-id=1# The basename and format of the binary loglog-basename=mariadbmasterbinlog-format=MIXED# Setting which tables are replicatedreplicate_wild_do_table="NSS.TNSSA_AUTH_SESSION_CACHE"# Avoiding collisions of primary IDs for tables where the primary ID is auto-incremented# Auto-increment valueauto_increment_increment=2# Auto-increment offset (*)auto_increment_offset=1# Suppressing duplicated keys errors for multi-master setupslave_exec_mode=IDEMPOTENT# Ignoring some data definition language errorsslave-skip-errors=1452, 1062# Suppressing binary logs after a delay regardless of the replication statusexpire_logs_days=1# Maximum number of connectionsmax_connections=1000# Size of each of the binary log files (default: 1GB)max_binlog_size=500M# Enabling writing to the DB in parallel threads for the replicationslave-parallel-threads=10# enabling semi-synchronous replicationrpl_semi_sync_master_enabled=ONrpl_semi_sync_slave_enabled=ON# change to READ COMMITTEDtransaction-isolation=READ-COMMITTED -
Configure the MariaDB service on host-db2:
[mariadb]# Enabling binary loglog-bin# The ID of this master (*)server_id=2# The ID of the replication stream created by this master (*)gtid-domain-id=2# The basename and format of the binary loglog-basename=mariadbmasterbinlog-format=MIXED# Setting which tables are replicatedreplicate_wild_do_table="NSS.TNSSA_AUTH_SESSION_CACHE"# Avoiding collisions of primary IDs for tables where the primary ID is auto-incremented# Auto-increment valueauto_increment_increment=2# Auto-increment offset (*)auto_increment_offset=2# Suppressing duplicated keys errors for multi-master setupslave_exec_mode=IDEMPOTENT# Ignoring some data definition language errorsslave-skip-errors=1452, 1062# Suppressing binary logs after a delay regardless of the replication statusexpire_logs_days=1# Maximum number of connectionsmax_connections=1000# Size of each of the binary log files (default: 1GB)max_binlog_size=500M# Enabling writing to the DB in parallel threads for the replicationslave-parallel-threads=10# enabling semi-synchronous replicationrpl_semi_sync_master_enabled=ONrpl_semi_sync_slave_enabled=ON# change to READ COMMITTEDtransaction-isolation=READ-COMMITTED -
Restart the MariaDB servers on both hosts:
sudo service mariadb restart
Semi-synchronous replication
By default, MariaDB uses asynchronous replication. To reach more consistency, it is recommended using semi-synchronous replication.
The database configurations previously shown enable semi-synchronous replication with the following lines:
rpl_semi_sync_master_enabled=ON
rpl_semi_sync_slave_enabled=ON
MariaDB versions before 10.3.3 require the installation of plug-ins for semi-synchronous replication and are not supported.
Start-up of replication
To start the replication, log in as root into your MariaDB client and run the following commands.
-
on host-db1 (master is host-db2):
CHANGE MASTER TOMASTER_HOST='host-db2',MASTER_USER='replication_user',MASTER_PASSWORD='replicationpassword',MASTER_PORT=3306,MASTER_USE_GTID=current_pos,MASTER_CONNECT_RETRY=10; -
on host-db2 (master is host-db1):
CHANGE MASTER TOMASTER_HOST='host-db1',MASTER_USER='replication_user',MASTER_PASSWORD='replicationpassword',MASTER_PORT=3306,MASTER_USE_GTID=current_pos,MASTER_CONNECT_RETRY=10; -
on host-db1:
START SLAVE; -
on host-db2:
START SLAVE;
Setup of nevisAuth
Most of the nevisAuth configuration is the same for the replicated remote session store as for a single database node. The only difference is the connectionUrl of the database connection pool, with which you configure the two database hosts:
<DatabaseConnectionPool name="SessionDb"
connectionUser="nss_auth"
connectionPassword="nss_auth"
connectionUrl="jdbc:mariadb:sequential//host-db1:3306,host-db2:3306/NSS"/>
You can use the full MariaDB syntax, because nevisAuth hands the value of connectionUrl over to the MariaDB JDBC driver without changes.
For more information on the MariaDB jdbc driver, see the MariaDB documentation.
We recommend using sequential fail-over mode, which will sequentially use the DB nodes in the provided order, one at the time.
The connection handling to a database in nevisAuth is lazy. If one of the database nodes fails, the system continuously moves each connection to the other node. The same happens if the failing database node recovers. That is, the connections are continuously re-initiated to the recovered node as they age out.
Additional setup
Purging the binary logs
With the provided configuration (expire_logs_days=1 in the MariaDB settings), the system will automatically remove the binary logs that are older than one day, even if the logs were not copied by the slave. This prevents the disk of the master node from being filled up in case the slave is down for a long time. The automatic binary log removal takes place when
- the master DB node starts,
- the logs are flushed (nevisAuth does not use this feature),
- the binary log rotates, or
- the binary logs are purged manually (see below).
So binary logs older than one day can exist, if none of the listed actions occurred recently.
Complementary to this expiration feature, MariaDB provides the possibility to manually purge the binary logs. The purge action removes all binary logs that were already copied by the slave. This allows a safe removal of the binary logs on a regular basis. The nevisProxy package is delivered with an adaptable purging script, which is located at: /opt/nevisproxy/sql/mariadb/purgebinarylogs.sh
To use this script,
- copy the script to a location of your choice, and
- adapt it to your configuration.
The script takes care of both DB nodes, so that it only needs to be configured once.
Note that if different database server nodes are used for nevisProxy and nevisAuth, you have set them up separately.
You can schedule the script to run for example once per hour, with a cron job:
0 * * * * /var/opt/nevisproxy/instance/conf/purgebinarylogs.sh # Absolute path of your adapted script
Size the binary logs
The provided configuration (max_binlog_size=500M in the MariaDB settings) allows you to configure the maximal size of the binary log files before rotating. The smaller the size, the more often rotations will occur, which will slow down replication. The advantage is a more efficient purge process. The bigger the size, the less often rotations will occur, but the disk may be filled with old logs.
According to our experiences, a size less than 8K does stop replication completely under heavy load, because the slave keeps rotating the logs.
Troubleshooting
Usually the slave stops the replication if an error occurs. You can check the state of the slave with the following SQL command:
show slave status\G
Note that showing the slave status requires the REPLICATION CLIENT grant.
If the replication has stopped, usually the error that caused it will be displayed. First you should try to fix the error. If this is not possible, you can do a "forced" restart of the slave like this:
-
on the master call (to display the current state of the master):
MariaDB [replicated_session_store]> show master status\G*************************** 1. row ***************************File: mariadbmaster-bin.000131Position: 194630804Binlog_Do_DB:Binlog_Ignore_DB:1 row in set (0.00 sec) -
On the slave (using the values returned by the call
show master status\Gon the master):STOP SLAVE;CHANGE MASTER TOMASTER_LOG_FILE='mariadbmaster-bin.000131',MASTER_LOG_POS=194630804;START SLAVE;
In this way, the system will restart the slave, without replicating to the slave all the sessions that occurred from the moment the replication has stopped until now.
Configuring Resilient Session Sharing with PostgreSQL
Not supported during the experimental phase.
OpenID Connect back-channel logout
The BackChannelLogout element configures OpenID Connect back-channel logout for the nevisAuth instance. For the concept and the supported scenarios, see OpenID Connect back-channel logout and RP-initiated logout.
The element is optional, but the following features require it:
- nevisAuth as OpenID Provider sends logout tokens: an AuthorizationServer sets
openid.bcl.enabledtotrue. Without theBackChannelLogoutelement, the AuthorizationServer fails at startup. - nevisAuth as relying party receives logout tokens: the back-channel logout REST service is configured. The element stores the identifiers of the received logout tokens.
The end-session REST service for RP-initiated logout does not require the BackChannelLogout element.
The REST services verify their configuration when they receive a request, not at startup. If the back-channel logout service has no BackChannelLogout element, or if the required session indexing attributes of a REST service are missing, the requests to the REST service fail.
Place the element in the SessionCoordinator, after RemoteSessionStore:
<SessionCoordinator ...>
<SessionIndexing attributes="ch.nevis.session.loginid,ch.nevis.session.oidc.sid,ch.nevis.session.oidc.sub,ch.nevis.session.rp.oidc.sid,ch.nevis.session.rp.oidc.sub"/>
<LocalSessionStore .../>
<RemoteSessionStore connectionPoolRef="MainDb" .../>
<BackChannelLogout logoutTokenExpiry="120">
<RemoteStore connectionPoolRef="MainDb"/>
<property name="httpclient.tls.trustStoreRef" value="RpTrustStore"/>
</BackChannelLogout>
</SessionCoordinator>
Back-channel logout store
The BackChannelLogout element contains exactly one store element. The store keeps the clients of each session and the identifiers (jti) of the received logout tokens, to detect replayed logout tokens.
-
LocalStoreKeeps the data in the memory of the nevisAuth instance. The data is lost when nevisAuth restarts, and each instance has its own data. Use it only for testing.
-
RemoteStoreKeeps the data in the database. Use it in production, also with a single nevisAuth instance and also if nevisAuth only receives logout tokens. If several instances end the same session at the same time, only one instance sends the logout tokens. If the database is not available at this moment, nevisAuth sends the logout tokens anyway, so an RP can receive the same logout twice. The only attribute is
connectionPoolRef, the name of the database connection pool. With automatic schema setup, nevisAuth creates the tablesnevisauth_oidc_bcl_session_clientandnevisauth_oidc_jti_replay_cache. For the DDL, see Setting up the back-channel logout tables manually.
Setting up the back-channel logout tables manually
If connectionAutomaticDbSchemaSetup is false on the connection pool, create the tables with the following statements. The data user of the connection pool needs SELECT, INSERT, UPDATE, and DELETE on both tables.
CREATE TABLE IF NOT EXISTS `nevisauth_oidc_bcl_session_client` (
`session_id` VARCHAR(255) NOT NULL,
`client_id` VARCHAR(255) NOT NULL,
`sid` VARCHAR(255) NOT NULL,
`issued_at` TIMESTAMP(6) NOT NULL,
`expires_at` TIMESTAMP(6) NOT NULL,
`terminated_at` TIMESTAMP(6) NULL,
`bcl_in_progress_at` TIMESTAMP(6) NULL,
PRIMARY KEY (`session_id`, `client_id`),
INDEX bcl_session_client_expires_at_idx (`expires_at`)
) ENGINE=InnoDB ROW_FORMAT=DYNAMIC;
CREATE TABLE IF NOT EXISTS `nevisauth_oidc_jti_replay_cache` (
`namespace` VARCHAR(255) NOT NULL,
`jti` VARCHAR(255) NOT NULL,
`expires_at` TIMESTAMP(6) NOT NULL,
PRIMARY KEY (`namespace`, `jti`),
INDEX jti_replay_cache_expires_at_idx (`expires_at`)
) ENGINE=InnoDB ROW_FORMAT=DYNAMIC;
CREATE TABLE IF NOT EXISTS nevisauth_oidc_bcl_session_client (
session_id VARCHAR(255) NOT NULL,
client_id VARCHAR(255) NOT NULL,
sid VARCHAR(255) NOT NULL,
issued_at TIMESTAMP WITH TIME ZONE NOT NULL,
expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
terminated_at TIMESTAMP WITH TIME ZONE,
bcl_in_progress_at TIMESTAMP WITH TIME ZONE,
PRIMARY KEY (session_id, client_id)
);
CREATE INDEX IF NOT EXISTS bcl_session_client_expires_at_idx ON nevisauth_oidc_bcl_session_client (expires_at);
CREATE TABLE IF NOT EXISTS nevisauth_oidc_jti_replay_cache (
namespace VARCHAR(255) NOT NULL,
jti VARCHAR(255) NOT NULL,
expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
PRIMARY KEY (namespace, jti)
);
CREATE INDEX IF NOT EXISTS jti_replay_cache_expires_at_idx ON nevisauth_oidc_jti_replay_cache (expires_at);
Back-channel logout attributes
The BackChannelLogout element has the following attributes.
-
logoutTokenExpiry(Integer, seconds, optional, 120)Default value:
120The lifetime of the logout tokens that nevisAuth sends. The value must be greater than 0. nevisAuth logs a warning if the value is greater than 120.
-
triggerReasons(String, comma-separated list, optional,LOGOUT,RP_LOGOUT,MANAGEMENT_DELETE,BCL_RECEIVED)Default value:
LOGOUT,RP_LOGOUT,MANAGEMENT_DELETE,BCL_RECEIVEDThe session end reasons that trigger back-channel logout. Use the names of the end reasons in Session end reasons and back-channel logout. The names are case-sensitive. The setting applies to all AuthorizationServers of the nevisAuth instance. nevisAuth rejects unknown names and an empty list.
-
firstRetryDelay(Integer, seconds, optional, 5)Default value:
5The delay before the first retry of a failed delivery. The value must be at least 0.
-
secondRetryDelay(Integer, seconds, optional, 30)Default value:
30The delay before the second and last retry of a failed delivery. The value must be at least
firstRetryDelay. -
workerThreads(Integer, optional, 8)Default value:
8The number of threads that deliver the logout tokens. The value must be greater than 0.
-
gracePeriod(Integer, seconds, optional, 300)Default value:
300The time that nevisAuth keeps the data of a session after it expires. The value must be at least
logoutTokenExpiry. -
reaperPeriod(Integer, seconds, optional, 300)Default value:
300The interval of the cleanup of expired data. A value of 0 or lower disables the cleanup.
-
reaperInitialDelay(Integer, seconds, optional)Default value: the value of
reaperPeriodThe delay of the first cleanup after startup.
-
reaperBatchSizeInRun(Integer, optional, 500)Default value:
500The maximum number of entries that the cleanup deletes in one batch. The value must be between 1 and 1000.
The BackChannelLogout element also accepts property elements with the HTTP client properties (httpclient.*) for the delivery of the logout tokens. For example, set httpclient.tls.trustStoreRef to trust the TLS certificates of the RPs.
Session end reasons and back-channel logout
Each session ends with an end reason. The end reason decides whether nevisAuth sends logout tokens to the RPs of the session. To change which end reasons trigger back-channel logout, set triggerReasons.
| Event | End reason | Value in the event log | Triggers back-channel logout by default |
|---|---|---|---|
The user logs out, for example through nevisProxy, which calls the SOAP logout operation | LOGOUT | logout | Yes |
SAML single logout, WS-Federation sign-out, or a custom AuthState that ends the session with LOGOUT | LOGOUT | logout | Yes |
| RP-initiated logout through the end-session REST service | RP_LOGOUT | rp-initiated logout | Yes |
| Deletion through the session management API | MANAGEMENT_DELETE | management delete | Yes |
nevisProxy ends its session, or another client calls the SOAP kill operation | PROXY_KILL | proxy kill | No |
| The session times out in nevisAuth | TIMEOUT | expired | No |
| The concurrent session limit of the ThrottleSessionsState evicts the session | THROTTLE | throttle | No |
| nevisAuth receives a logout token from an external OpenID Provider | BCL_RECEIVED | bcl received | Yes |
nevisAuth also accepts STATELESS_AUTH (stateless authentication), REDIRECT_RESTART (restart of the flow on AUTH_REDIRECT), and AUTH_ERROR (authentication error) in triggerReasons. These sessions rarely have OpenID Connect clients. Do not use INVALID and REMOTE_NOT_FOUND. INVALID has no effect. REMOTE_NOT_FOUND only means that another nevisAuth instance already removed the session, for any reason. With it, nevisAuth would send logout tokens also for sessions that expired, or that ended through a received logout token.
Consider the following points:
- If an AuthState marks the session for logout, the session ends when nevisProxy ends it. nevisAuth then uses the end reason that the AuthState set.
- SAML single logout triggers back-channel logout with the SOAP, redirect, and POST bindings. With the SOAP binding, nevisAuth finds the session by the SessionIndex of the logout request. If the logout of another SAML service provider fails, nevisAuth does not end the session and does not send logout tokens.
- To end a session administratively with back-channel logout, use the session management API. A SOAP
killcall ends the session withPROXY_KILL, which does not trigger back-channel logout by default. - If you add
PROXY_KILLorTIMEOUT, nevisAuth sends logout tokens each time an OpenID Connect session expires. - With
BCL_RECEIVED, nevisAuth as identity broker forwards a logout from the external OpenID Provider to its own RPs. nevisAuth sends new logout tokens for its own session, so the logout does not loop back to the external OpenID Provider. To end only the local session, removeBCL_RECEIVEDfromtriggerReasons. See nevisAuth as identity broker.
nevisAuth sends a logout token to a client only if all of the following conditions are true:
- The session has an ID token that nevisAuth issued with back-channel logout enabled.
- The end reason of the session is in
triggerReasons. - nevisAuth recorded the client for the session.
- The client has a Backchannel Logout URI in nevisMeta.
To find out why nevisAuth did not send a logout token, set the trace group BclSender to DEBUG. For more information, see Logging configuration.
Session attributes
The authentication session inside nevisAuth supports a set of well-known session attributes as defined in the following list. The context specifies whether the attribute is relevant during authentication processing or session coordination.
-
ch.nevis.session.userid(*) 1Context:
authAuthenticated user principal; the user's internal identification, usually the primary key within the user database. Needs to be set by authentication plug-in on successful authentication.
-
ch.nevis.session.loginidContext:
authThe login ID, the user has presented for authentication. May be set by authentication plug-in at any time during login.
-
ch.nevis.session.authlevel(*) 1Context:
authThe level of authentication as defined by the site's security role model. May be set after each successful authentication phase (initial login, stepup) by the authentication plug-in.
-
ch.nevis.session.secrolesContext:
authThe (comma separated) list of actual security roles a user currently has.
-
ch.nevis.session.loginresourceContext:
sessThis attribute reflects the resource (URL) a user accessed when performing the initial authentication step.
-
ch.nevis.session.domain(*) 1Context:
authThe SSO domain the user was logged in.
-
ch.nevis.session.clientidContext:
authThe Nevis entry point (reverse proxy) detects the client's channel and associates a channel ID with it. This attribute is used to store the channel ID.
-
ch.nevis.session.entryid(*) 1Context:
authThe Nevis reverse proxy may be identified by this attribute.
-
ch.nevis.session.esauthid(*) 1Context:
authThe nevisAuth instance that performed the authentication is specified by this attribute.
-
ch.nevis.session.sessid(*) 1Context:
sessThe global Nevis session ID.
-
ch.nevis.esauth.sess.id.-pregenerateContext:
sessThe pre-generated session ID, if
idPregenerateis set totrue. -
ch.nevis.session.time.creation,ch.nevis.session.time.access,ch.nevis.session.time.time.syncContext:
sessThese are timestamps, marking the suggested event in the session life cycle.
-
ch.nevis.session.timeout.idle,ch.nevis.session.timeout.absoluteContext:
sessThese are the timeouts (in milliseconds) of the session that are enforced as described in Session cache. |