JwtSession

Configures settings for stateless sessions.

Session information is serialized as a secure JWT, that is encrypted and signed, and optionally compressed. The resulting JWT string is placed in one or more JWT session cookies. The cookies contain session attributes as JSON, and a marker for the session timeout.

Use JwtSession to configure stateless sessions as follows:

Configure a JwtSession object named Session in the heap of config.json.

Stateless sessions are created when a request traverses any route or subroute in the configuration. No routes can create stateful sessions.
Configure a JwtSession object in the session property of a Route object.

When a request enters the route, IG builds a new session object for the route. Any child routes inherit the session. The session information is saved/persisted when the response exits the route. For more information, refer to Route.
Configure a JwtSession object in the session property of multiple sibling routes in the configuration, using an identical cookie name and cryptographic properties. Sibling routes are in the same configuration, with no ascending hierarchy to each other.

When a JwtSession object is declared in a route, the session content is available only within that route. With this configuration, sibling routes can read/write in the same session.

Consider the following points when you configure JwtSession:

Only JSON-compatible types can be serialized into a JWT and included in JWT session cookies. Compatible types include primitive JSON structures, lists, arrays, and maps. For more information, refer to http://json.org.
The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, IG automatically splits it into multiple cookies.
If an empty session is serialized, the supporting cookie is marked as expired and is effectively discarded.

To prevent IG from cleaning up empty session cookies, consider adding some information to the session context by using an AssignmentFilter. For an example, refer to Adding info to a session.
When HTTP clients perform multiple requests in a session that modify the content, the session information can become inconsistent.

For information about IG sessions, refer to Sessions.

Usage

{
  "name": string,
  "type": "JwtSession",
  "config": {
    "authenticatedEncryptionSecretId": configuration expression<secret-id>,
    "encryptionMethod": configuration expression<string>,
    "cookie": object,
    "sessionTimeout": configuration expression<duration>,
    "persistentCookie": configuration expression<boolean>,
    "secretsProvider": SecretsProvider reference,
    "skewAllowance": configuration expression<duration>,
    "useCompression": configuration expression<boolean>,
    "encryptionSecretId": configuration expression<secret-id>, //deprecated
    "signatureSecretId": configuration expression<secret-id>, //deprecated
    "keystore": Keystore reference, //deprecated
    "alias": string, //deprecated
    "password": configuration expression, //deprecated
    "sharedSecret": string, //deprecated
    "cookieName": string,  //deprecated
    "cookieDomain": string  //deprecated
  }
}

Properties

"authenticatedEncryptionSecretId": configuration expression<secret-id>, optional: The secret ID of the encryption key used to perform authenticated encryption on a JWT. Authenticated encryption encrypts data and then signs it with HMAC, in a single step.

This secret ID must point to a CryptoKey.

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: IG generates a default symmetric key for authenticated encryption. Consequently, IG instances cannot share the JWT session.

"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

The configuration of the cookie used to store the encrypted JWT.

The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, IG automatically splits it into multiple cookies.

Default: The cookie is treated as a host-based 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: Name of the JWT cookie stored on the user agent. For security, change the default name of cookies.

Default: openig-jwt-session
"domain" configuration expression<string>, optional: Domain from which the JWT cookie can be accessed. When the domain is specified, a JWT cookie can be accessed from different hosts in that domain.

Set a domain only if the user agent is able to re-emit cookies on that domain on its next hop. For example, to re-emit a cookie on the domain .example.com, the user agent must be able to access that domain on its next hop.

Default: The fully qualified hostname of the user agent’s next hop.
"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 protected by this session.

Set a path only if the user agent is able to re-emit cookies on the path. For example, to re-emit a cookie on the path /home/cdsso, the user agent must be able to access that path on its next hop.

Default: The path of the request that got the Set-Cookie in its response.

"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. Not case-sensitive.

With this setting, consider setting secure to true to prevent browsers from rejecting the cookie. For more information, refer to SameSite cookies.

Default: LAX

"secure": configuration expression<boolean>, optional

Flag to limit the scope of the cookie to secure channels.

Set this flag only if the user agent is able to re-emit cookies over HTTPS on its next hop. For example, to re-emit a cookie with the secure flag, the user agent must be connected to its next hop by HTTPS.

Default: false

"sessionTimeout": configuration expression<duration>, optional

The duration for which a JWT session is valid. If the supporting cookie is persistent, this property also defines the expiry of the cookie.

The value must be above zero. The maximum value is 3650 days (approximately 10 years). If you set a longer duration, IG truncates the duration to 3650 days.

Default: 30 minutes

"persistentCookie": configuration expression<boolean>,optional

Whether or not the supporting cookie is persistent:

true: the supporting cookie is a persistent cookie. Persistent cookies are re-emitted by the user agent until their expiration date or until they are deleted.
false: the supporting cookie is a session cookie. IG does not specify an expiry date for session cookies. The user agent is responsible for deleting them when it considers that the session is finished (for example, when the browser is closed).

Default: false

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the JWT session signing or encryption keys. For more information, refer to SecretsProvider.

Default: The route’s default secret service. For more information, refer to Default secrets object.

"skewAllowance": configuration expression<duration>, optional

The duration to add to the validity period of a JWT to allow for clock skew between different servers. To support a zero-trust policy, the skew allowance is by default zero.

A skewAllowance of 2 minutes affects the validity period as follows:

A JWT with an iat of 12:00 is valid from 11:58 on the IG clock.
A JWT with an exp 13:00 is expired after 13:02 on the IG clock.

Default: zero

"useCompression": configuration expression boolean, optional

A flag to compress the session JWT before it is placed in a cookie.

Compression can undermine the security of encryption. Evaluate this threat according to your use case before you enable compression.

Default: false

"encryptionSecretId": configuration expression<secret-id>, optional

The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The secret ID of the encryption key used to encrypt the JWT.

This secret ID must point to a CryptoKey.

"signatureSecretId": configuration expression<secret-id>, optional

The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The secret ID of the JWT signature required to sign and verify the JWTs. HMAC-SHA-256 is used to sign JWTs.

This secret ID must point to a GenericSecret.

The value of this attribute must be:

Base64-encoded.
At least 32 bytes (32 characters)/256 bits long after base64 decoding. If the provided key is too short, an error message is created.

Default: Random data is generated as the key, and the IG instance can verify only the sessions it has created.

"keystore": KeyStore reference, optional

The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The keystore holding the key pair with the private key used to encrypt the JWT.

Provide either the name of the KeyStore object defined in the heap or the inline KeyStore configuration object inline.

Default: When no keystore is specified, IG generates a unique key pair, and stores the key pair in memory. With JWTs encrypted using a unique key pair generated at runtime, IG cannot decrypt the JWTs after a restart, nor can it decrypt such JWTs encrypted by another IG server.

"alias": string, required when keystore is used

The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

Alias for the private key.

"password": configuration expression, required when keystore is used

The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The password to read the private key from the keystore.

"sharedSecret": string, optional

The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

Specifies the key used to sign and verify the JWTs.

This attribute is expected to be base-64 encoded. The minimum key size after base-64 decoding is 32 bytes/256 bits (HMAC-SHA-256 is used to sign JWTs). If the provided key is too short, an error message is created.

If this attribute is not specified, random data is generated as the key, and the IG instance can verify only the sessions it has created.

"cookieName": string, optional

The use of this property is deprecated; use cookie instead. For more information, refer to the Deprecated section of the Release Notes.

The name of the JWT cookie stored on the user-agent.

Default: openig-jwt-session

"cookieDomain" string, optional

The use of this property is deprecated; use cookie instead. For more information, refer to the Deprecated section of the Release Notes.

The name of the domain from which the JWT cookie can be accessed.

When the domain is specified, a JWT cookie can be accessed from different hosts in that domain.

Default: The domain is not specified. The JWT cookie can be accessed only from the host where the cookie was created.

Example

For information about configuring a JwtSession with authenticated encryption, see Encrypt JWT sessions.

For information about managing multiple instances of IG in the same deployment, refer to the Installation guide.

More information

For information about IG sessions, refer to Sessions.

org.forgerock.openig.session.jwt.JwtSessionManager

Identity Gateway 2023.11

JwtSession

Usage

Properties

Example

More information