Appendix E - SessionStore configuration changes introduced with 4.38.0.12

nevisAdmin4 managed instances

The following migration instructions do not apply to nevisAuth instances managed by nevisAdmin4, as no manual migration is required.

The configuration restructuring is implemented as follows:

• Session attribute configurations are moved to the SessionCoordinator element.
• Indexing configuration of sessions are moved to the SessionIndexing element.
• Local session store related configurations are moved to the LocalSessionStore element.
• Remote session store related configurations are moved to the RemoteSessionStore element.

Detailed example

Most of the changes consist of adding a prefix for easier identification and moving the attribute or property to different elements. For sake of readability, the following examples keep the element order in both configuration examples.

The following additional changes have taken place:

• The size attribute is renamed to maxSessions.
• The idPregenerate attribute is renamed to sessionIdPreGenerate. Notice that the G is capital now.
• The enableIndexing attribute is removed, use the SessionIndexing element instead.
  • The previous value on is no longer required, to turn on session indexing, the element SessionIndexing has to exist.
  • The previous value off is no longer required, to turn off session indexing, remove the element SessionIndexing.
  • The previous value your.session.attribute can be defined in the attribute attribute of the SessionIndexing element. In case the attribute is not defined, the default value is ch.nevis.session.loginid as before, when specifying on.
• The attribute failSafe is removed as it is not necessary anymore. The purpose of it was to turn on or off the remote session store. To configure the remote session, define a RemoteSessionStore element or remove it if it is not needed.
• The property syncMaxConnectionKeepAlive is renamed to connectionMaxLifeTime to better reflect its usage.

Hints

• All new attributes are validated, therefore nevisAuth will not start until all issues are fixed.
• The behaviour of the session store did not change, just the configuration attributes.
  • SessionIndexing is optional.
  • LocalSessionStore is required.
  • RemoteSessionStore is optional.

Old configuration snippet:

Old configuration snippet

<SessionCoordinator>
 <SessionCache
  initialInactivityTimeout="300"
  inactivityTimeout="86400"
  initialMaxLifetime="900"
  maxLifetime="86400"
  idRandomBytes="32"
  idPregenerate="true"
  enableIndexing="your.session.attribute"
  size="100000"
  reaperPeriod="60"
  failSafe="true">

   <property name="syncProvider"        value="jdbc"/>
   <property name="syncUser"            value="nss_auth"/>
   <property name="syncPassword"        value="nss_auth"/>
   <property name="syncTarget"          value="jdbc:mariadb://localhost:3306/NSS"/>
   <property name="syncMaxConnectionKeepAlive"     value="60000" />
   <property name="syncMaxConnectionPoolSize"     value="20"/>
   <property name="syncMaxRetry"        value="2"/>
   <property name="syncRemoteSessionReaperPeriod"     value="60" />
   <property name="syncRemoteSessionReaperInitialDelay"     value="30" />
   <property name="syncRemoteSessionReaperThreads"     value="1" />
   <property name="syncRemoteSessionAbsToTolerance"     value="10"/>
   <property name="syncRemoteSessionIndexFormat"     value="normal" />
   <property name="syncPullInitial"     value="false"/>
   <property name="syncFailRetryPeriod" value="0"/>
   <property name="syncFailRetryCount"  value="0"/>
   <property name="syncUnauthenticSessions" value="true"/>
 </SessionCache>
    ...
</SessionCoordinator>    

New configuration snippet:

New configuration snippet

<SessionCoordinator
 sessionInitialInactivityTimeout="300"
 sessionInactivityTimeout="86400"
 sessionInitialMaxLifetime="900"
 sessionMaxLifetime="86400"
 sessionIdRandomBytes="32"
 sessionIdPreGenerate="true">

 <SessionIndexing
  attribute="your.session.attribute"
  attributeMapping="none" />

 <LocalSessionStore 
  maxSessions="100000"
  reaperPeriod="60" />

 <RemoteSessionStore
  provider="jdbc"
  connectionUser="nss_auth"
  connectionPassword="nss_auth"
  connectionUrl="jdbc:mariadb://localhost:3306/NSS"
  connectionMaxLifeTime="60000"
  connectionMaxPoolSize="20"
  connectionMaxRetry="2"
  reaperPeriod="60"
  reaperInitialDelay="30"
  reaperThreads="1"   
  reaperTimeoutTolerance="10" 
  syncPullInitial="false"
  syncFailRetryPeriod="0"
  syncFailRetryCount="0"
  storeUnauthenticatedSessions="true"/>
   ...
</SessionCoordinator>   

Changes in default values

In case nothing is set in the esauth4.xml.

SessionCoordinator

attribute	old	new
sessionInitialInactivityTimeout	300	600
sessionInactivityTimeout	86400	28800
sessionInitialMaxLifetime	900	1200
sessionMaxLifetime	86400	28800
sessionIdRandomBytes	16	32
sessionIdPreGenerate	false	true

LocalSessionStore

attribute	old	new
maxSessions	1024	100000

RemoteSessionStore

attribute	old	new
reaperTimeoutTolerance	1800	10% of MaxLifetime
syncPullInitial	true	false
syncFailRetryPeriod	20000	100
syncFailRetryCount	3	1
storeUnauthenticatedSessions	false	true

Deprecated properties:

attribute	old	new
syncDelay	1000	0
syncRefreshInterval	-1	0
syncThreads	1	5

TokenAssembler.TokenSpec

attribute	old	new
ttl	7200	28800

Troubleshooting

Startup errors

In case you have some invalid element in the configuration, an error will occur during the startup of nevisAuth. In the following example, the SessionCoordinator had a name attribute which is not valid.

Note, that the error message has reverse logic, it says you have an unexpected element which should be defined in the schema. What, in fact needs to be done is to remove the name attribute.

Caused by: java.lang.IllegalStateException: AuthenticationManagerOperationsSkeleton: initialization failed (ch.nevis.esauth.BadConfigurationException: org.jdom2.input.JDOMParseException: Error on line 6 of document file:/var/opt/nevisauth/default/conf/esauth4.xml:
Attribute "name" must be declared for element type "SessionCoordinator".)

Wrong default values

The default values are based on the esauth4.dtd. In case you have an older instance you might have a local esauth4.dtd in your instance directory. For example: /var/opt/nevisauth/<instance>/conf/esauth4.dtd. Make sure to change your esauth4.xml DOCTYPE section to point to /opt/nevisauth/dtd/esauth4.dtd.