ThrottleSessionsState

Introduction and overview

The ThrottleSessionsState may be used to limit the number of sessions matching given criteria. For example, it can be used to limit the number of sessions per loginId. The exact criteria are defined in a query. Matching sessions are identified by applying the query to the set of existing sessions. The AuthState relies on session indexing to perform this query consistently and with high performance in architectures with shared sessions.

info

In setups with a single nevisAuth instance, ThrottleSessionsState can be used without session sharing. Setups with multiple nevisAuth instances are required to have session sharing enabled . Otherwise, each nevisAuth instance will only be able to see and throttle locally known sessions.

The algorithm of the AuthState can be summarized as follows:

1. Evaluate configured queryValue to compute the query to execute.
2. Use the session indexing functionality .
3. If the resulting set of sessions includes the caller session (user session that executes the AuthState), remove it from the set.
4. Compare the number of sessions in the result set with the configured maxMatchingSessions to decide if some or all of the sessions should be terminated.
5. If maxMatchingSessions is exceeded, iterate over the sessions by their creation time (the oldest first) and terminate them until maxMatchingSessions is reached.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.standard.ThrottleSessionsState
Logging	StdStates
Auditing	none
Marker	throttling/NONE (marking both terminated sessions and executing session)
Methods	process

Properties

• queryAttribute (string, -)

  Session attribute on which sessions shall be queried in step 2 above.

  • This is optional for scenarios where the session cache is configured with enableIndexing. If queryAttribute is set, it must be identical to the enableIndexing value configured (see Session indexing).
  • For local sessions without configured enableIndexing, this value must be set. In this case, querying the sessions will be done by simple iteration of all sessions.

• queryValue (string, "${request:loginId}")

  Value that is used to find all matching sessions in step 1 above.

• maxMatchingSessions (int,0)

  Maximum number of sessions matching the query that are left alive. The caller session is never included in this sum: configuring 0 (the default) essentially means that only the caller session may match the query.

  If this value is not 0 (i.e., some matching sessions should be left alive), then the matching sessions are terminated in order of creation time: The most recent sessions survive.

Input

none

Transitions

• ok

  Processing of AuthState completed without errors.

• sessionsTerminated (optional)

  Matching sessions were found and some sessions were terminated. Fallback to ok if not configured.

• matchingSessionsExist (optional)

  Matching sessions were found, but no sessions were terminated. Fallback to ok if not configured.

Output

• notes:sessionsMatched

  number of sessions that matched the query

• notes:sessionsTerminated

  number of sessions that were terminated

• notes:terminatedSessions

  comma-separated list of session IDs of terminated sessions

Errors

none

Notes

none

Example

The following example ensures that no other session has the same userId as the current user. It assumes session indexing over ch.nevis.session.userid (see Session indexing). This example must be used after authentication.

<AuthState name="UserSessionThrottling" class="ch.nevis.esauth.auth.states.standard.ThrottleSessionsState" final="false">
  <ResultCond name="ok" next="AuthDone" />
  <Response value="AUTH_ERROR">
    <Gui name="AuthErrorDialog"/>
  </Response>
  <property name="queryValue" value="${request:userId}" />
</AuthState>