Session management custom properties
- AlwaysEncodeURL
- CheckSessionCookieNameOnEncodeURL
- checkSessionNewOnIsValidRequest
- CloneSeparator
- CloneSeparatorChange
- ConnectionRetryCount
- CookieSameSite
- DebugSessionCrossover
- DelayAfterDuplicateIdException
- DelayInvalidationAlarmDuringServerStartup
- ForceSessionInvalidationMultiple
- HideSessionValues
- HttpSessionCloneId
- HttpSessionIdLength
- HttpSessionIdReuse
- HttpSessionReaperPollInterval
- InvalidateOnUnauthorizedSessionRequestException
- NoAdditionalSessionInfo
- NoAffinitySwitchBack
- OptimizeCacheIdIncrements
- SecurityUserIgnoreCase
- Servlet21SessionCompatibility
- SessionIdentifierMaxLength
- SessionInvalidatorThreadPoolSize
- SessionRewriteIdentifier
- SessionTableName
- SessionTableSkipIndexCreation
- ThrowSecurityExceptionOnGetSessionFalse
- UseInvalidatedId
- UseOracleBLOB
- UseApplicationSessionsAndInvalidateAll
- UseCustomSchemaName
We can specify additional settings for session management through setting custom properties. Session management properties, like the session management configuration, can be configured at the server, application, or web module level. The following steps are for setting the custom properties for session management at the server level.
From the admin console go to...
- Servers > Server Types > WebSphere application servers > server > Session management > Additional Properties > Custom Properties > Custom Properties > New
Restart the server to instantiate your change..
AlwaysEncodeURL
The Servlet 2.5 specification specifies to not encode the URL on a response.encodeURL call if it is not necessary. To support compatibility with earlier versions when URL encoding is enabled, set the AlwaysEncodeURL custom property to true to call the encodeURL method. The URL is always encoded, even if the browser supports cookies. The property must be configured at the web container level.
CheckSessionCookieNameOnEncodeURL
Check for the existence of the HTTP session cookie when determining whether the session ID needs to be encoded in the URL. This property must be configured at the web container level. Default is false. When true, we enable the session manager to check for the existence of the HTTP session cookie when determining whether the session ID needs to be encoded in the URL.
checkSessionNewOnIsValidRequest
Specify whether the server can handle multiple simultaneous client requests when HttpSessionIdReuse is enabled. This property must be configured at the web container level.
By default, the session manager handles one client request at a time when property HttpSessionIdReuse is also enabled. Set checkSessionNewOnIsValidRequest to false to allow the session manager to handle multiple simultaneous requests from a client when HttpSessionIdReuse is enabled. If HttpSessionIdReuse is not enabled, this property has no effect.
We must restart the server for the configuration change to take effect.
The default value for this property is true.
CloneSeparator
Specify a different character as the clone separator in session cookies. The value specified must be a single character.
This property was set as a web container custom property in Version 6.1 but must now be set as a session management custom property at the web container level.
This property must be used only as a means to provide more flexibility if we have a situation where we cannot use either a colon (:), or a plus sign (+) as the clone separator in session cookies. We must understand the clone character requirements of other products running on the system before we use this property to change the clone separator character.
The fact any character can be specified as the value does not imply that the character we specify functions correctly. This fact also does not imply that IBM is responsible for fixing any problem that might arise from using an alternative character. bprac
CloneSeparatorChange
Maintain session affinity. The clone ID of the server is appended to session identifier separated by colon. On some Wireless Application Protocol (WAP) devices, a colon is not allowed. Set to true to change clone separator to a plus sign (+). This property must be configured at the web container level.
ConnectionRetryCount
Select the number of retry attempts on a database connection.
For example, when ConnectionRetryCount set to 0, the session manager attempts a database connection once only, with no retry attempt.
The default value for this property is 2.
CookieSameSite (v9.0.5.4)
Specify a SameSite attribute value to use for session cookies.
The following table shows the values for the SameSite attribute and information about each value. The values are case-insensitive.
| Value | Information |
|---|---|
| Lax | Set the SameSite attribute value on a session cookie to Lax. The session cookie that is sent is for cross-site requests that use a safe HTTP method and for same-site requests. |
| None | Set the SameSite attribute value on a session cookie to None. The session cookie that is sent is for same-site requests only. When we set the value to None, the Secure attribute is set on the session cookie. |
| Strict | Set the SameSite attribute value on a session cookie to Strict. The session cookie that is sent is for same-site requests and cross-site requests. |
| Disabled | Specify so that the SameSite attribute is not added to the session cookie. The Disabled value is the default. |
DebugSessionCrossover
Enable code to perform extra checks to verify that only the session associated with the request is accessed or referenced. Messages are logged if any discrepancies are detected.
Set to true to enable session data crossover detection.
DelayAfterDuplicateIdException
Specify how long, in milliseconds, the session manager must wait before it attempts to retrieve a session from the backend server after a SESN0196W error occurs. This property must be configured at the web container level.
The default value for this property is 500.
DelayInvalidationAlarmDuringServerStartup
Delay the startup of the invalidation alarm upon server startup by the specified number of seconds.
The default value for this property is 0.
ForceSessionInvalidationMultiple
Should session manager must wait indefinitely for a request to complete or should the session be invalidated after the specified time limit has elapsed. Defaut is 3.
- 0 (zero), the session manager waits indefinitely until a request is complete before it attempts to invalidate the session.
If our requests normally are not bound by a response time limit, specify 0 for this property.
- If we specify a positive integer, such as 1, 2, or 3, even if a session is not known to complete, the session manager attempts to invalidate the session, if the indicated time period since the last access occurred elapses. This time period is the result of multiplying the value specified for this property and the value specified for the Session Timeout property. For example, if we specify 2 minutes for the Session Timeout property and 2 for the ForceSessionInvalidationMultiple property, the session manager attempts to invalidate the session after 4 minutes.
To invalidate your sessions after a certain amount of time elapses, specify the appropriate positive integer for this property.
HideSessionValues
Prevent the logging of session attribute values in session manager traces. This property must be configured at the web container level.
Applications store these session attribute values. Default is true.
HttpSessionCloneId
Change the clone ID of the cluster member. Within a cluster, this ID must be unique to maintain session affinity. When set, this name overwrites the default name generated by WAS. This property must be configured at the web container level.
(Dist) Default clone ID length: 8 or 9
(iSeries) (ZOS) Default clone ID length: 40
(ZOS) HttpSessionEnableUnmanagedServerReplication
Set true if we want to enable servant failover by replicating session data to a controller managed data space. The default is false.
HttpSessionIdLength
Configure the session identifier length. Do not use an very low value; using a low value results in reduced number of combinations possible, which increases the risk of guessing the session identifier. In a cluster, all cluster members must be configured with same ID length. Allowed range: 8 to 128. Default length: 23. This property must be configured at the web container level.
HttpSessionIdReuse
The custom property HttpSessionIdReuse determines whether the session manager can use the session ID sent from a browser to preserve session data across web applications running in an environment that is not configured for session persistence. This property must be configured at the web container level.
In a multi-JVM environment that is not configured for session persistence, setting this property to true enables the session manager to use the same session information for all of a user's requests even if the web applications that are handling these requests are governed by different JVMs. The default value for this property is false. Set to true to enable the session manager to use the session ID sent from a browser to preserve session data across web applications running in an environment that is not configured for session persistence.
(ZOS) In a z/OS system that includes multiple servants, on rare occasions two requests come in at approximately the same time, and are routed to two separate servants. However, because the two requests come in at approximately the same time, they both request a new session with the same session ID. If the HttpSessionIdReuse property is set to true when this situation occurs, the following error message is logged for one of the servants, and the servant where the message is logged does not get a session:
- ExtendedMessage: BBOO0220E: SessionContext:createSession - call to establishAffinity for id id_number failed with rc 4
HttpSessionReaperPollInterval
Specify, in seconds, a wake-up interval for the process that removes invalid sessions. The value specified for this property overrides the default installation value, which is between 30 and 360 seconds, and ensures that the reaper process runs at a specific interval.
If the maximum inactive interval is less than 2 minutes, the reaper poll interval is usually between 30 to 60 seconds.
If the maximum inactive interval is more than 2 minutes and up to 15 minutes, the reaper poll interval is usually between 60 to 90 seconds.
If the maximum inactive interval is more than 15 minutes and up to 30 minutes, the reaper poll interval is usually between 120 to 180 seconds.
If the maximum inactive interval is more than 30 minutes, the reaper poll interval is usually between 240 to 300 seconds.
Because the default timeout and maximum inactive interval is 30 minutes, the reaper interval is usually between 2 and 3 minutes.
Use this property if we want the installation timed out sessions invalidated more frequently than 2 to 3 minutes. Specifying HttpSessionReaperPollInterval=120 ensures that sessions are invalidated within 2 minutes of timing out.
The minimum value for this property is 30 seconds. If a value less than the minimum is entered, the specified property is ignored and an appropriate value is automatically determined and used. The maximum inactive interval is the session timeout. The default is based on maximum inactive interval set in session management.
InvalidateOnUnauthorizedSessionRequestException
Set to true if, in response to an unauthorized request, we want the session manager to invalidate a session instead of issuing an UnauthorizedSessionRequestException error message.
When a session is invalidated, the requester can create a new session, but does not have access to any of the previously saved session data. This invalidation allows a single user to continue processing requests after a logout while still protecting session data.
The default value for this property is false.
NoAdditionalSessionInfo
Set to true to force removal of information that is not needed in session identifiers. This property must be configured at the web container level.
NoAffinitySwitchBack
Set to true to maintain affinity to the new member even after original one comes back up. When a cluster member fails, its requests that are routed to a different cluster member, and sessions are activated in that other member. Thus, session affinity is maintained to the new member, and when failed cluster member comes back up, the requests for sessions that were created in the original cluster member are routed back to it. Allowed values are true or false, where the default value is false. This property must be configured at the web container level.
Set to true when we have distributed sessions that are configured with time-based write. When we use Memory-to-memory session replication, set custom property HttpSessionCloneId to use the affinity switch back. Notice that this property has no affect on the behavior when distributed sessions are not enabled
OptimizeCacheIdIncrements
Set the OptimizeCacheIdIncrements custom property to true to make the session manager assess whether the in-memory session for a web module is older than the copy in persistent store. Setting this property resolves the continually increasing cache ID.
If HTTP session management is configured to use session persistence and the user's browser session is moving back and forth across multiple web applications, we might see extra persistent store activity as the in-memory sessions for a web module are refreshed from the persistent store. As a result, the cache IDs are continually increasing and the in-memory session attributes are overwritten by the attributes of the persistent copy. Set to true to prevent the cache IDs from continually increasing.
If the configuration is a cluster, ensure the system times of each cluster member are identical as possible.
SecurityUserIgnoreCase
Set to true if we want the session security identity and the client security identity to be considered a match even if their cases are different.
When a user configures session security integration, the session manager compares the security identity of th session owner with the security identity of the client request. Because the matching criteria is case sensitive, if these two identities do not exactly match, an UnauthorizedSessionRequestException is sent back to the client.
If we have situations where we want the session security identity and the client security identity to be considered a match even if their cases are different, add the SecurityUserIgnoreCase custom property to your Web container configuration settings, and set the property to true. When true, an UnauthorizedSessionRequestException does not occur if the session security identity and the client security identity are identical except for their cases. For example, when this property is set to true, the session security identity USER1 matches the client security identities User1 and user1.
Servlet21SessionCompatibility
Set true to enable global session behavior. In Servlet 2.2 and later, sessions are scoped at the Web module level. The default is false.
Deprecated feature: This property is deprecated. The IBMApplicationSession method replaces the function of the Servlet21SessionCompatibility custom property.
SessionIdentifierMaxLength
Use this value to set maximum length that a session identifier can grow. This property must be configured at the web container level.
In a cluster, because of fail-over when a request goes to new cluster member, session management appends a new clone ID to the existing clone ID. In a large cluster, if for some reason servers are failing more often, then it is possible that the session identifier length can be more than expected reducing room for URL. This property helps to find out the condition and takes appropriate action to address servers fail-over. When this value is specified, message is logged when specified maximum length is reached. Allowed value: integer.
SessionInvalidatorThreadPoolSize
Defines the maximum size of the thread pool for the threads that reap invalid sessions after they time out. These threads are responsible for notifying other servers if the sessions are distributed and cleaning up any local references to them. Higher frequency of sessions timing out due to a shorter timeout interval as well as a larger number of sessions due to high volume of traffic drives a need for a higher number of these threads.
The default is 50. The minimum value is 20 and the maximum value is 100.
SessionRewriteIdentifier
Change the key used with URL rewriting. The default key is jsessionid.
SessionTableName
Set the database table name. Allowed value: String. The default is SESSIONS.
Some applications might rely on method ejbCreate(...) to create the entity bean in the database. For such a requirement, setting the JVM property com.ibm.websphere.ejbcontainer.allowEarlyInsert to true overrides the default behavior.
SessionTableSkipIndexCreation
Disable index creation on server startup.
This custom property must be used only to manually create our own database indices for session persistence. However, IBM recommends that you let session manager create database indices.
To enable this property, go to the session management custom properties administrative console page, enter the SessionTableSkipIndexCreation property name, and set its value to true. Before enabling this property, make sure that the correct index does exist on your session database.
ThrowSecurityExceptionOnGetSessionFalse
Set this custom property to false to allow session management to return a null session value instead of an UnauthorizedSessionrequestException. Default is true.
UseInvalidatedId
Set true to reuse the incoming ID if the session with that ID was recently invalidated. This is a performance optimization because it prevents checking the persistent store. Default is true.
UseOracleBLOB
The UseOracleBLOB custom property creates the HTTP session database table using the Binary Large Object (BLOB) data type for the medium column. This property increases performance of persistent sessions when Oracle databases are used.
Due to an Oracle restriction, BLOB support requires use of the Oracle Call Interface (OCI) database driver for more than 4000 bytes of data. We must also ensure that a new sessions table is created before the server is restarted by dropping our old sessions table or by changing the datasource definition to reference a database that does not contain a sessions table.
To create a sessions table using the BLOB data type, use the following name-value pair:
| Name | Value |
|---|---|
| UseOracleBLOB | true |
UseApplicationSessionsAndInvalidateAll
When the invalidateAllSet method is called, not all IBMApplicationSessions objects are checked. If we are using both the IBMApplicationSessions object and the invalidateAll call, use the following name-value pair:
| Name | Value |
|---|---|
| UseApplicationSessionsAndInvalidateAll | true |
Ensure that the session manager successfully
detects the sessions table on subsequent server startups.
Set true if we are using DB2 for sessions persistence and the customSchema property
is not set to the default value in the DB2 JDBC driver.
The default is false.