Session store configuration

The Connect2id server includes a store for the end-user sessions. Its configuration properties are located in

WEB-INF/sessionStore.properties

The configuration properties are grouped into sections:

Any property in the configuration file can be overridden with a Java system property, e.g. by setting the optional -D argument at JVM startup:

-DsessionStore.maxLifetime=-1

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

1. Web API

sessionStore.apiAccessTokenSHA256

The access token for the subject session store web API, represented by its SHA-256 hash (in hexadecimal format). The hashed storage is intended to prevent accidental leakage of the token through configuration files, logs, etc. The token is of type Bearer, non-expiring and must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If not specified the web API will be disabled.

The hash for a token with value ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6:

sessionStore.apiAccessTokenSHA256 = cca68b8b82bcf0b96cb826199429e50cd95a042f8e8891d1ac56ab135d096633

sessionStore.secondaryAPIAccessTokenSHA256

Optional secondary access token for the subject session store web API. Has the same format as sessionStore.apiAccessTokenSHA256. Must not be set if not needed.

sessionStore.secondaryAPIAccessTokenSHA256 = 304b07b6d8eb155a957b965831be9ce39fb098554a2d5f2047ee0a0491022dea

2. Session defaults and policies

sessionStore.maxLifetime

The default maximum session lifetime, in minutes. Applied to newly created subject sessions where the max_life value has been omitted. A negative value implies no time limit. Must not be zero.

The maximum session lifetime is used in conjunction with the maximum authentication lifetime and the maximum idle time to determine when a session should expire (whichever time event occurs first).

To set the default maximum session lifetime to 14 days (20160 minutes):

sessionStore.maxLifetime = 20160

sessionStore.authLifetime

The default maximum authentication lifetime, in minutes. Applied to newly created subject sessions where the auth_life value has been omitted. A negative value implies no time limit. Must not be zero.

The maximum authentication lifetime is used in conjunction with the maximum lifetime and the maximum idle time to determine when a session should expire (whichever time event occurs first).

To set the default maximum authentication lifetime to 24 hours (1440 minutes):

sessionStore.authLifetime = 1440

sessionStore.maxIdleTime

The default maximum session idle time, in minutes. Applied to newly created subject sessions where the max_idle value has been omitted. A negative value implies no time limit. Must not be zero.

The maximum idle time is used in conjunction with the maximum lifetime and the maximum authentication lifetime to determine when a session should expire (whichever time event occurs first).

To set the default maximum idle time to 24 hours (1440 minutes):

sessionStore.maxIdleTime = 1440

sessionStore.quotaPerSubject

The maximum number of concurrent sessions a subject may have across browsers and devices. Should typically be set to not more than ten concurrent sessions.

To set the maximum number of concurrent session to five:

sessionStore.quotaPerSubject = 5

sessionStore.onQuotaExhaustion

The login behaviour when a subject exhausts their session quota.

Policy values:

  • DENY_LOGIN -- The login request must be rejected.
  • CLOSE_OLD_SESSION -- The next expiring session for the subject must be closed and the new login request must be allowed to proceed.

To set the policy to CLOSE_OLD_SESSION:

sessionStore.onQuotaExhaustion = CLOSE_OLD_SESSION

sessionStore.acceptLegacySIDs

Set to true to accept legacy session identifiers (SID) without HMAC protection. Required to enable import of sessions from Connect2id server versions 5x and older. Defaults to false.

sessionStore.acceptLegacySIDs = false

3. Internal configuration

sessionStore.internal.subjectIndexPurgeInterval

The interval for purging orphaned subject index keys, in seconds. If -1 the purge thread is disabled. If 0 the Connect2id server will set the interval heuristically, depending on the Infinispan configuration (1 day for stateless deployments with Redis or DynamoDB, disabled in all other cases). If not specified the default value is 0.

Since v7.9.

The purge thread can be safely disabled (-1) if you're running Connect2id server 7.9 or newer and have no pre-existing subject sessions in the store.

sessionStore.internal.subjectIndexPurgeInterval = -1

sessionStore.sessionMap.expirationInterval

Overrides the default wake-up interval of the Infinispan thread for expiring subject sessions which max lifetime was reached. The default value is 300000 milliseconds, or 5 minutes. Zero (0) disables the expiration thread.

This configuration can only be set or overridden via a Java system property.

Since v7.9.

To increase the interval to one hour:

-DsessionStore.sessionMap.expirationInterval=3600000

To disable the Infinispan expiration thread when all sessions are stored in AWS DynamoDB and also automatically expired there via a "ttl" attribute:

-DsessionStore.sessionMap.expirationInterval=0