AmSessionIdleTimeoutFilter
Forces the revocation of AM sessions that have been idle for a specified duration. The AmSessionIdleTimeoutFilter issues an authenticated and encrypted JWT to track activity on the AM session and conveys it within a persistent cookie.
To help honor timeout, the persistent cookie is configured to expire at the same time as the tracking token. Without a persistent cookie, the browser is more likely to clear the side-car cookie and PingGateway is more likely to consider the session as timed out.
The tracking token contains the following parts:
-
The time when the user was last active
-
A hash of the AM session cookie, used to bind the tracking token to the AM session cookie
-
The idle timeout
Multiple filter instances can share the same tracking token, for example, in a clustered PingGateway configuration, or when a federation of applications protected by authentication filters need to have a flexible idle timeout strategy.
AmSessionIdleTimeoutFilter requires the following configuration:
-
In AM, client-side sessions must be enabled for the realm in which the tracking token operates. See Configure client-side sessions in AM’s Sessions Guide.
-
In AM, client-side session denylisting must be enabled. See Configure client-side session denylisting in AM’s Sessions Guide.
-
The AmSessionIdleTimeoutFilter must be placed in a route before a filter that uses the AM session token, such as a SingleSignOnFilter or PolicyEnforcementFilter.
-
In production environments, and when multiple AmSessionIdleTimeoutFilters use the same tracking token, the encryption must not rely on the default configuration. It must be configured identically on each filter that uses the tracking token.
The following image shows the flow of information when an AmSessionIdleTimeoutFilter sits in front of a CrossDomainSingleSignOnFilter, to manage AM session timeout.
[1-5] When the AmSessionIdleTimeoutFilter receives an unauthenticated request, it passes the request along the chain, and the CrossDomainSingleSignOnFilter manages authentication.
[6-8] When the AmSessionIdleTimeoutFilter receives an authenticated request, it checks that the AM session token is valid, and then passes the request along the chain.
[9-10] If the AM session was valid, the AmSessionIdleTimeoutFilter issues a tracking token on the response flow, containing the following information:
-
Hash of the AM session token
-
Current timestamp
-
Idle timeout of the current filter
If the AM session was not valid, the AmSessionIdleTimeoutFilter does nothing on the response flow.
[11-12] The AmSessionIdleTimeoutFilter places the tracking token in persistent tracking cookie, and sends it with the response, to be used in the next request.
[13-15] When the same or another AmSessionIdleTimeoutFilter receives an authenticated request with a tracking token, it checks that the AM session token is valid, and checks that tracking token hash is bound to the AM session.
[16] Depending on the strategy set by idleTimeoutUpdate, the
AmSessionIdleTimeoutFilter selects the value for idleTimeout from the tracking
token (set by the AmSessionIdleTimeoutFilter in a previous request) or from
its own value of idleTimeout (if this is a different instance of
AmSessionIdleTimeoutFilter).
The AmSessionIdleTimeoutFilter checks for AM session timeout. If the last activity time plus the idle timeout is before the current time, the session has timed out. For example, a session with the following values has timed out:
-
last activity time: 15h30 today
-
idle timeout: 5 mins
-
current time: 15h40
[17-21] The AM session has timed out, so the AmSessionIdleTimeoutFilter does the following:
-
Forces AM to revoke the session.
-
Passes the request along the chain.
-
Expires the tracking cookie on the response flow, and sends it with the response.
[22-26] The session has not timed out, so the AmSessionIdleTimeoutFilter does the following:
-
Passes the request along the chain.
-
Updates the tracking token on the response flow based on the
idleTimeoutUpdatestrategy. -
Places the tracking token in a persistent tracking cookie, and sends it with the response, to be used in the next request.
Usage
{
"name": string,
"type": "AmSessionIdleTimeoutFilter",
"config": {
"amService": AmService reference,
"idleTimeout": configuration expression<duration>,
"sessionToken": runtime expression<string>,
"removeAmSessionFilter": Filter reference,
"idleTimeoutUpdate": configuration expression<enumeration>,
"secretsProvider": SecretsProvider reference,
"encryptionSecretId": configuration expression<secret-id>,
"encryptionMethod": configuration expression<string>,
"cookie": object
}
}Properties
"amService": AmService reference, required-
The AmService that refers to the AM instance that issue tracked session token.
"idleTimeout": configuration expression<duration>, required-
The time a session can be inactive before it is considered as idle.
When an AmSessionIdleTimeoutFilter creates the tracking token, the token’s value for
idleTimeoutis set by this property. When a different AmSessionIdleTimeoutFilter accesses the same tracking token, depending on the strategy set byidleTimeoutUpdate, the token’s value foridleTimeoutcan be updated by the second AmSessionIdleTimeoutFilter. "sessionToken": runtime expression<string>, optional-
The location of the AM session token in the request. The following example accesses the first value of the request cookie
iPlanetDirectoryPro:"sessionToken": "${request.cookies['iPlanetDirectoryPro'][0].value}"You can find more information in Find the AM session cookie name.
Default:
${request.cookies['<cookie name defined in the referenced AmService>'][0].value} "removeAmSessionFilter": Filter reference, optional-
A filter to remove the AM session details from the request when the session is no longer valid.
This helps in load-balanced AM deployments with client-side sessions where AM servers aren’t necessarily in sync regarding expired client-side sessions. Set this to a custom filter if the AM session token isn’t in the AM session cookie.
Default: a filter that removes the AM session token based on the AM session cookie name.
"idleTimeoutUpdate": configuration expression<enumeration>, required-
When multiple AmSessionIdleTimeoutFilters use the same tracking token, this property defines what idle timeout to use for the request and how to set the idle timeout for the tracking token in the response.
Use one of the following values:
-
ALWAYS: Enforce the idle timeout from this filter; in the response, set the new tracking token idle timeout to the idle timeout of this filter. -
DECREASE_ONLY: Enforce the shortest idle timeout from either this filter or the tracking token; in the response, set the new tracking token idle timeout to the shortest of the two. -
INCREASE_ONLY: Enforce the longest idle timeout from either this filter or the tracking token; in the response, set the new tracking token idle timeout to the longest of the two. -
INCREASE_ONLY_THEN_ALWAYS: Enforce the longest idle timeout from either this filter or the tracking token; in the response, set the new tracking token idle timeout to the idle timeout of this filter. -
NEVER: Enforce the idle timeout from the tracking token; in the response, set the new tracking token idle timeout to the idle timeout of the old tracking token.
PingGateway uses the new tracking token on the next interaction with an AmSessionIdleTimeoutFilter.
Default:
ALWAYS -
"secretsProvider": SecretsProvider reference, optional-
The SecretsProvider to query for secrets to encrypt the tracking token.
"encryptionSecretId": configuration expression<secret-id>, optional-
The secret ID of the encryption key used to encrypt the tracking cookie.
This secret ID must point to a CryptoKey`.
In production environments, and when multiple AmSessionIdleTimeoutFilters use the same tracking cookie, the encryption must not rely on the default configuration. It must be configured identically on each filter that uses the cookie.
Authenticated encryption is achieved with a symmetric encryption key. Therefore, the secret must refer to a symmetric key.
For more information, refer to RFC 5116.
Default: When no
secretsProvideris provided, PingGateway generates a random symmetric key for authenticated encryption.
"encryptionMethod": configuration expression<string>, optional-
The algorithm to use for authenticated encryption. For information about allowed encryption algorithms, refer to RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.
Default: A256GCM
"cookie": object, optional-
Configuration of the activity tracking cookie.
{ "name": configuration expression<string>, "domain": configuration expression<string>, "httpOnly": configuration expression<boolean>, "path": configuration expression<string>, "sameSite": configuration expression<enumeration>, "secure": configuration expression<boolean> }"name": configuration expression<string>, optional-
The cookie name.
Default:
x-ig-activity-tracker
"domain": configuration expression<string>, optional-
Domain to which the cookie applies.
Default: The fully qualified hostname of the PingGateway host.
"httpOnly": configuration expression<boolean>, optional-
Flag to mitigate the risk of client-side scripts accessing protected cookies.
Default:
true "path": configuration expression<string>, optional-
Path to apply to the cookie.
Default:
/ "sameSite": configuration expression<enumeration>, optional-
Options to manage the circumstances in which a cookie is sent to the server. Use one of the following values to reduce the risk of CSRF attacks:
-
STRICT: Send the cookie only if the request was initiated from the cookie domain. Not case-sensitive. Use this value to reduce the risk of cross-site request forgery (CSRF) attacks. -
LAX: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain. Not case-sensitive. Use this value to reduce the risk of cross-site request forgery (CSRF) attacks. -
NONE: Send the cookie whenever a request is made to the cookie domain. With this setting, consider settingsecuretotrueto prevent browsers from rejecting the cookie. For more information, refer to SameSite cookies.
Default: Null
-
"secure": configuration expression<boolean>, optional-
Flag to limit the scope of the cookie to secure channels.
Default:
false
Example
{
"type": "AmSessionIdleTimeoutFilter",
"config": {
"sessionToken": "${request.cookies['iPlanetDirectoryPro'][0].value}",
"amService": "AmService",
"idleTimeout": "1 minute",
"idleTimeoutUpdate": "ALWAYS",
"cookie": {
"name": "x-ig-activity-tracker",
"domain": null,
"path": "/",
"secure": false,
"httpOnly": true,
"sameSite": null
},
"secretsProvider": "secrets-provider-ref",
"encryptionMethod": "A256GCM",
"encryptionSecretId": "crypto.key.secret.id"
}
}