JwtSession

Configures settings for stateless sessions.

Session information is serialized as a secure JWT, that is encrypted and signed, and the resulting JWT string is placed in a cookie. The cookie contains the 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. 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": duration,
    "persistentCookie": boolean,
    "secretsProvider": SecretsProvider reference,
    "skewAllowance": configuration expression<duration>
  }
}

Properties

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

The secret ID of the encryption key used to perform authenticated encryption on the JWT.

Default: IG generates a default symmetric key for authenticated encryption. Consequently, IG instances cannot share the JWT session.

For information about supported formats for secret-id, see secret-id.

"encryptionMethod": configuration expression<string>, optional

The algorithm to use for authenticated encryption. For information about allowed encryption algorithms, see RFC 7518, section-5.1.

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.

{
  "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

Manage the circumstances in which a cookie is sent to the server. Use one of the following options to reduce the risk of cross-site request forgery (CSRF) attacks:

  • STRICT: Send the cookie only if the request was initiated from the cookie domain.

  • LAX: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain.

The value is not case-sensitive.

Default: Null; send the cookie whenever a request is made to the cookie domain.

"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" 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

For information about supported formats for duration, see duration.

"persistentCookie" 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

Example

For information about configuring a JwtSession with authenticated encryption, see "Encrypting JWT Sessions".

For information about managing multiple instances of IG in the same deployment, see "Sharing JWT Session Between Multiple Instances of IG".

More Information

For information about IG sessions, see "Sessions".

org.forgerock.openig.jwt.JwtSessionManager

Read a different version of :