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. The tracking token contains the following parts:

The time when the user was last active
A hash of the AM session cookie, 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 IG 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, with the current timestamp and the value for idleTimeOut, using the same value for that was selected in step 16.
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>,
     "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 idleTimeout is set by this property. When a different AmSessionIdleTimeoutFilter accesses the same tracking token, depending on the strategy set by idleTimeoutUpdate, the token’s value for idleTimeout can 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}"

For more information, refer to Find the AM session cookie name.

Default: ${request.cookies['<cookie name defined in the referenced AmService>'][0].value}

idleTimeoutUpdate: configuration expression<enumeration>, required

When multiple AmSessionIdleTimeoutFilters use the same tracking token, this property selects whether to use the idleTimeout from this filter or from the tracking token.

Use one of the following values:

NEVER: Use the idle timeout from the tracking token, and ignore the idle timeout from this filter.
ALWAYS: Use the idle timeout from this filter, and ignore the idle timeout from the tracking token.
INCREASE_ONLY: Compare the idle timeout from this filter and the tracking token, and use the longest value.
DECREASE_ONLY: Compare the idle timeout from this filter and the tracking token, and use the shortest value.

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 secretsProvider is provides, IG 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 IG 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 setting secure to true to 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"
  }
}

More information

org.forgerock.openig.openam.session.AmSessionIdleTimeoutFilter

Identity Gateway 2023.11

AmSessionIdleTimeoutFilter

Usage

Properties

Example

More information