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 a cookie, which contains 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, see 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 a session cookie. Compatible types include primitive JSON structures, lists, arrays, and maps. For more information, see http://json.org.
The maximum size of a JWT cookie is 4 KB. Because encryption adds overhead, limit the size of any JSON that you store in a cookie. To reduce the JWT cookie size:
- Use the default true value for the JwtSession property useCompression, to compress the session JWT before it is placed in a cookie.
- Consider storing large data outside of the session.
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, see 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, see 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.

Authenticated encryption is achieved with a symmetric encryption key. Therefore, the secret must refer to a symmetric key.

For more information, see 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, see 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.

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, see 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, see SecretsProvider.

Default: The route’s default secret service. For more information, see 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. When a session stores large items, such as tokens, use the default value true to reduce the size of the cookie.

Default: true

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