Version: 3.14.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.

When you use a remote session store like MariaDB for sharing sessions between several nevisProxy instances, each instance must have the same application ID (application-id). You can configure the application ID as context parameter (context-param) in the file web.xml (sie the following code sample). The value can be any string, but has to be the same for every web.xml.

<context-param>
             <param-name>application-id</param-name>
             <param-value>value</param-value>
</context-param>

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

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.

Examples

This chapter contains two examples that illustrate the SessionManagementFilter. One example shows how to set up a cookie-based SessionManagementFilter with a local session store. The second example shows the setup of a SessionManagementFilter using a MySQL session store.

The third example shows how to disable the Container Session Handling. You should do this as soon as you have configured the Dynamic Session Engine.

SessionManagementFilter with local session store

To set up a cookie-based SessionManagementFilter using a local session store, you have to configure the web.xml file as shown in the sample code below:

<filter>
  <filter-name>CookieBasedSessionManagementFilter</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>Cookie</param-value>
  </init-param>
  <init-param>
     <param-name>Cookie.HttpOnly</param-name>
     <param-value>true</param-value>
  </init-param>
  <init-param>
     <param-name>Cookie.Name</param-name>
     <param-value>NPSession</param-value>
  </init-param>
</filter>

<! - add here other filters -->

 <filter-mapping>
  <filter-name>CookieBasedSessionManagementFilter</filter-name>
  <url-pattern>/*</url-pattern>
 </filter-mapping>

<!-- add here other filter-mappings -->

<servlet>
 <servlet-name>LocalSessionStoreServlet</servlet-name>
 <servlet-class>ch::nevis::nevisproxy::servlet::cache::local::LocalSessionStoreServlet</servlet-class>
 <init-param>
  <param-name>MemorySize</param-name>
  <param-value>1073741824</param-value>
 </init-param>
 <init-param>
  <param-name>MaxInactiveInterval</param-name>
  <param-value>120</param-value>
 </init-param>
 <init-param>
  <param-name>MaxLifetime</param-name>
  <param-value>86400</param-value>
 </init-param>
</servlet>

<!-- add here other servlets followed by the servlet-mappings -->

SessionManagementFilter with MySQL session store

To set up a cookie-based SessionManagementFilter with a MySQL session store, configure the web.xml file as shown in the sample code below:

 <filter>
  <filter-name>CookieBasedSessionManagementFilter</filter-name>
  <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
  <init-param>
     <param-name>Servlet</param-name>
     <param-value>MySQLSessionStoreServlet</param-value>
  </init-param>
  <init-param>
     <param-name>Identification</param-name>
     <param-value>Cookie</param-value>
  </init-param>
  <init-param>
    <param-name>Cookie.HttpOnly</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>Cookie.Name</param-name>
    <param-value>NPSession</param-value>
  </init-param>
 </filter>

 <!-- add here other filters -->

 <filter-mapping>
  <filter-name>CookieBasedSessionManagementFilter</filter-name>
  <url-pattern>/*</url-pattern>
 </filter-mapping>

 <!-- add here other filter-mappings -->

 <servlet>
   <servlet-name>MySQLSessionStoreServlet</servlet-name>
   <servlet-class>ch::nevis::nevisproxy::servlet::cache::mysql::MySQLSessionStoreServlet</servlet-class>
   <servlet-lib>libMySQLSessionStoreServlets.so.1</servlet-lib>
   <init-param>
     <param-name>SessionsTableName</param-name>
     <param-value></param-value>
   </init-param>
   <init-param>
     <param-name>AttributesTableName</param-name>
     <param-value></param-value>
  </init-param>
  <init-param>
     <param-name>KeyToIdMapTableName</param-name>
     <param-value></param-value>
  </init-param>
  <init-param>
     <param-name>ConfigurationsTableName</param-name>
     <param-value></param-value>

  </init-param>
  <init-param>
     <param-name>UserName</param-name>
     <param-value></param-value>
  </init-param>
  <init-param>
     <param-name>Password</param-name>
     <param-value></param-value>
  </init-param>
  <init-param>
     <param-name>ConnectString</param-name>
     <param-value></param-value>
  </init-param>
 </servlet>

 <!-- add here other servlets followed by the servlet-mappings -->

Disabling the Container Session Handling

Once you have configured the Dynamic Session Engine, you can disable the Container Session Handling. To do so, set the maxEntries attribute in both the CookieCache section and the HttpSession section of the navajo.xml file to "0". See the sample code below:

  ...
   <CookieCache
    maxEntries="0"
    checkIP="false"
    cookieName="Navajo"
    maxInactiveInterval="90"
    maxLifetime=""
    randomSize="56"
   />
  ...
  <HttpSession
    maxEntries="0"
    maxAttributes="250"
    maxEntrySize=""
    maxInactiveInterval="120"
  />

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.

Troubleshooting

It is possible that the following error appears:

2017 07 14 12:48:33.173 isi3web NPMySQLSes 17199.140670833444608.c0a80d97-432f-a2508-15d40b6e08f-00000000.collab-int.adnovum.ch:443 3-ERROR : MysqlConnector_1_0::handleSqlError: An error occured executing the sql-statement 'INSERT INTO sessions(SESSION_ID, CREATION_TIME, LAST_ACCESS_TIME, INACTIVE_TIMEOUT, FINAL_TIMEOUT) VALUES (?, ?, ?, ?, ?)': ERROR(1364): Field "OWNER_ID" doesn't have a default value.

In this case, change the session table with the following SQL command:

alter table session MODIFY OWNER_ID BIGINT(22) NOT NULL DEFAULT 0;

This change is not needed for all nevisProxy versions >= 3.13.2.0

SessionManagementFilter

Configuration​

Servlet​

Identification​

MaxInactiveInterval​

MaxLifetime​

UpdateTimeStamp​

UpdateTimeStampMinInterval​

Validation.Rules​

ForcedParameterNames​

Cookie.Name​

Cookie.HttpOnly​

Cookie.Domain​

Cookie.Path​

Cookie.Secure​

Cookie.ExtraAttributes​

Cookie.Persistent​

Cookie.OnInvalid​

Cookie.KeepOldCookieTimeout​

Custom.RequiredIdentifiers​

Custom.OptionalIdentifiers​

Custom.IdentifierViolationPolicy​

Custom.BindToParentSession​

Custom.BindToParentSession.MaxSessionsPerParent​

Custom.BindToParentSession.InheritSessionAttributes​

Examples​

SessionManagementFilter with local session store​

SessionManagementFilter with MySQL session store​

Disabling the Container Session Handling​

Custom-based SessionManagementFilter​

Logging the session storage statistics​

Troubleshooting​