Skip to main content
Version: 9.2605.x RR

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:

  1. Unauthenticated session (also mentioned as initial session)
  2. 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:

Session store configuration example
<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.
info

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: 600

    The 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: 28800

    The 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 <= now

    caution

    This attribute must have the same value as the maxLifeTime attribute.

  • sessionInitialMaxLifetime (Integer, seconds, optional, 1200)

    Default value: 1200

    The 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: 28800

    The session's absolute timeout. (applies to authenticated sessions)

    Kill the session if: creationTime + maxLifeTime <= now

    This 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: 32

    The 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$

    info

    The 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: true

    Under normal circumstances, a session receives its final ID only after the state AUTH_DONE is reached for the first time. At this point, the previous (temporary) session ID is changed to a randomly generated ID as configured using sessionIdRandomBytes.

    Under some circumstances, it is desirable to know the final session ID during the authentication process. This can be achieved by setting sessionIdPreGenerate to "true". The session variable ch.nevis.esauth.sess.id.pregenerate will 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.

Local session caches and terminated session polling

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

    The session attributes to index. nevisAuth stores the indexed values as SHA-256 hashes. If you set attributes and need the login ID index, list ch.nevis.session.loginid as 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.sid and ch.nevis.session.oidc.sub for the end-session service (RP-initiated logout).
  • ch.nevis.session.rp.oidc.sid and ch.nevis.session.rp.oidc.sub for the back-channel logout service.
Session indexing for OpenID Connect logout
<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 SessionIndexing configuration.
  • With a remote session store, nevisAuth also writes the hash of the first entry of attributes to the column SESSION_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 queryAttribute is not indexed. The session management API responds with HTTP 400 if attributeName is 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.
info

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: 100000

    The 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: 60

    The reaper thread locks the session cache regularly (defined by this period) to clean up expired sessions.

  • reaperEvictSyncedSessions (Boolean, optional, true)

    Default value: true

    When 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 RemoteSessionStore is 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:

IndicatorSourceWarns before the limit is reached
Session reaper logINFO message in the LocalSessionStore log category after each reaper runYes
Limit exceeded logERROR message in the LocalSessionStore log categoryNo
Readiness endpointlocalSessionStore check of the readiness endpointNo

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:

  1. Cache sessions during the evaluation of an authentication step.
  2. 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: jdbc

    Specifies the provider handling synchronization connections.

    Only jdbc provider 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: false

    Configures 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: 100

    This 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: 1

    This 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: 60

    The 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 lifetime

    The tolerance (in seconds) is added to the ABS_TO value 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: reaperPeriod

    Time elapsed before the first clean up of the remote session store with the RemoteSessionReaper is triggered after startup.

  • reaperThreads (Integer, optional, 1)

    Default value: 1

    The number of threads to use to clean up the remote session store with the RemoteSessionReaper.

  • reaperInvalidateSessionBeforeDelete (Boolean, optional, true)

    Default value: true

    When 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. See reaperMaxSessionsPerRun and reaperBatchSizeInRun to tune the reaper behaviour.

  • reaperMaxSessionsPerRun (Integer, optional, 5000)

    Default value: 5000

    Maximum number of expired sessions to process per reaper run. Only used when reaperInvalidateSessionBeforeDelete is enabled.

  • reaperBatchSizeInRun (Integer, optional, 500)

    Default value: 500

    Number 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 reaperInvalidateSessionBeforeDelete is enabled.

  • storeUnauthenticatedSessions (Boolean, optional, true)

    Default value: true

    When 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:

ModereaperEvictSyncedSessionsreaperInvalidateSessionBeforeDelete
Consistency (default)truetrue
Performancetruefalse
Legacyfalsefalse

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.

Deprecation of the automatic table creation

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.

Minimal configuration example
<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.

Example of immediate synchronisation to remote session store
<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.

Example with replicated remote session store databases and retries
<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).
info

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.

    info

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

UsernamePurposeRequired permissions
nss_authAccount used by nevisAuth for session management.ALL PRIVILEGES, on the replicated database to manage sessions.
replication_userAccount used by the slave node to log into the master node.REPLICATION SLAVE, to be able to replicate data.
binarylog_userAccount 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.

  1. Creation of the replication user
CREATE USER IF NOT EXISTS replication_user IDENTIFIED BY 'replicationpassword';
GRANT REPLICATION SLAVE ON *.* TO replication_user;
  1. Creation of the binary logs user
CREATE USER IF NOT EXISTS binarylog_user IDENTIFIED BY 'binarylogspassword';
GRANT SUPER ON *.* TO binarylog_user;
  1. Configuration of MariaDB service. To configure the MariaDB service, add the following entries to the file /etc/my.cnf as 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 log
    log-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 log
    log-basename=mariadbmaster
    binlog-format=MIXED
    # Setting which tables are replicated
    replicate_wild_do_table="NSS.TNSSA_AUTH_SESSION_CACHE"
    # Avoiding collisions of primary IDs for tables where the primary ID is auto-incremented
    # Auto-increment value
    auto_increment_increment=2
    # Auto-increment offset (*)
    auto_increment_offset=1
    # Suppressing duplicated keys errors for multi-master setup
    slave_exec_mode=IDEMPOTENT
    # Ignoring some data definition language errors
    slave-skip-errors=1452, 1062
    # Suppressing binary logs after a delay regardless of the replication status
    expire_logs_days=1
    # Maximum number of connections
    max_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 replication
    slave-parallel-threads=10
    # enabling semi-synchronous replication
    rpl_semi_sync_master_enabled=ON
    rpl_semi_sync_slave_enabled=ON
    # change to READ COMMITTED
    transaction-isolation=READ-COMMITTED
  • Configure the MariaDB service on host-db2:

    [mariadb]
    # Enabling binary log
    log-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 log
    log-basename=mariadbmaster
    binlog-format=MIXED
    # Setting which tables are replicated
    replicate_wild_do_table="NSS.TNSSA_AUTH_SESSION_CACHE"
    # Avoiding collisions of primary IDs for tables where the primary ID is auto-incremented
    # Auto-increment value
    auto_increment_increment=2
    # Auto-increment offset (*)
    auto_increment_offset=2
    # Suppressing duplicated keys errors for multi-master setup
    slave_exec_mode=IDEMPOTENT
    # Ignoring some data definition language errors
    slave-skip-errors=1452, 1062
    # Suppressing binary logs after a delay regardless of the replication status
    expire_logs_days=1
    # Maximum number of connections
    max_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 replication
    slave-parallel-threads=10
    # enabling semi-synchronous replication
    rpl_semi_sync_master_enabled=ON
    rpl_semi_sync_slave_enabled=ON
    # change to READ COMMITTED
    transaction-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
info

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

info

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.

info

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.

info

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.000131
    Position: 194630804
    Binlog_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\G on the master):

    STOP SLAVE;
    CHANGE MASTER TO
    MASTER_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.enabled to true. Without the BackChannelLogout element, 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:

Back-channel logout with the database store
<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.

  • LocalStore

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

  • RemoteStore

    Keeps 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 tables nevisauth_oidc_bcl_session_client and nevisauth_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.

MariaDB
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;
PostgreSQL
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: 120

    The 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_RECEIVED

    The 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: 5

    The delay before the first retry of a failed delivery. The value must be at least 0.

  • secondRetryDelay (Integer, seconds, optional, 30)

    Default value: 30

    The delay before the second and last retry of a failed delivery. The value must be at least firstRetryDelay.

  • workerThreads (Integer, optional, 8)

    Default value: 8

    The number of threads that deliver the logout tokens. The value must be greater than 0.

  • gracePeriod (Integer, seconds, optional, 300)

    Default value: 300

    The 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: 300

    The 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 reaperPeriod

    The delay of the first cleanup after startup.

  • reaperBatchSizeInRun (Integer, optional, 500)

    Default value: 500

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

EventEnd reasonValue in the event logTriggers back-channel logout by default
The user logs out, for example through nevisProxy, which calls the SOAP logout operationLOGOUTlogoutYes
SAML single logout, WS-Federation sign-out, or a custom AuthState that ends the session with LOGOUTLOGOUTlogoutYes
RP-initiated logout through the end-session REST serviceRP_LOGOUTrp-initiated logoutYes
Deletion through the session management APIMANAGEMENT_DELETEmanagement deleteYes
nevisProxy ends its session, or another client calls the SOAP kill operationPROXY_KILLproxy killNo
The session times out in nevisAuthTIMEOUTexpiredNo
The concurrent session limit of the ThrottleSessionsState evicts the sessionTHROTTLEthrottleNo
nevisAuth receives a logout token from an external OpenID ProviderBCL_RECEIVEDbcl receivedYes

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 kill call ends the session with PROXY_KILL, which does not trigger back-channel logout by default.
  • If you add PROXY_KILL or TIMEOUT, 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, remove BCL_RECEIVED from triggerReasons. 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 (*) 1

    Context: auth

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

    Context: auth

    The login ID, the user has presented for authentication. May be set by authentication plug-in at any time during login.

  • ch.nevis.session.authlevel (*) 1

    Context: auth

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

    Context: auth

    The (comma separated) list of actual security roles a user currently has.

  • ch.nevis.session.loginresource

    Context: sess

    This attribute reflects the resource (URL) a user accessed when performing the initial authentication step.

  • ch.nevis.session.domain (*) 1

    Context: auth

    The SSO domain the user was logged in.

  • ch.nevis.session.clientid

    Context: auth

    The 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 (*) 1

    Context: auth

    The Nevis reverse proxy may be identified by this attribute.

  • ch.nevis.session.esauthid (*) 1

    Context: auth

    The nevisAuth instance that performed the authentication is specified by this attribute.

  • ch.nevis.session.sessid (*) 1

    Context: sess

    The global Nevis session ID.

  • ch.nevis.esauth.sess.id.-pregenerate

    Context: sess

    The pre-generated session ID, if idPregenerate is set to true.

  • ch.nevis.session.time.creation, ch.nevis.session.time.access, ch.nevis.session.time.time.sync

    Context: sess

    These are timestamps, marking the suggested event in the session life cycle.

  • ch.nevis.session.timeout.idle, ch.nevis.session.timeout.absolute

    Context: sess

    These are the timeouts (in milliseconds) of the session that are enforced as described in Session cache. |

Footnotes​

  1. The attributes marked with (*) are usually part of the SecToken. ↩ ↩2 ↩3 ↩4 ↩5 ↩6