--- title: Client-side session security description: Configure PingAM to sign and encrypt client-side session JWTs to prevent tampering and protect sensitive session information from man-in-the-middle attacks component: pingam version: 7.5 page_id: pingam:security:session-state-configure-cookie-security canonical_url: https://docs.pingidentity.com/pingam/8.1/security/session-state-configure-cookie-security.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Security", "Setup & Configuration", "Sessions"] page_aliases: ["security-guide:session-state-configure-cookie-security.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/security/session-state-configure-cookie-security.html section_ids: session-state-configure-jwt-signature: Configure the JWT signature session-state-configure-jwt-encryption: Configure JWT encryption policy_agent5_client-based: Client-side session security and agents --- # Client-side session security AM can issue *server-side* sessions, which contain a reference to the real session stored in the CTS store, or *client-side* sessions, which contain all the information that would be held in the CTS store. While both types are susceptible to cookie hijacking, client-side sessions are even more vulnerable, since they contain all the information for the session. Therefore, the malicious user could tamper with the session data to their benefit. When using client-side sessions and client-side authentication sessions, you should configure AM to sign and/or encrypt the JWT containing session information: * JWT signing AM verifies that the JWT is authentic by validating a signature configured in the Session Service. AM thwarts attackers who might attempt to tamper with the contents of the JWT or its signature, or who might attempt to sign the JWT with an incorrect signature. - JWT encryption Knowledgeable users can easily decode JWTs. Because an AM session or authentication session contains information that might be considered sensitive, encrypting the JWT that contains it protects its contents, ensuring opaqueness. Encrypting the JWT prevents man-in-the-middle attacks that could log the state of every AM session. Encryption also ensures that end users are unable to access the information in their AM session. **Client-side sessions and client-side authentication sessions share the same encryption and signing configuration.** | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Web agents and Java agents don't support both signing *and* encrypting the session cookie. This ensures that the client-side session cookie size isn't greater than the browser supported size.Learn more in [Client-side session security and agents](#policy_agent5_client-based). | ## Configure the JWT signature Configure a JWT signature to prevent malicious tampering of client-side session JWTs. Follow these steps to configure the JWT signature: 1. Go to Configure > Global Services > Session > Client-Side Sessions. 2. From the Signing Algorithm Type drop-down menu, choose a suitable algorithm for your environment. The default value is `HS256`. 3. Map a suitable secret that corresponds to the algorithm you selected: * For an HMAC signing algorithm, map a suitable secret to the `am.global.services.session.clientbased.signing.HMAC` secret label. * For the RS256 signing algorithm, map a suitable secret to the `am.global.services.session.clientbased.signing.RSA` secret label. * For the elliptic curve algorithms, map a suitable secret to one of the corresponding secret labels: * `am.global.services.session.clientbased.signing.ES256` * `am.global.services.session.clientbased.signing.ES384` * `am.global.services.session.clientbased.signing.ES512` You can only configure these secrets at a global level. Learn more about mapping secrets to secret labels in [Secret stores](secret-stores.html). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Don't sign the JWT if you plan to encrypt it with the Direct AES Encryption algorithm, because the signature will be redundant.To disable JWT signing:1. Go to Configure > Global Services > Session > Client-Side Sessions. 2. From the Signing Algorithm Type drop-down list, choose `NONE`. 3. Go to Configure > Server Defaults > Advanced. 4. Set `org.forgerock.openam.session.stateless.signing.allownone` to `true`. > **Collapse: How do I configure advanced server properties?** > > * To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI. > > * To configure advanced server properties for a particular instance, go to Deployment > Servers > *server name* > Advanced. > > If the property you want to add or edit is already configured, click on the pencil ([icon: pencil-alt, set=fas]) button to edit it. When you are finished, click on the tick ([icon: check, set=fas]) button. > > Click Save Changes. 5. Save your work. | Learn more about Session Service configuration attributes in [Session](../reference/global-services-configuration.html#global-session). ## Configure JWT encryption Configure JWT encryption to prevent man-in-the-middle attackers from accessing users' session details, and to prevent end users from examining the content in the JWT. Follow these steps to encrypt the JWT: 1. Go to Global Services > Session > Client-Side Sessions. 2. From the Encryption Algorithm drop-down list, choose a suitable algorithm: 1. If you select the `RSA` algorithm, also follow these steps: * [Configure JWT encryption](#session-state-configure-jwt-encryption). * Map a suitable secret to the `am.global.services.session.clientbased.encryption.RSA` secret label. You can only configure this secret at a global level. Learn more about configuring secrets in [Secret stores](secret-stores.html). * Configure one of the following paddings in the `org.forgerock.openam.session.stateless.rsa.padding` advanced server property: **RSA1_5**. RSA with PKCS#1 v1.5 padding.\ **RSA-OAEP**. RSA with OAEP and SHA-1.\ **RSA-OAEP-256**. RSA with OAEP padding and SHA-256. The default is `RSA-OAEP-256`. > **Collapse: How do I configure advanced server properties?** > > * To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI. > > * To configure advanced server properties for a particular instance, go to Deployment > Servers > *server name* > Advanced. > > If the property you want to add or edit is already configured, click on the pencil ([icon: pencil-alt, set=fas]) button to edit it. When you are finished, click on the tick ([icon: check, set=fas]) button. > > Click Save Changes. 2. If you select the AES KeyWrapping or Direct AES Encryption algorithms, also map a suitable secret to the `am.global.services.session.clientbased.encryption.AES` secret label. You can only configure this secret at a global level. Learn more about configuring secrets in [Secret stores](secret-stores.html). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | AES key wrap is a symmetric encryption method, which means the same key is used for encrypting and decrypting. Make sure you use the same secret on all AM instances to allow any AM instance to decrypt the encrypted JWT. | * For direct encryption with AES-GCM, or for AES-KeyWrap with any content encryption method, the secret must be 128, 192, or 256 bits long. * For direct encryption with AES-CBC-HMAC, the secret must be 256, 384, or 512 bits long. * For the underlying content encryption method, configure one of the following encryption methods in the `org.forgerock.openam.session.stateless.encryption.method` advanced server property: **A128CBC-HS256**. AES 128-bit in CBC mode with HMAC-SHA-256-128 hash (HS256 truncated to 128 bits)\ **A192CBC-HS384**. AES 192-bit in CBC mode with HMAC-SHA-384-192 hash (HS384 truncated to 192 bits)\ **A256CBC-HS512**. AES 256-bit in CBC mode with HMAC-SHA-512-256 hash (HS512 truncated to 256 bits)\ **A128GCM**. AES 128-bit in GCM mode\ **A192GCM**. AES 192-bit in GCM mode\ **A256GCM**. AES 256-bit in GCM mode The default is `A128CBC-HS256`. > **Collapse: How do I configure advanced server properties?** > > * To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI. > > * To configure advanced server properties for a particular instance, go to Deployment > Servers > *server name* > Advanced. > > If the property you want to add or edit is already configured, click on the pencil ([icon: pencil-alt, set=fas]) button to edit it. When you are finished, click on the tick ([icon: check, set=fas]) button. > > Click Save Changes. 3. To compress the session state, choose Deflate Compression from the Compression Algorithm drop-down list. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When set to Deflate compression, this option may lead to a possible vulnerability with session state information leakage. Because the session token compression depends on the data in the session, an attacker can vary one part of the session (for example, the username or some other property) and then deduce some secret parts of the session state by examining how the session compresses. You should evaluate this threat depending on your use cases before enabling compression and encryption together. | By default, AM rejects compressed session JWTs that expand to a size larger than 32 KiB (32768 bytes). For more information, see [Control the size of compressed JWTs](control-maximum-size-decompressed-JWT.html). 4. Save your work. For detailed information about Session Service configuration attributes, see the entries for [Session](../reference/global-services-configuration.html#global-session). ## Client-side session security and agents To ensure that the client-side session cookie size does not surpass the browser supported size, web agents and Java agents do not support both signing and encrypting the session cookie. To configure agents with client-side sessions, implement one of the following configurations: * Configure signing and compression: 1. Enable HS256 signing for the client-side session cookie. For more information, see [Configure the JWT signature](#session-state-configure-jwt-signature). 2. Enable compression. Go to Configure > Global Services > Session > Client-Side Sessions and choose Deflate Compression from the Compression Algorithm drop-down list. * Configure encryption and compression: 1. Set the `org.forgerock.openam.session.stateless.signing.allownone` advanced server property to `true` for all the instances in the environment. > **Collapse: How do I configure advanced server properties?** > > * To configure advanced server properties for all instances of the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI. > > * To configure advanced server properties for a particular instance, go to Deployment > Servers > *server name* > Advanced. > > If the property you want to add or edit is already configured, click on the pencil ([icon: pencil-alt, set=fas]) button to edit it. When you are finished, click on the tick ([icon: check, set=fas]) button. > > Click Save Changes. 1. Disable signing for the client-side session cookie. Go to Configure > Global Services > Session > Client-Side Sessions and choose NONE from the Signing Algorithm Type drop-down list. 2. Enable Direct AES Encryption. For more information, see [Configure JWT encryption](#session-state-configure-jwt-encryption). 3. Enable compression. Go to Configure > Global Services > Session > Client-Side Sessions and choose Deflate Compression from the Compression Algorithm drop-down list. Failure to set up client-side sessions correctly may cause unexpected errors when accessing a protected resource, such as blank pages and redirection loops. Client-side sessions do not support restricted tokens. Therefore, web agents and Java agents configured in a realm configured for client-side sessions are not protected against cookie hijacking. Use web or Java agents with server-side sessions where possible.