--- title: JwtSessionManager description: "Configures session cookie and timeout settings for JWT-based sessions. Set this as the \"session\" in the AdminHttpApplication (admin.json) for administrative requests and the GatewayHttpApplication (config.json ) or individual Route for other requests." component: pinggateway version: 2026 page_id: pinggateway:reference:JwtSessionManager canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/JwtSessionManager.html revdate: 2026-02-23T12:00:00Z section_ids: usage: Usage properties: Properties JwtSessionManager-authenticatedEncryptionSecretId: authenticatedEncryptionSecretId JwtSessionManager-encryptionMethod: encryptionMethod JwtSessionManager-cookie: cookie JwtSessionManager-sessionTimeout: sessionTimeout JwtSessionManager-persistentCookie: persistentCookie JwtSessionManager-secretsProvider: secretsProvider JwtSessionManager-skewAllowance: skewAllowance JwtSessionManager-useCompression: useCompression example: Example more_information: More information --- # JwtSessionManager Configures session cookie and timeout settings for JWT-based sessions. Set this as the `"session"` in the [AdminHttpApplication (`admin.json`)](AdminHttpApplication.html) for administrative requests and the [GatewayHttpApplication (`config.json` )](GatewayHttpApplication.html) or individual [Route](Route.html) for other requests. The user-agent stores the session data, and PingGateway puts the session data in a JWT stored as one or more session cookies on the user-agent. Learn more about session management in [PingGateway sessions](../about/about-sessions.html). ## Usage ```none { "name": string, "type": "JwtSessionManager", "config": { "authenticatedEncryptionSecretId": configuration expression, "encryptionMethod": configuration expression, "cookie": { "name": configuration expression, "domain": configuration expression, "httpOnly": configuration expression, "path": configuration expression, "sameSite": configuration expression, "secure": configuration expression }, "sessionTimeout": configuration expression, "persistentCookie": configuration expression, "secretsProvider": SecretsProvider reference, "skewAllowance": configuration expression, "useCompression": configuration expression } } ``` ## Properties ### authenticatedEncryptionSecretId `"authenticatedEncryptionSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID of the encryption key used to perform authenticated encryption on a JWT. Authenticated encryption encrypts data and signs it with HMAC in a single step. This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). Authenticated encryption is achieved with a symmetric encryption key. The secret must refer to a symmetric key. Learn more in [RFC 5116](https://www.rfc-editor.org/rfc/rfc5116.html). Default: PingGateway generates a default symmetric key for authenticated encryption. Consequently, PingGateway instances cannot share the JWT session. ### encryptionMethod `"encryptionMethod"`: *configuration expression<[string](preface.html#definition-string)>, optional* The algorithm to use for authenticated encryption. Learn about allowed encryption algorithms in [RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). Default: A256GCM ### cookie `"cookie"`: *[object](preface.html#definition-object), optional* The cookie used to store the secure JWT. Default: The cookie is treated as a host-based cookie. * `"name"` *configuration expression<[string](preface.html#definition-string)>, optional* The name of the cookie stored on the user-agent. Change the default name to improve security. At a minimum, use different names for administrative and non-administrative sessions. Default: `openig-jwt-session` - `"domain"` *configuration expression<[string](preface.html#definition-string)>, optional* The domain name for servers that can access the JWT cookie. Only set the domain if the user-agent can return cookies to servers in the domain on its next hop. Default: The fully qualified hostname of the user-agent's next hop. * `"httpOnly"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Set to `true` to mitigate the risk of client-side scripts accessing protected cookies. Default: `true` - `"path"`: *configuration expression<[string](preface.html#definition-string)>, optional* The URL path that must exist in the requested URL for PingGateway to use the cookie. Only set the path if the user-agent can return cookies for the path on its next hop. Default: `/` * `"sameSite"`: *configuration expression<[enumeration](preface.html#definition-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, set `"secure": true` to prevent browsers from rejecting the cookie. Learn more in [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite). Default: `LAX` - `"secure"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Set to `true` to limit the scope of the cookie to secure channels. When `true`, the user-agent can return cookies only over HTTPS. The user-agent must be connected to its next hop by HTTPS. Default: `false` ### sessionTimeout `"sessionTimeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The duration of a valid JWT session. The cookie expires after this duration. The value must be greater than zero and at most 3650 days (approximately 10 years). If you set a longer duration, PingGateway truncates the duration to 3650 days. Default: 30 minutes ### persistentCookie `"persistentCookie"`: *configuration expression<[boolean](preface.html#definition-boolean)>,optional* Whether the supporting cookie is persistent: * `true`: the supporting cookie is a persistent cookie. The user-agent returns persistent cookies until their expiration date or until they are deleted. * `false`: the supporting cookie is a session cookie. PingGateway doesn't specify an expiry date for session cookies. The user-agent deletes them when it considers the session terminated; for example, when the user closes the browser. Default: `false` ### secretsProvider `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](SecretsProvider.html) to query for the JWT session signing or encryption keys. ### skewAllowance `"skewAllowance"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The duration to add to the validity period of a JWT to allow for clock skew between different servers. 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 PingGateway clock. * A JWT with an `exp` 13:00 is expired after 13:02 on the PingGateway clock. Default: To support a zero-trust policy, the default skew allowance is `zero`. ### useCompression `"useCompression"`: *configuration expression [boolean](preface.html#definition-boolean), optional* When `true`, PingGateway compresses the session JWT before setting it in a cookie. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------ | | | Compression can undermine the security of encryption. Evaluate this threat according to your use case before you enable compression. | Default: `false` ## Example Learn more in [Encrypt JWT sessions](../installation-guide/jwtsession-using.html#jwtsession-encrypt). ## More information [org.forgerock.openig.session.jwt.JwtSessionManagerHeaplet](../_attachments/apidocs/org/forgerock/openig/session/jwt/JwtSessionManagerHeaplet.html)