VirtualSessionFilter
The VirtualSessionFilter is in the process of being faded out. Do not use this filter for new setups. Instead, use the SessionManagamentFilter, with the parameter Identification of the SessionManagamentFilter set to "custom".
Example adaptation
The nevisproxy package used to contain example configurations for the VirtualSessionFilter (alternative session creation and switchable subsession). As of release 3.13.9.0, these sample configurations have been adapted by the SessionManagmentFilter. They are added to the nevisproxy package in /opt/nevisproxy/examples/session_store/ (Alternative_session_association_with_custom_based_SMF.example and Switchable_subsessions_with_custom_based_SMF.example).
The VirtualSessionFilter makes it possible to place an additional, virtual session after an already existing session. All filters that come after the VirtualSessionFilter in the filter chain will only see the virtual session (instead of the original session). If there is no original session, the virtual session is the initial session.
The unique identifier of the virtual session is defined by the virtual session filter attributes RequiredIdentifiers and OptionalIdentifiers (for an explanation, see the following table). These attributes are in turn based on identifiers of the client request (e.g., request header settings, environment variables, client certificate, a constant). nevisProxy calculates a SHA1 hash digest based on the attributes and saves this hash value as the VirtualSession-Identifier.
Besides attributes of the client request, it is also possible to use attributes of the response, such as a back-end cookie (e.g., JSESSIONID cookie), to define the unique virtual session identifier.For a description of some use cases, see the subchapter Sample configurations further below.
ch::nevis::isiweb4::filter::auth::VirtualSessionFilter
libIdentificationFilters.so.1
Configuration
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| RequiredIdentifiers | string; required | List of attributes used to calculate the unique identifier for the virtual session (the VirtualSession-Identifier (ID)):<SRC>:<VAR>[;<SRC>:<VAR>...].<SRC>: AUTH |
| RequiredIdentifiers | string; required | List of attributes used to calculate the unique identifier for the virtual session (the VirtualSession-Identifier (ID)):<SRC>:<VAR>[;<SRC>:<VAR>...].<SRC>: AUTH |
| OptionalIdentifiers | string; optional | List of optional attributes nevisProxy needs to calculate the unique identifier for the virtual session (the VirtualSession-ID):<SRC>:<VAR>[;<SRC>:<VAR>...]. <SRC>: AUTH |
| IdentifierViolationPolicy | New line separated list of conditions and enum. The enum must have one of the following values: abort, skip, response; required | Defines what should be done if a required identifier (needed to calculate the unique virtual session ID) is missing. The available options are: abort: Aborts the client request and returns an error code. skip: Skips the calculation of the unique virtual session identifier and continues without a virtual session. response: Waits for the response of the back end to build the unique virtual session identifier. Sometimes, nevisProxy may need a response from the back end to be able to calculate the unique virtual session identifier. This is relevant if nevisProxy could not find all required identifiers in the client request. In this case, the response may include the missing identifier(s). If the response does not include the needed identifiers either, nevisProxy skips the calculation of the unique session identifier and continues without a virtual session. It is possible to add a condition of the form: Condition::<VARIABLE>:<expression>nevisProxy takes the first matching condition. E.g., the following example aborts the client request altogether for hosts matching "CIDR 10.4.12.0/22". For all other hosts, nevisProxy forwards the client request to the back end without creating a virtual session: REMOTE_ADDR:CIDR/10.4.12.0/22/ abort skip |
| MaxVirtualSessionsPerClient | integer; required | Defines the maximum number of virtual sessions per parent session (the attribute name is misleading). The default value is "0".nevisProxy ignores this attribute if the attribute BindToParentSession is set to "false". In this case, the MaxVirtualSessionsPerClient attribute is irrelevant: The virtual session is not bound to the parent session but stands on its own.However, if the attribute BindToParentSession is "true", this attribute is required. We recommend setting the attribute value to "1". |
| MaxVirtualSessions | integer; required | Maximum number of virtual sessions that can be used at the same time. |
| BindToParentSession | boolean optional default: true | If set to "true", nevisProxy binds the virtual session to the parent session. If nevisProxy cannot find a parent session, it creates a new parent session. If the parent session is invalidated, all virtual sessions bound to the parent session are also invalidated. |
| OverflowPolicy | enum: abort, reap, skip; required | Defines what to do if either the maximum number of virtual sessions (MaxVirtualSessions) or the maximum number of virtual sessions per parent session (MaxVirtualSessionsPerClient) is reached. These options are available: abort: Aborts the client request and returns an error code. reap: Invalidates the oldest virtual session created by the filter. Replaces it with the new virtual session. * skip: Skips the creation of a new virtual session. Continues without a virtual session. |
| MaxInactivInterval | integer; optional | Defines the maximum inactive interval (in seconds) before the system invalidates a virtual session. If not set, the system takes the inactive interval of the parent session. In case there is no parent session, the inactive interval set in the session cache comes into effect. |
| MaxVirtualSessions.StatusCode | integer; optional | The error code that is sent to the client when the maximum number of virtual sessions (MaxVirtualSessions) is reached. |
| MaxVirtualSessionsPerClient.StatusCode | integer; optional | The error code that is sent to the client when the maximum number of virtual sessions per parent session (MaxVirtualSessionsPerClient) is reached. |
| BindToParentSession.InheritSessionAttributes | boolean; optional | If this attribute is set to "true", the virtual session inherits the attributes from the parent session. However, it saves attribute changes in its own session. This attribute is relevant only if the attribute BindToParentSession is set to "true". |
Sample configurations
It is possible to apply the virtual session filter in many different setups. Below, two typical scenarios are described:
Scenario 1: Use virtual session filter to create an alternative session association
This scenario is of use if for one reason or another the original session identifier (e.g., cookie, TLS session ID or client IP) is not adequate or cannot be used for session authentication. This scenario makes it possible to use the identifier of the virtual session instead.
This scenario may present a security risk. The VirtualSessionFilter calculates the VirtualSession-Identifier based on attributes that you specify in the filter settings. Select these attributes with care: If the calculation of the VirtualSession-ID does not result in a unique identifier, the virtual session might be shared between different users, who are all able to access the session.
To implement this scenario, configure the filter as follows:
- Map the VirtualSessionFilter in front of the IdentityCreationFilter.
- As the virtual session identifier, use the "Authorization" header with tokens to optimize the authorization overhead. Therefore, set the filter attribute RequiredIdentifiers to "HEADER:Authorization".
- Use the filter attribute MaxVirtualSessions to restrict the number of virtual sessions that is open simultaneously.
- In this scenario, there is no parent session. Therefore, set the filter attribute BindToParentSession to "false".
The code block below shows a sample configuration for this scenario:
<filter>
<filter-name>NewSessionAssociationVirtualSessionFilter</filter-name>
<filter- class>ch::nevis::isiweb4::filter::auth::VirtualSessionFilter</filter-class>
<init-param>
<param-name>RequiredIdentifiers</param-name>
<param-value>HEADER:Authorization</param-value>
</init-param>
<init-param>
<param-name>IdentifierViolationPolicy</param-name>
<param-value>abort</param-value>
</init-param>
<init-param>
<param-name>MaxVirtualSessions</param-name>
<param-value>20000</param-value>
</init-param>
<init-param>
<param-name>BindToParentSession</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>OverflowPolicy</param-name>
<param-value>reap</param-value>
</init-param>
</filter>
Scenario 2: Use virtual session filter to create switchable subsessions
This scenario is typically used to open one or more subsessions, besides the parent session, towards the back-end (application) server. In this case, the virtual session serves as the subsession.
The information on the connection state to the backend server is stored in the virtual session. This includes cookies coming from the backend. If you terminate the virtual session, nevisProxy sends a notification ("logoutURI") to the corresponding server in the backend.
Here, it is necessary to bind the virtual session (being the subsession) to the parent session. If you terminate the virtual session, the parent session remains intact. But as soon as you terminate the parent session, all virtual sessions bound to this parent are terminated automatically, too.
To implement this scenario, configure the filter as follows:
- Map the VirtualSessionFilter after the IdentityCreationFilter.
- We recommended using an alternative token issued by nevisAuth as the virtual session identifier. Therefore, set the filter attribute RequiredIdentifiers to "AUTH:
<nevisAuthToken>". - To bind the virtual session to the parent session, set the filter attribute BindToParentSession to "true" (this is the default value).
- We recommend creating only one virtual session per parent session, to keep the setup clear and manageable. Therefore, set the filter attribute MaxVirtualSessionsPerClient to "1" (this is the default value).
- In this scenario, the maximum number of virtual sessions to be open simultaneously correlates with the maximum number of allowed parent sessions and the maximum number of virtual sessions per parent. Therefore, specify the attribute MaxVirtualSessions as a function of "
<Maximum Parent Sessions> x <MaxVirtualSessionsPerClient>". - The filter attribute IdentifierViolationPolicy defines what nevisProxy must do if the required virtual session identifier is missing. In this case, nevisProxy cannot create the virtual session. If you want to allow the parent session to access the backend application instead, set the attribute to "skip".
- The filter attribute OverflowPolicy defines what nevisProxy must do if the maximum number of virtual sessions in total or per parent session is reached. We recommend setting this attribute to "reap". In this case, nevisProxy replaces the oldest virtual session with the new virtual session. The oldest session is invalidated.
The code block below shows a sample configuration for this scenario:
<filter>
<filter-name>CreateSubsessionVirtualSessionFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::auth::VirtualSessionFilter</filter-class>
<init-param>
<param-name>RequiredIdentifiers</param-name>
<param-value>AUTH:saml.assertion</param-value>
</init-param>
<init-param>
<param-name>IdentifierViolationPolicy</param-name>
<param-value>skip</param-value>
</init-param>
<init-param>
<param-name>MaxVirtualSessionsPerClient</param-name>
<param-value>1</param-value>
</init-param>
<init-param>
<param-name>MaxVirtualSessions</param-name>
<param-value><Maximum Parent Sessions> x <MaxVirtualSessionsPerClient></param-value>
</init-param>
<init-param>
<param-name>BindToParentSession</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>OverflowPolicy</param-name>
<param-value>reap</param-value>
</init-param>
</filter>
The next figure illustrates both scenarios:
