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.
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:
- Evaluate configured queryValue to compute the query to execute.
- Use the session indexing functionality .
- If the resulting set of sessions includes the caller session (user session that executes the AuthState), remove it from the set.
- 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.
- If maxMatchingSessions is exceeded, iterate over the sessions by their creation time (oldest first) and terminate them until maxMatchingSessions is reached.
Description
The following table describes 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) |
| Properties | queryAttribute . For local sessions without configuredenableIndexing*, 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. | |
| Methods | process |
| 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 |
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 . 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>