Skip to main content
Version: 4.6.x.x LTS

SessionManagementFilter

The SessionManagementFilter is part of the Dynamic Session Management Engine, also called Dynamic Session Engine or Dynamic Session Management. With the Dynamic Session Engine, the creation and handling of sessions happens on filter chain level. Thus, it is possible to set different session management rules for different applications and/or types of user requests. This leads to a more flexible way of session handling and makes it possible to deal with certain undesirable Web2.0 patterns such as unnecessary background requests and updates. For more information on the Dynamic Session Management Engine, see the chapter Dynamic Session Management Engine.

If a session is needed, it is the SessionManagementFilter that defines the method of session binding (mostly by means of cookies) and creates as well as handles the session. Session store servlets are responsible for storing and loading the session data.

Depending on the required storage technology, the SessionManagementFilter calls for a different session store servlet. Currently, nevisProxy supports:

  • the local storage of a session via the LocalSessionStoreServlet;
  • the remote session storage in a MariaDB database by means of the MySQLSessionStoreServlet;
  • and the combination of a local and a remote storage with the MultiLevelSessionStoreServlet.

To reduce the risk of unintended session overwrite, the SessionManagementFilter utilizes a mutex mechanism. On the parameter level, nevisProxy checks whether a faster request within the same session has already updated the parameter in the session store. If this is the case, the slower request does not overwrite the data.

Classname
ch::nevis::nevisproxy::filter::session::SessionManagementFilter
Library
libNPSessionFilters.so.1

Configuration​

Servlet​

Type: string
Usage Constraints: required

Sets the session store servlet that stores the session data. The SessionManagementFilter uses the name of the session store servlet to contact the session store.

Identification​

Type: enum
Possible values: cookie, custom
Usage Constraints: required

Defines the method of session binding. Depending on the session type, you may have to set other parameters.

MaxInactiveInterval​

Type: integer
Usage Constraints: optional

Use this parameter to override the MaxInactiveInterval parameter in the SessionStoreServlet. This allows you to flexibly change the timeout for different locations.

Be aware that this timeout can be overwritten by

  • the IdentityCreationFilter via the parameter InactiveInterval
  • the LuaFilter via the expression session:setInactiveTimeout(timeout)
  • nevisAuth, for specific sessions

MaxLifetime​

Type: integer
Usage Constraints: optional

You can use this parameter to override the maximum lifetime of the session set in the underlying servlet. This allows you to flexibly change the timeout for different locations.

Note, that this parameter only works together with the dynamic session management. If you use it in connection with the legacy session management, the system will throw an error [NVCT-0015].

Be aware that this timeout can be overwritten by

  • the IdentityCreationFilter via the parameter MaxLifetime
  • the SecurityRoleFilter via the parameter MaxLifetime, and
  • the LuaFilter via the session object method session:setMaxLifetime(timeout)

UpdateTimeStamp​

Type: boolean
Usage Constraints: optional, conditional
Supported Pragmas: break only, no continue
Default: true

Sets whether to update the time stamp of the session.

UpdateTimeStampMinInterval​

Type: integer
Usage Constraints: min: 0, max: 3600
Default: 60

This parameter sets the minimum time interval between two updates of the session timestamp, in seconds. If the parameter is set to "0", the system will update the session timestamp each time a request accesses a session.

Be aware that in a worst case scenario the maximum inactive timeout may be reduced by the value you configure here.

Validation.Rules​

Type: new-line separated list of rules
Usage Constraints: optional, conditional
Syntax: AUTH|ENV|CONST|PARAM|HEADER:<attribute_name>:block|invalidate|reauth

Configures a set of rules on which attributes must not change in the same session.

  • block: The request will be blocked and 403 (Forbidden) will be returned.
  • invalidate: The session will be invalidated and a new one will be created.
  • reauth: The session is reauthenticated with an IdentityCreationFilter. When there are multiple filters capable of invoking the reauthentication, only the first one is triggered.

ForcedParameterNames​

Type: new-line separated list of parameter names
Usage Constraints: optional, experimental

This parameter defines the names of the attribute stored into a session, regardless of whether another instance modified the same attribute in the meantime.

Cookie.Name​

Type: string
Usage Constraints: required for cookie identification

Sets the name of the cookie that is sent to the client.

Cookie.HttpOnly​

Type: boolean
Usage Constraints: optional
Default: true

Sets whether to send the cookie as HttpOnly to the client.

Be aware that the HttpOnly flag might be overwritten by Navajo. For details, refer to the attribute cookieHttpOnly in the table: UserAgent attributes.

Cookie.Domain​

Type: string
Usage Constraints: optional

Sets the domain of the cookie that is sent to the client.

Cookie.Path​

Type: string
Usage Constraints: optional
Default: /

Sets the path of the cookie that is sent to the client.

Cookie.Secure​

Type: boolean
Usage Constraints: optional
Default: true

Sets whether the cookie has a secure flag.

Cookie.ExtraAttributes​

Type: new-line separated list
Usage Constraints: optional
Syntax: <name>[:<value>]

Makes it possible to add extra cookie attributes.

Cookie.Persistent​

Type: boolean
Usage Constraints: optional
Default: false

If this attribute is set to true, the Expires and Max-Age parameters will be set for the session cookie.

Cookie.OnInvalid​

Type: integer
Usage Constraints: optional, advanced, conditional
Supported Pragmas: break only, no continue

Defines a status code, which will be sent if a session cookie does not point to a valid session.

If you have two locations, an active location and a passive location and switch from the active to the passive location, a huge amount of requests will then arrive and all will get an anonymous session as soon as they trigger the login process. This can then lead to a session store overflow.

Important: If you map en ErrorFilter between this filter and the frontend, you have to set propagateHeader of the ErrorFilter to true, otherwise you risk that the invalid cookie will never be removed and no login is possible anymore.

Example: 401

Cookie.KeepOldCookieTimeout​

Type: integer
Usage Constraints: optional, min: 0, max: 10

Configures the number of seconds that a cookie is to be valid after renegotiated with a new one, for example, due to a successful login. Increasing the value can help minimize the chance of session loss during a login or step-up with parallel request.

Custom.RequiredIdentifiers​

Type: string
Usage Constraints: required for custom identification
Syntax: <SRC>:<VAR>[;<SRC>:<VAR>...]..

List of attributes needed to calculate the Hash for the Session ID. Source can be: AUTH|ENV|CONST|PARAM|HEADER.

Custom.OptionalIdentifiers​

Type: string
Usage Constraints: optional, advanced Syntax: <SRC>:<VAR>[;<SRC>:<VAR>...]..

List of attributes needed to calculate the Hash for the Session ID. Source can be: AUTH|ENV|CONST|PARAM|HEADER

Custom.IdentifierViolationPolicy​

Type: enum
Possible values: abort, skip, response Usage Constraints: advanced Default: abort

Defines what to do if at least one of the Custom.RequiredIdentifiers is missing:

  • Abort: Abort the request and return an error code.
  • Skip: Skip the calculation of the HashKey and continue without a custom session.
  • Response: Wait for the response of the backend to build the identifier, if not all identifiers have been found before calling the backend.

Custom.BindToParentSession​

Type: boolean
Usage Constraints: optional
Default: false

If set to true, the custom session will be bound to the parent session. It means, that if the parent session is invalidated, all custom sessions bound to it will be invalidated as well. However, a child session can be invalidated independently of the parent session. If no parent session can be found, a new parent session will be created.

Custom.BindToParentSession.MaxSessionsPerParent​

Type: integer
Usage Constraints: optional, advanced, min: 1, max: 100

Will only be evaluated if Custom.BindToParentSession is true.

Defines the maximal number of custom sessions that the parent may have. If the limit is reached, the oldest (by access time) will be invalidated. Be aware that if you set the limit to more than 10, the performance may decrease. So you better configure custom sessions with a low inactive timeout.

Custom.BindToParentSession.InheritSessionAttributes​

Type: boolean
Usage Constraints: optional, advanced Default: false

Will only be evaluated if Custom.BindToParentSession is true.

If set to true, the custom session will inherit the attributes from the parent session but will save changes in its own session.

Custom-based SessionManagementFilter​

The sample below shows a SessionManagementFilter that applies custom identification. It creates or retrieves a session using the ID specified in the header field User-Session-Id:

<filter>
    <filter-name>CustomBasedSessionManagementFilter</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>

    <init-param>
        <param-name>Servlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
    <init-param>
        <param-name>Identification</param-name>
        <param-value>Custom</param-value>
    </init-param>
    <init-param>
        <param-name>Custom.RequiredIdentifiers</param-name>
        <param-value>HEADER:User-Session-Id</param-value>
    </init-param>
</filter>

Additional sample configurations for the SessionManagementFilter​

nevisProxy's VirtualSessionFilter is in the process of being faded out. It is recommended to use the SessionManagementFilter instead. For this reason, the example configurations for the VirtualSessionFilter - alternative session creation and switchable subsession - have been adapted by the SessionManagementFilter and added to the nevisproxy package in /opt/nevisproxy/example/session_store/ <Alternative_session_association_with_custom_based_SMF.example> and <Switchable_subsessions_with_custom_based_SMF.example>.

Logging the session storage statistics​

If you want to display session store statistics with the Dynamic Session Engine, you need to configure the bc.properties file as follows:

  • In the bc.properties file, set the property BC.Tracer.DebugProfile.NPReaperOp to "1":

    BC.Tracer.DebugProfile.NPReaperOp=1

The system will then write statistical information about the used session store solution into the navajo.log log file. In the nevisProxy software delivery package, the above property is enabled by default. For more information on trace groups and tracing properties in the bc.properties file, see the chapter: Debugging.