Session management
In-memory session cache
nevisAuth uses an in-memory session cache to store authentication sessions after the first successful authentication step has been completed. This session cache uses an inactivity time-out mechanism with a session reaper to get rid of expired sessions. The session cache has an upper limit to prevent uncontrolled session creation.
The authentication engine, which is using the session cache, uses two different inactivity time-outs depending on the authentication phase. The session coordinator enforces the current inactivity time-out and an absolute session lifetime. The time-outs therefore are:
- initial inactivity time-out: The user is performing a multistep authentication and has not yet fully established the global authentication session. This time-out is compared against the last access time.
- established inactivity time-out: The user has successfully logged in. This time-out is compared against the last access time during the authentication process.
- absolute session time-out: The session cannot be valid longer than the specified time-out. This time-out is compared against the creation time.
This time-out 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 time-out needs to be equal to the absolute session time-out (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 time-outs therefore are only relevant for limiting unestablished sessions before authentication and for clearing sessions where no termination notifications from nevisProxy instances arrive.
A simple session cache configuration, in conjunction with the time-outs enforced by the AuthEngine, therefore looks as follows:
<SessionCache name="AuthCache"
size="1024"
initialInactivityTimeout="120"
inactivityTimeout="7300"
initialMaxLifetime="900"
maxLifetime="7300"
reaperPeriod="60"
idRandomBytes="32"
failSafe="false">
</SessionCache>
<TokenAssembler name="default">
<Selector default="true"/>
<TokenSpec version="CSSO-1.0" ttl="7200" algorithm="SHA256withRSA">
...
</TokenSpec>
<Domain name="SSO1" default="true"
reauthInterval="0"
inactiveInterval="1800">
...
</Domain>
This example enforces:
- A maximum inactivity time-out to perform a login step of 120 seconds (only relevant for stateful multistep authentications), to be enforced by nevisAuth.
- The "screen lock" time-out (i.e., the inactivity time-out, that triggers a reauthentication on an existing session with some minimal credential requirements) is disabled.
- An inactivity time-out 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".
- An maximum session lifetime of 900 seconds for unauthentic sessions.
- An maximum session lifetime of 7200 seconds for authentic 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 that compatibility of this behavior should therefore be considered for each application.
The following table provides an overview of the SessionCache configuration attributes.
| Attribute | Type****Usage Constraints | Description |
|---|---|---|
| size | integer default: 1024 | The maximum number of cache 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. |
| initialInactivityTimeout | integer default: 300 | The session's initial inactivity time-out, which is raised to inactivityTimeout as soon as the initial login is completed. A user therefore needs to perform a login step within this period. Otherwise, the user is forced to start over. |
| inactivityTimeout | integer default: 86400 | The session's inactivity time-out. When nevisAuth does not get any session events, the session is killed after this period.Kill the session if: lastAccessTime + inactivityTimeout <= now This attribute must have the same value as the maxLifeTime attribute. |
| initialMaxLifetime | integer default: 900 | The session's initial absolute time-out (applies to unauthentic sessions), which is raised to maxLifetime as soon as the initial login is completed (authentication flow reaches AUTH_DONE). A user therefore needs to complete the login within this period. Otherwise, the user is forced to start over. |
| maxLifeTime | integer default: 86400 | The session's absolute time-out (applies to authentic 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. This is because expired SecTokens already define the maximum life time of an authentication session. |
| reaperPeriod | integer default: 60 | The reaper thread locks the session cache regularly (defined by this period) to cleanup expired sessions. |
| idRandomBytes | integer default: 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 32 bytes therefore represents 256 true random bits, which is higher than the currently recommended default of 128 bytes. The session ID length therefore is: idRandomBytes 4 / 3 + <instance name length> *The session ID inside nevisAuth is prefixed with the nevisAuth instance ID to distinguish sessions generated by different nevisAuth instances. |
| idPregenerate | boolean: true, false default: false | 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 idRandomBytes.Under some circumstances, it is desirable to know the final session ID during the authentication process. This can be achieved by setting idPregenerate 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. |
| failSafe | boolean: true, false default: false | This attribute signals if nevisAuth runs in failsafe mode. If set to "true", a cache syncer component is loaded, which synchronizes modified sessions with another nevisAuth instance. |
| enableIndexing | String: on, off, <session variable name>default: off | Enables and configures session indexing (see Session indexing]. Possible values: off: session indexing is disabled on: legacy value enabling session indexing on session's loginId field * <session variable name>: enables indexing on configured session variable |
Remote session cache
Internally, a nevisAuth instance holds one store syncer, which is registered as a session listener. Whenever a session event is fired, e.g., when a session is deleted or updated, all session listeners are informed about the recent change. Thus, the store syncer is informed and, if enabled, will attempt to synchronize the current state of the local session with another nevisAuth instance, with an SQL database or with the file system, depending on its configuration.
The SessionCache attribute failSafe enables the store syncer, while the syncTarget defines the technology and address of the remote session sharing nodes.
Sessions are only synchronized to the remote session cache when the authentication flow has been completed and the session is upgraded to an authentic session. Unauthentic sessions are not synchronized to the remote session cache. As a consequence, it is not possible to complete an authentication flow on a nevisAuth instance different from the one on which it was started. That is, active-active load balancing on nevisAuth is not supported.
Session synchronization
The synchronization is performed by recording session modifications during a short time interval (for network optimization) and sending the session content to the fallback nevisAuth instance or the storage medium. If this call fails, the retry counter is decremented and the session is queued for retrial.
Note that asynchronous session-sharing (with configured syncDelay > 0) is performed with a limited number of threads (per default 1) and heavy session load with short synchronization delays may lead to an overflowing synchronization queue. In this case, it is recommended using synchronous session-sharing (setting the syncDelay to "0" and reducing syncFailRetryCount).
The following code is an example of session-sharing using a JDBC connection to a common MariaDB database. The example shows a synchronous setup:
<SessionCache name="AuthCache"
..."
failSafe="true">
<property name="syncProvider" value="jdbc"/>
<property name="syncUser" value="nss_auth"/>
<property name="syncPassword" value="nss_auth"/>
<property name="syncTarget" value="jdbc:mysql://localhost:3306/NSS"/>
<property name="syncDelay" value="0"/>
<property name="syncThreads" value="5"/>
<property name="syncPullInitial" value="true"/>
<property name="syncFailRetryPeriod" value="0"/>
<property name="syncFailRetryCount" value="0"/>
</SessionCache>
The following table provides an overview of the component's configuration properties.
| Attribute | Type****usage constraints | Description |
|---|---|---|
| syncProvider | enum {jdbc} | Specifies the provider handling synchronization connections.* jdbc: provider synchronizing to MariaDB database using JDBC. |
| syncTarget | string required | This attribute specifies the connection/address of the synchronization medium for the provider.* JDBC: JDBC connection string for MariaDB JDBC driver. |
| syncMaxRetry | int optional for JDBC default: 2 | The number of retries that should be attempted when the connection object that is just retrieved from the connection pool is null. This attribute is only used in JDBC connectors. |
| syncUser | string required for JDBC | The username for DB access. You can use the same format as you can use for passwords. For example, you can use the following syntax to specify the username from an environment variable: pipe://echo $SYNC_USER.For more information regarding the allowed syntax, see Passwords in the configuration. |
| syncPassword | string required for JDBC | The password for DB access. This property accepts standard encryption/obfuscation syntax. See documentation of how to restrict disclosure of passphrases in Passwords in the configuration. |
| syncDelay | integer default: 1000 | Specifies a period in milliseconds, the session syncer should delay the sync to reduce network traffic. When the value is set to 0 msec, the synchronization is done synchronized with the call performing the session modification. This can be useful to reduce race conditions when two clients, modifying the session, are connected to the master and the fallback instance respectively. The client in this case has to wait until the synchronization has completed.Setting the value to 0 msec is therefore only recommended under the following circumstances: in case of heavy use of distributed session management (to prevent optimistic locking problems) to limit JVM memory consumption (because synchronization Q is not used in this case) |
| syncPullInitial | boolean default: 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. |
| syncThreads | integer default: 1 | Specifies the number of threads to use to send synchronization packages to the fallback instance.If the number of worker threads in the server is high and the syncer thread number is low, heavy traffic may lead to OutOfMemory exception in the JVM. |
| syncFailRetryPeriod | integer default: 20000 | 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 default: 3 | This counter defines how many retries should be performed after a failed synchronization. The counter is decremented with each try. |
| syncMaxConnectionPoolSize | integer optional for JDBCdefault: 20 | Size of the connection pool used to communicate with the remote session store. |
| syncMaxConnectionKeepAlive | integer optional for JDBC default: 60000 | The maximum time, in milliseconds, that a connection is kept alive in the connection pool. |
| syncRefreshInterval | integer default: -1 | The interval in milliseconds after which a session is resynched."-1": The session is never resynched against the remote cache. This only works for failover cases, not for load balancing. "0": The session is always resynched from the remote cache. * ">0": The time in msec after which the session is resynched. |
| syncRemoteSessionReaperThreads | integer optional for JDBCdefault: 1 | The number of threads to use to clean up the remote session cache with the RemoteSessionReaper.This parameter is only relevant if ABSTO-based session reaping is enabled (see the table below). |
| syncRemoteSessionReaperPeriod | integer [sec] default: 60 | The period in seconds in which to execute the run method of the RemoteSessionReaper. This parameter is only relevant if ABSTO-based session reaping is enable (see the table below). |
| syncRemoteSessionAbsToTolerance | integer [sec] default: 1800 (30 minutes) | 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. This parameter is only relevant if ABSTO-based session reaping is enabled (see the table below). |
| syncRemoteSessionIndexFormat | enum {normal, unicodeEscaped, hashed}default: hashed | Defines the format, in which the session index value is written into the remote session store in case Session indexing is turned on. normal: the value of the session index is stored as it is in the session without any change (legacy behavior); unicodeEscaped: non-Latin 1 (ISO 8859-1) characters in the session index value are unicode-escaped (\uxxxx), for example, abçdefğ is stored as ab\u00E7def\u011F; hashed: the SHA-256 (hex) hash of the session index value is stored, for example, "abçdefğ" is stored as 20c76ac7893952f0d6993b1977ec13893f76cc5fdf4eb4d00f788e89c9101785 |
By default, nevisAuth uses the MariaDB client as the JDBC driver when configuring jdbc:-URLs. However, it is also possible to use the official MySQL client as the JDBC driver. Therefore, place the MySQL client JAR into the folder /var/opt/nevisauth/<instance>/lib .
Setting up a remote SQL session DB (for provider "JDBC")
nevisAuth synchronizes session properties as blobs into a MariaDB database. The schema of the remote SQL session table TNSSA_AUTH_SESSION_CACHE, which holds the session entries, is described in the following table:
| Field | Type | Null | Key | Default |
|---|---|---|---|---|
| SESSION_ID | varchar(255) | NO | PRIMARY KEY | NULL |
| DATA | mediumtext | YES | NULL | |
| ABSTO | timestamp | NO | CURRENT_TIMESTAMP | |
| SESSION_INDEX | varchar(255) | YES | MUL | NULL |
The column data-type has to be sized differently in scenarios where this assumption does not hold.
The SESSION_ID field corresponds to the ID of the local session of a nevisAuth instance. The DATA field contains the session properties as strings in form of a blob. The ABSTO field corresponds to the expiration timestamp of the session. The DATA and ABSTO fields are updated whenever a session is synced, which is whenever a session is created or updated. Sessions that have a timestamp ABSTO in the past will not be resynched to a nevisAuth instance. Instead, they will be removed regularly if the remote session reaper is running. We recommend storing the ABSTO as it increases the reliability of the nevisAuth instances that are pulling and pushing updates from and to the remote session cache.
The following MariaDB script can be used to create the remote session table that can be accessed from localhost with the user nss_auth :
CREATE DATABASE IF NOT EXISTS NSS;
-- table TNSSA_AUTH_SESSION_CACHE stores the sessions
DROP TABLE IF EXISTS NSS.TNSSA_AUTH_SESSION_CACHE;
CREATE TABLE NSS.TNSSA_AUTH_SESSION_CACHE (
SESSION_ID VARCHAR(255) PRIMARY KEY NOT NULL UNIQUE,
DATA MEDIUMTEXT,
ABSTO TIMESTAMP NOT NULL,
SESSION_INDEX VARCHAR(255)
) ENGINE = InnoDB;
-- nss_auth indexes:
ALTER TABLE NSS.TNSSA_AUTH_SESSION_CACHE ADD INDEX (SESSION_INDEX);
ALTER TABLE NSS.TNSSA_AUTH_SESSION_CACHE ADD INDEX (ABSTO);
-- nss_auth user:
GRANT USAGE ON NSS.TNSSA_AUTH_SESSION_CACHE TO nss_auth@localhost;
DROP USER nss_auth@localhost;
CREATE USER nss_auth@localhost IDENTIFIED BY 'nss_auth';
GRANT SELECT,UPDATE,INSERT,DELETE ON NSS.TNSSA_AUTH_SESSION_CACHE TO nss_auth@localhost;
If the MariaDB database is located in a different host than nevisAuth, make sure that the user can remotely connect to it, as described in the(https://mariadb.com/kb/en/library/configuring-mariadb-for-remote-client-access/).
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
The chapter describes a setup that is resilient to database outage. With such a setup, 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 possibly 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).
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.
Hint
The installation of MariaDB is not discussed here. For instructions, see the online documentation of MariaDB. Note that Nevis offers a database appliance which comes bundled with a pre-installed MariaDB package.
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)
jdbc:mariadb:sequential//host-db1:3306,host-db2:3306/NSSData consistency (MariaDB replication)
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.
| 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 .
- 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.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:
Configuration of 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:
Configuration of 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
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):
Setting master on host-db1
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):
Setting master on host-db2
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:
Starting replication on host-db1
START SLAVE;
- on host-db2:
Starting replication on host-db2
START SLAVE;
Setup of nevisAuth
Most of the nevisAuth configuration is the same for the replicated remote session cache as for the "single-node" (normal) remote session cache. The only difference is the syncTarget property of the SessionCache, with which you configure the two database hosts:
<property name="syncTarget" value="jdbc:mariadb:sequential//host-db1:3306,host-db2:3306/NSS"/>
You can use the full MariaDB syntax, because the value of the syncTarget property is handed over to the MariaDB jdbc driver as connection string without any changes.
For more information on the MariaDB jdbc driver, see the documentation at:(https://mariadb.com/kb/en/library/about-mariadb-connector-j/)
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:
/etc/crontab
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> 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.
Session indexing
nevisAuth sessions can be indexed by a configurable session variable. This allows fast searches of sessions, a functionality that is desirable for some use cases. One example is session throttling, where the number of sessions a user is allowed to have at any time is to be limited. In this case, sessions should be grouped by a userId or loginId. Without index all sessions will have to be inspected and this will be prohibitively expensive considering that session sharing has to be configured for throttling to be possible.
When session indexing with SQL DB-based session sharing is used, the default DB schema definition of the SESSION_INDEX column is not intended for indexing large data fields (exceeding 255 characters). The column data-type has to be sized differently in scenarios where this assumption does not hold. See Setting up a remote SQL session DB (for provider "JDBC"). The following table describes the possible combinations of session indexing and session sharing:
| enableIndexing | Session sharing | Description |
|---|---|---|
| off | Irrelevant | Session indexing is disabled, session sharing is not relevant. Sessions may be queried by iterating over all local sessions. |
| on | Off | Local session indexing on the session's loginId value. Implemented by a simple in-memory lookup table. |
| on | On (JDBC only) | Local session indexing on the session's loginId value.Indexing on shared sessions is only supported for SQL DBs and only if the DB schema defines the SESSION_INDEX index (see Setting up a remote SQL session DB (for provider "JDBC")]. |
<variable name> | Off | Shared session indexing on a session variable value. Implemented by a simple in-memory lookup-table. |
<variable name> | On (JDBC only) | Shared session indexing on a variable value.Indexing on shared sessions is only supported for SQL DBs and only if the DB schema defines the SESSION_INDEX index (see Setting up a remote SQL session DB (for provider "JDBC")]. |
Session attributes
The authentication session inside nevisAuth supports a set of well-known session attributes as defined in the following table. The context specifies whether the attribute is relevant during authentication processing or session coordination.
| Name1) | Context | Description |
|---|---|---|
| ch.nevis.session.userid *) | 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.plug-in |
| ch.nevis.session.loginid | 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 *) | 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 | auth | The (comma separated) list of actual security roles a user currently has. |
| ch.nevis.session.loginresource | sess | This attribute reflects the resource (URL) a user accessed when performing the initial authentication step. |
| ch.nevis.session.domain *) | auth | The SSO domain the user was logged in. |
| ch.nevis.session.clientid | 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 *) | auth | The Nevis reverse proxy may be identified by this attribute. |
| ch.nevis.session.esauthid *) | auth | The nevisAuth instance that performed the authentication is specified by this attribute. |
| ch.nevis.session.sessid *) | sess | The global Nevis session ID. |
| ch.nevis.esauth.sess.id.-pregenerate | sess | The pre-generated session ID, if idPregenerate is set to true. |
| ch.nevis.session.time.creationch.nevis.session.time.accessch.nevis.session.time.time.sync | sess | These are timestamps, marking the suggested event in the session life cycle. |
| ch.nevis.session.timeout.idlech.nevis.session.timeout.absolute | sess | These are the timeouts (in milliseconds) of the session that are enforced as described in Session cache. |
| 1) The attributes marked with) are usually part of the SecToken.* |