Shared out-of-context data

The state of most processing of authentication operations is strictly limited to the session of a user. This means that only changes to the user session can persist. Any state changes done within the context of a request (or by extension, within the conversation) are lost after the operation is finished. In any case, data stored in those contexts can only be seen by the operations running within the same context, i.e., by the same user.

However, it is sometimes necessary to maintain a global state, beyond the concerns of a particular user or his session. For this purpose, nevisAuth defines the OutOfContextDataService interface. An implementing class is defined and its instance configured using system properties with the following syntax:

-Dch.nevis.esauth.OutOfContextDataService.class=fully.qualified.ClassName
-Dch.nevis.esauth.OutOfContextDataService.param1=aValue
-Dch.nevis.esauth.OutOfContextDataService.param2=anotherValue

By default, nevisAuth uses the FileSystemOOCDService for out-of-context data (see FileSystemOOCDService]. The service can be disabled by configuring "off":

-Dch.nevis.esauth.OutOfContextDataService.class=off

The OutOfContextDataService interface provides the following properties:

• Hierarchically structured data with unique entry keys similar to file system paths.
• Each entry has an associated expiration date and will not be visible after this date.
• Each entry can be associated with an arbitrary number of meta data in the form of key/value pairs.
• Entries can be queried and listed based on branches of the hierarchical structure, much like listing files in a file system directory.
• Reading, writing, removing and querying entries is guaranteed to be consistent under load of multiple accessing threads and processes. However, no guarantees are made regarding the performance of those operations.

FileSystemOOCDService

Fully qualified class name: ch.nevis.esauth.ooc.FileSystemOOCDService

This OOCD service class implements the OOCD interface using the file system as persistence medium and as locking mediator. Each data entry is stored in a simple file, its meta data is placed in a property file. The hierarchical structure of the data is translated into a directory structure.

Coordination of multiple processes is done using a single global file lock. Coordination of multiple threads within a process holding this lock is implemented with Java concurrent locks.

A reaper thread running in the background periodically deletes files whose data entries have expired.

Property	Type Usage Constraints	Description
dir	string (file system path)defaults to /var/opt/nevisauth/<instance>/run/data	This property sets the directory in which the data is persisted in the file system. To set up data sharing between multiple nevisAuth instances, configure the same path here.
reaperInterval	number (seconds)defaults to 60 seconds	This property sets the interval of the reaper thread that clears away outdated files. Note that outdated data will be seen by the service automatically, even if the files holding the data have not yet been removed by the reaper.
lockGloballyWhenReaping	boolean defaults to true	With this property, the locking behavior can be relaxed. By default or when set to "true", the filesystem directory is completely locked when entries are reaped. When set to "false", the file, which will be deleted, is locked locally, allowing better performance when the reaper runs.

SqlOOCDService

Fully qualified class name: ch.nevis.esauth.ooc.sql.SqlOOCDService

The SqlOOCDService dataservice uses an SQL database as a backend to store out-of-context data. Currently only MariaDB databases are supported.

In the future, migrating from both file and Couchbase data services to the SqlOOCDService dataservice will be recommended. In the current release 4.25.0.2 however, this implementation is considered as experimental. Improvements and changes might be introduced in further phases of this experimental stage.

The SqlOOCDService out-of-context data service does not provide the following elements:

• Hierarchically structured data with unique entry keys similar to file system paths.
• Querying and listing entries based on branches of the hierarchical structure, like listing files in a file system directory.

Database setup

Possible approaches:

1. Create a schemaUser with the rights to create the database table in a newly created database, then create a dataUser who can modify the content of this table.
2. Create the table manually with the schemaUser.
3. Rely on nevisAuth to use the schemaUserto create the table.
4. Create the database table and the dataUser with appropriate rights using an existing administrator user.
5. Use an existing database.
6. Manually create a new database.

The following example shows how to set up the database using UTF-8 and local connectivity. If you want to store a string containing special characters, your database much use a charset supporting these special characters. If this is not the case, configure your database accordingly.

CREATE DATABASE IF NOT EXISTS OOCD CHARACTER SET ='utf8' COLLATE ='utf8_unicode_ci';
CREATE USER IF NOT EXISTS `oocdschemauser`@`localhost` IDENTIFIED BY 'password';
GRANT CREATE ON OOCD.* TO `oocdschemauser`@`localhost`;
CREATE USER IF NOT EXISTS `oocddatauser`@`localhost` IDENTIFIED BY 'password';
GRANT SELECT, INSERT, UPDATE, DELETE ON OOCD.* TO `oocddatauser`@`localhost`;
FLUSH PRIVILEGES;

Depending on your preferences, you can also re-use the NSS database and nss_auth user from the( setup. Note that in this case still create the user that will create the table, or you have to create the table manually by an administrator user.

It is not recommended using the same user for database table creation and data modification.

By default, the SqlOOCDService automatically creates the required database table in the SQL database (can be disabled by setting the property automaticDbSchemaSetup to "false"). The code below shows the current default table definition:

SQL Out of Context Data Service Table

CREATE TABLE IF NOT EXISTS `nevisauth_out_of_context_data_service` (
 `key` VARCHAR(1024) NOT NULL UNIQUE,
 `value` MEDIUMTEXT NOT NULL,
 `reap_timestamp` TIMESTAMP NOT NULL,
 UNIQUE INDEX key_idx (`key`), INDEX reap_timestamp_idx (`reap_timestamp`))

You can adapt the table above according to your needs, if your data exceeds the limits defined above (key size of 1024 bytes and storage size of 16 MB/MEDIUMTEXT), or fits into smaller data storage types like TINYTEXT or TEXT. Note that use the same table and column names.

Configuring nevisAuth

The SqlOOCDService can be configured by JVM command line options. The following table depicts the available configuration options:

Property	TypeUsage Constraints	Description
jdbcUrl	string JDBC URL	The JDBC URL to the MariaDB database. For more details regarding the syntax, see the MariaDB documentation.
dataUser	string example value: data-user	The username required to access the data in the database. This user must have SELECT, INSERT, UPDATE and DELETE access rights to the database.
dataUserPassword	string	The password of the user accessing the data.
schemaUser	string	The name of the user that creates the schema and tables in the database. This user must have CREATE access rights to the database. If not provided, the system will use the user specified with the attribute user to create the schema.It is recommended that separate users create the schema and access the data. You specify these users in the DB properties schemaUser and dataUser, respectively.
schemaUserPassword	string	The password of the user who creates the schema and the tables in the database.If not provided, the system will use the password specified with attribute passwordto create the schema.
automaticDbSchemaSetup	boolean default value: true	If set to "true", nevisAuth will automatically create the schema and table used to store the data. Set this property to "false", if you want to handle this differently, for example because you have different data sizing requirements. Also set the property to "false", if you did not specify the schemaUseror if the specified user does not have the required CREATE access rights.

The next code block shows an example configuration to be added in the Java options (for the exact syntax, see the JVM command-line options in the section Server command-line interface]:

-Dch.nevis.esauth.OutOfContextDataService.class=ch.nevis.esauth.ooc.sql.SqlOOCDService
-Dch.nevis.esauth.OutOfContextDataService.jdbcUrl=jdbc:mariadb://localhost:3306/OOCD
-Dch.nevis.esauth.OutOfContextDataService.dataUser=oocddatauser
-Dch.nevis.esauth.OutOfContextDataService.dataUserPassword=password
-Dch.nevis.esauth.OutOfContextDataService.schemaUser=oocdschemauser
-Dch.nevis.esauth.OutOfContextDataService.schemaUserPassword=password
-Dch.nevis.esauth.OutOfContextDataService.automaticDbSchemaSetup=true

Below, find another example. Here, we created the database table manually and reused the NSS database and the nss_auth user from the remote session store (see Session management]. Note that if no schemaUser is available, the dataUser is used. This means that if the dataUser has no CREATE rights, you have to disable the property automaticDbSchemaSetup (see the SqlOOCDService - Properties].

-Dch.nevis.esauth.OutOfContextDataService.class=ch.nevis.esauth.ooc.sql.SqlOOCDService
-Dch.nevis.esauth.OutOfContextDataService.jdbcUrl=jdbc:mariadb://localhost:3306/NSS
-Dch.nevis.esauth.OutOfContextDataService.dataUser=nss_auth
-Dch.nevis.esauth.OutOfContextDataService.dataUserPassword=password
-Dch.nevis.esauth.OutOfContextDataService.automaticDbSchemaSetup=false

You can use the following syntax to avoid hardcoding passwords in a plaintext file (standalone deployment only):

Syntax	Example	Remarks
${exec:command}	dataUserPassword: ${exec:/var/opt/keys/own/instance/keypass.sh}	Executes the given command and uses its output as the value.
${env:variablename}	dataUser: ${env:DATA_USER}	Uses the value of the specified environment variable.