Migrating to nevisAuth 9.2611
nevisAuth 9.2611 adds OpenID Connect back-channel logout, RP-initiated logout, and shared database connection pools. The release contains the following breaking changes:
- The methods that end a session require the end reason of the session.
- Session indexing supports several attributes, and uses a new database table.
- Shared database connection pools replace the connection settings of each database feature.
sidis a reserved ID token claim.- The event log shows new session end reasons.
The guide has three parts:
- Migrating custom AuthStates and scripts: applies to everyone who uses custom AuthStates or ScriptState scripts that end sessions, with or without nevisAdmin 4.
- Changes that apply to all setups: applies to everyone. This part includes the conditions for a rolling upgrade of several nevisAuth instances that share a session database, also with nevisAdmin 4.
- Migrating the configuration and the database: applies only if you configure nevisAuth without nevisAdmin 4. If you use nevisAdmin 4, the patterns generate the new configuration, and you can skip this part.
For more information on the new features, see OpenID Connect back-channel logout and RP-initiated logout.
Migrating custom AuthStates and scripts
Changed session termination methods
The methods that end a session now require the end reason of the session as a parameter. The reason is the enum ch.nevis.esauth.sess.RemovalReason, which is part of the artifact nevisauth-authstate-api. The parameter must not be null.
| Interface | Earlier method | New method |
|---|---|---|
ch.nevis.esauth.auth.engine.AuthResponse | setInvalidateSession() | setInvalidateSession(RemovalReason terminationReason) |
ch.nevis.session.NevisSession | invalidate() | invalidate(RemovalReason reason) |
ch.nevis.esauth.sess.SessionCoordinator | killSession(String actor, String sessionId) | killSession(String actor, String sessionId, RemovalReason reason), or killSession(String sessionId, RemovalReason reason) |
ch.nevis.esauth.sess.SessionCoordinator | killSessions(String actor, String attributeName, String attributeValue) | killSessions(String attributeName, String attributeValue, RemovalReason reason), which returns the number of ended sessions |
The earlier methods are removed. Custom AuthStates do not compile against nevisAuth 9.2611. Custom AuthStates that were compiled against an earlier version, and ScriptState scripts, fail at runtime when they call one of these methods. Update the code, and compile custom AuthStates again.
Choosing the end reason
The end reason decides whether nevisAuth sends logout tokens to the OpenID Connect clients of the session. Use one of the following values in custom code:
RemovalReason.LOGOUT: the session ends because the user logs out, for example in a custom single logout. By default, this reason triggers back-channel logout.RemovalReason.PROXY_KILL: the session ends for technical cleanup, for example after a flow that must not keep a session. This reason does not trigger back-channel logout by default.
setInvalidateSession(RemovalReason.LOGOUT) triggers back-channel logout when nevisProxy ends the session afterwards. If the session expires instead, the end reason is a timeout, and nevisAuth does not send logout tokens by default.
For the reasons that trigger back-channel logout, see Session end reasons and back-channel logout.
Migration examples
The following examples show a custom single logout in a Java AuthState and in a Groovy ScriptState.
response.setInvalidateSession();
import ch.nevis.esauth.sess.RemovalReason;
response.setInvalidateSession(RemovalReason.LOGOUT);
Groovy scripts must pass the enum, not a string. Import RemovalReason at the beginning of the script:
import ch.nevis.esauth.sess.RemovalReason
// Mark the session for logout. nevisProxy ends it afterwards.
response.setInvalidateSession(RemovalReason.LOGOUT)
// End the current session directly.
request.getSession(false)?.invalidate(RemovalReason.LOGOUT)
// End all sessions of a user. The attribute must be indexed.
sessionCoordinator.killSessions('ch.nevis.session.loginid', loginId, RemovalReason.LOGOUT)
Changes that apply to all setups
Reserved sid claim
sid is now a reserved ID token claim. If an AuthorizationServer defines the property openid.claim.sid, also through a nevisAdmin 4 pattern, the AuthorizationServer fails at startup with the following error:
Default claims can not be overwritten! Conflicting property prefix is: openid.claim. Conflicting property name(s): sid
The check applies whenever OpenID Connect is enabled, also if back-channel logout is not enabled. Remove the property openid.claim.sid. If RPs read the value of this claim, define it with another claim name, and adapt the RPs.
If openid.bcl.enabled is true, nevisAuth also sets the sid claim in the access tokens. A custom access token claim oauth2.claim.sid is then replaced by the session ID. Use another claim name for it.
Session end reasons in the event log
The field sessionEndReason of the event log shows the new end reasons. Adapt filters and reports that use the earlier values.
| Session end | Earlier value | Value in nevisAuth 9.2611 |
|---|---|---|
| A client ends the session, for example nevisProxy | terminated-by-client | proxy kill, or logout if an AuthState marked the session for logout |
| Deletion through the session management API | terminated-by-client | management delete |
| An AuthState ends the session directly | terminated-by-flow | The end reason, for example logout or throttle |
| RP-initiated logout | Not available | rp-initiated logout |
| Back-channel logout received from an external OP | Not available | bcl received |
The values logout (user logout), expired (timeout), and aborted (error) are unchanged.
The value terminated-by-flow remains on the event of the operation in which an AuthState marks the session for logout.
Upgrading nevisAuth instances that share a session database
This section applies if several nevisAuth instances share a remote session store, also if you use nevisAdmin 4.
nevisAuth 9.2611 and earlier versions can use the same session database at the same time. This supports a rolling upgrade, for example in Kubernetes, where the earlier instances continue to process requests while the new instances start. The database migration of nevisAuth 9.2611 does the following:
- It creates the table
session_indexand copies the index of the existing sessions to this table. - It keeps the column
SESSION_INDEXof the tableTNSSA_AUTH_SESSION_CACHE, which the earlier versions use. - It adds triggers. When an earlier instance writes an index value to the column
SESSION_INDEX, the triggers copy the value to the tablesession_index.
nevisAuth 9.2611 writes the index to the table session_index. It also writes the hash of the first entry of attributes to the column SESSION_INDEX. The earlier instances thus find the sessions of the new instances, and the new instances find the sessions of the earlier instances.
Conditions for a rolling upgrade
A rolling upgrade is supported only if all of the following conditions are true:
- The earlier version indexes with
attributeMapping="hash". This is the default value, and nevisAdmin 4 always uses it. - During the upgrade,
attributescontains only the attribute that the earlier version indexes, by defaultch.nevis.session.loginid. - OpenID Connect back-channel logout and RP-initiated logout are not configured during the upgrade.
- The database migration is complete before the first instance of nevisAuth 9.2611 starts. The nevisauth-dbschema image contains the migration. If you manage the schema yourself, run the statements in Session index in the database. Automatic schema setup does not do the migration, see Automatic schema setup during an upgrade.
After all instances run nevisAuth 9.2611, you can add index attributes, and configure OpenID Connect logout. The following limitations are the reason for conditions 2 and 3:
- Earlier instances do not index the additional attributes. A lookup by an additional attribute does not find a session that an earlier instance stored last.
- Earlier instances do not record the OpenID Connect clients of a session, and do not send logout tokens when they end a session.
If a condition is not true, upgrade with all instances stopped, see Upgrading with all instances stopped.
Rolling upgrade with nevisAdmin 4
In Kubernetes deployments, the 'nevisAuth Database' pattern runs the database migration as part of the deployment. Do the upgrade in two deployments:
- Upgrade to nevisAuth 9.2611 without the patterns for OpenID Connect logout. Deploy, and wait until all nevisAuth pods run the new version.
- Add the patterns for OpenID Connect logout, and deploy again. These patterns add index attributes.
For the configuration of OpenID Connect logout, see OpenID Connect back-channel logout and RP-initiated logout.
Automatic schema setup during an upgrade
With automatic schema setup (connectionAutomaticDbSchemaSetup="true"), nevisAuth 9.2611 creates the table session_index at startup. It does not copy the index of the existing sessions, and it does not create the triggers. This also applies to classic deployments with nevisAdmin 4, where the 'nevisAuth Database' pattern enables automatic schema setup.
Without the triggers, the new instances do not find the sessions that the earlier instances store by attribute. Do one of the following:
- Run the statements in Session index in the database before the first instance of nevisAuth 9.2611 starts. A rolling upgrade is then supported.
- Upgrade with all instances stopped.
Index attribute other than the login ID
The database migration stores the copied index values under the attribute name ch.nevis.session.loginid. If the earlier version indexes another attribute, set the environment variable FLYWAY_PLACEHOLDERS_LEGACY_INDEX_ATTRIBUTE of the nevisauth-dbschema migration job to the name of this attribute. If you run the statements yourself, replace ch.nevis.session.loginid in the statements.
Upgrading with all instances stopped
Stop all instances for the upgrade if a condition for a rolling upgrade is not true, for example if the earlier version uses attributeMapping="none" or attributeMapping="unicodeEscape":
- Stop all nevisAuth instances.
- Back up the session database.
- Run the database migration. If you manage the schema yourself, run the statements in Session index in the database. If you use back-channel logout with the database store, also create its tables, see Setting up the back-channel logout tables manually.
- Update the
esauth4.xmlof each instance, as described in Shared database connection pools and Session indexing configuration. - Install nevisAuth 9.2611 on all instances.
- Start the nevisAuth instances.
The migration copies only the index values that the earlier version stored with attributeMapping="hash". With another attributeMapping, lookups by attribute do not find the sessions that started before the upgrade, until these sessions end.
nevisAuth 9.2611 writes to the column SESSION_INDEX if session indexing is enabled. If the column does not exist, nevisAuth cannot store sessions in the database. Keep the column and the triggers. A later version of nevisAuth removes them.
Migrating the configuration and the database
Shared database connection pools
nevisAuth 9.2611 connects to databases through shared, named connection pools. The connection settings of <RemoteSessionStore> and <RemoteOutOfContextDataStore> are removed. If the configuration still contains them, nevisAuth does not start.
Move all connection* attributes of each feature to a <DatabaseConnectionPool> element in <ConnectionPools>, and reference the connection pool with connectionPoolRef. Place <ConnectionPools> in <esauth-server>, before <SessionCoordinator>. The features keep their other settings, for example reaperPeriod.
<SessionCoordinator ...>
<LocalSessionStore .../>
<RemoteSessionStore
connectionUrl="jdbc:postgresql://db:5432/nevisauth"
connectionUser="nevisauth" connectionPassword="secret"
connectionMaxPoolSize="10"
reaperPeriod="60" syncThreads="5"/>
</SessionCoordinator>
<RemoteOutOfContextDataStore
connectionUrl="jdbc:postgresql://db:5432/nevisauth"
connectionUser="nevisauth" connectionPassword="secret"
connectionMaxPoolSize="10"
reaperPeriod="60"/>
<ConnectionPools>
<DatabaseConnectionPool name="MainDb"
connectionUrl="jdbc:postgresql://db:5432/nevisauth"
connectionUser="nevisauth" connectionPassword="secret"
connectionMaxPoolSize="20"/>
</ConnectionPools>
<SessionCoordinator ...>
<LocalSessionStore .../>
<RemoteSessionStore connectionPoolRef="MainDb" reaperPeriod="60" syncThreads="5"/>
</SessionCoordinator>
<RemoteOutOfContextDataStore connectionPoolRef="MainDb" reaperPeriod="60"/>
Consider the following points when you migrate:
- If the features use the same database and the same credentials, use one connection pool for all of them. In earlier versions, each feature opened its own connection pool.
- The default
connectionMaxPoolSizeof a connection pool is 20. In earlier versions, the default of each feature was 10. SetconnectionMaxPoolSizeexplicitly to match the connection limit of your database. connectionAutomaticDbSchemaSetupis now an attribute of the connection pool. It applies to all features that use the connection pool. If a feature needs a different value, give it its own connection pool.
For all attributes and the sizing, see Database connection pools.
Session indexing configuration
The <SessionIndexing> element has a new attribute attributes, which contains a comma-separated list of the session attributes to index. The attributes attribute and attributeMapping are removed. nevisAuth always stores the indexed values as SHA-256 hashes, so attributeMapping has no replacement.
If the configuration still contains attribute or attributeMapping, nevisAuth does not start. The log contains an error like the following one:
Cannot load EsAuth server config from /var/opt/nevisauth/default/conf/esauth4.xml: Error on line 12 of document file:/var/opt/nevisauth/default/conf/esauth4.xml: Attribute "attribute" must be declared for element type "SessionIndexing".
Replace the attributes as follows:
<SessionIndexing attribute="ch.nevis.session.loginid" attributeMapping="hash"/>
<SessionIndexing attributes="ch.nevis.session.loginid"/>
If <SessionIndexing> has no attributes, nevisAuth indexes the login ID (ch.nevis.session.loginid), as before. 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, for example in the session management API.
For the attributes that OpenID Connect logout needs, see Session indexing.
All nevisAuth instances that share a session database must use the same <SessionIndexing> configuration.
Session index in the database
With a remote session store, nevisAuth 9.2611 stores the index in the new table session_index. For the earlier versions, nevisAuth also writes the hash of the first entry of attributes to the column SESSION_INDEX of the table TNSSA_AUTH_SESSION_CACHE. See Upgrading nevisAuth instances that share a session database.
- The nevisauth-dbschema image runs the database migration, which contains the statements below.
- With automatic schema setup (
connectionAutomaticDbSchemaSetup="true"on the connection pool of<RemoteSessionStore>), nevisAuth creates the tablesession_indexat startup if<SessionIndexing>is configured. nevisAuth does not copy the existing index to the tablesession_index, and does not create the triggers. To copy the index and to create the triggers, run the statements below before nevisAuth 9.2611 starts. - If you manage the schema yourself, run the following statements.
The statements create the table session_index, copy the index of the existing sessions, and create the triggers that copy the index values of earlier instances. If the earlier version indexes an attribute other than the login ID, replace ch.nevis.session.loginid with the name of this attribute.
CREATE TABLE IF NOT EXISTS `session_index` (
`keyname` VARCHAR(255) NOT NULL,
`valuehash` BINARY(32) NOT NULL,
`session_id` VARCHAR(255) NOT NULL,
PRIMARY KEY (`keyname`, `valuehash`, `session_id`),
INDEX (`session_id`),
FOREIGN KEY (`session_id`) REFERENCES `TNSSA_AUTH_SESSION_CACHE`(`SESSION_ID`) ON DELETE CASCADE
) ENGINE=InnoDB ROW_FORMAT=DYNAMIC;
-- Copy the index of the existing sessions (only values stored with attributeMapping="hash").
INSERT INTO `session_index` (`keyname`, `valuehash`, `session_id`)
SELECT 'ch.nevis.session.loginid', UNHEX(`SESSION_INDEX`), `SESSION_ID`
FROM `TNSSA_AUTH_SESSION_CACHE`
WHERE CHAR_LENGTH(`SESSION_INDEX`) = 64
AND `SESSION_INDEX` REGEXP '^[0-9a-fA-F]{64}$'
AND BINARY `SESSION_INDEX` = LOWER(`SESSION_INDEX`);
-- Copy the index values that earlier instances write to the column SESSION_INDEX.
DELIMITER //
CREATE TRIGGER tnssa_session_index_legacy_ai
AFTER INSERT ON `TNSSA_AUTH_SESSION_CACHE` FOR EACH ROW
BEGIN
IF NEW.`SESSION_INDEX` REGEXP '^[0-9a-f]{64}$' AND BINARY NEW.`SESSION_INDEX` = LOWER(NEW.`SESSION_INDEX`) THEN
INSERT IGNORE INTO `session_index` (`keyname`, `valuehash`, `session_id`)
VALUES ('ch.nevis.session.loginid', UNHEX(NEW.`SESSION_INDEX`), NEW.`SESSION_ID`);
END IF;
END//
CREATE TRIGGER tnssa_session_index_legacy_au
AFTER UPDATE ON `TNSSA_AUTH_SESSION_CACHE` FOR EACH ROW
BEGIN
IF NOT (NEW.`SESSION_INDEX` <=> OLD.`SESSION_INDEX`) THEN
DELETE FROM `session_index`
WHERE `session_id` = NEW.`SESSION_ID` AND `keyname` = 'ch.nevis.session.loginid';
IF NEW.`SESSION_INDEX` REGEXP '^[0-9a-f]{64}$' AND BINARY NEW.`SESSION_INDEX` = LOWER(NEW.`SESSION_INDEX`) THEN
INSERT IGNORE INTO `session_index` (`keyname`, `valuehash`, `session_id`)
VALUES ('ch.nevis.session.loginid', UNHEX(NEW.`SESSION_INDEX`), NEW.`SESSION_ID`);
END IF;
END IF;
END//
DELIMITER ;
CREATE TABLE IF NOT EXISTS session_index (
keyname VARCHAR(255) NOT NULL,
valuehash BYTEA NOT NULL,
session_id VARCHAR(255) NOT NULL REFERENCES TNSSA_AUTH_SESSION_CACHE(SESSION_ID) ON DELETE CASCADE,
PRIMARY KEY (keyname, valuehash, session_id)
);
CREATE INDEX IF NOT EXISTS session_index_session_id_idx ON session_index (session_id);
-- Copy the index of the existing sessions (only values stored with attributeMapping="hash").
INSERT INTO session_index (keyname, valuehash, session_id)
SELECT 'ch.nevis.session.loginid', decode(legacy.session_index, 'hex'), legacy.session_id
FROM (
SELECT SESSION_ID, SESSION_INDEX
FROM TNSSA_AUTH_SESSION_CACHE
WHERE SESSION_INDEX ~ '^[0-9a-f]{64}$'
) legacy;
-- Use the index names of nevisAuth 9.2611 on TNSSA_AUTH_SESSION_CACHE.
DROP INDEX IF EXISTS session_reap_timestamp_idx;
DROP INDEX IF EXISTS session_index_idx;
CREATE INDEX IF NOT EXISTS session_reap_timestamp_idx ON TNSSA_AUTH_SESSION_CACHE (ABSTO);
CREATE INDEX IF NOT EXISTS session_index_legacy_idx ON TNSSA_AUTH_SESSION_CACHE (SESSION_INDEX);
-- Copy the index values that earlier instances write to the column SESSION_INDEX.
CREATE OR REPLACE FUNCTION tnssa_session_index_legacy_sync() RETURNS trigger AS $$
BEGIN
IF TG_OP = 'UPDATE' THEN
IF NEW.SESSION_INDEX IS NOT DISTINCT FROM OLD.SESSION_INDEX THEN
RETURN NEW;
END IF;
DELETE FROM session_index
WHERE session_id = NEW.SESSION_ID AND keyname = 'ch.nevis.session.loginid';
END IF;
IF NEW.SESSION_INDEX ~ '^[0-9a-f]{64}$' THEN
INSERT INTO session_index (keyname, valuehash, session_id)
VALUES ('ch.nevis.session.loginid', decode(NEW.SESSION_INDEX, 'hex'), NEW.SESSION_ID)
ON CONFLICT DO NOTHING;
END IF;
RETURN NEW;
END $$ LANGUAGE plpgsql;
CREATE TRIGGER tnssa_session_index_legacy_trg
AFTER INSERT OR UPDATE OF SESSION_INDEX ON TNSSA_AUTH_SESSION_CACHE
FOR EACH ROW EXECUTE FUNCTION tnssa_session_index_legacy_sync();
Consider the following points:
- The data user of the session store needs
SELECT,INSERT,UPDATE, andDELETEonsession_index. - The user that runs the statements must be allowed to create triggers. In MariaDB, this is the
TRIGGERprivilege. If binary logging is enabled in MariaDB, creating triggers also requires theSUPERprivilege orlog_bin_trust_function_creators=1. In PostgreSQL, run the statements as the owner of the tableTNSSA_AUTH_SESSION_CACHE. - Do not remove the column
SESSION_INDEX. nevisAuth 9.2611 writes to it.
The INSERT statement copies the index of the existing sessions to the table session_index. The statement copies only the values that the earlier version stored with the default attributeMapping="hash". If you do not run the statement, or if the earlier version used another attributeMapping, lookups by attribute do not find the sessions that started before the upgrade, until these sessions end.