Set Persistent Cookie node
Creates the specified persistent cookie, the default being session-jwt.
The cookie contains a JWT with a JSON payload including information such as the UID of the identity, and the client IP address.
The node encrypts the payload of the JWT using the key pair defined
in the active secret mapped to the am.authentication.nodes.persistentcookie.encryption secret label.
If there isn’t a valid secret label mapping in a secret store, AM uses the key pair specified in Native Consoles > Access Management > Realms > Realm Name > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias. uses the key pair specified in Realms > Realm Name > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias. The global setting is found under Configure > Authentication > Core Attributes > Security.
The node signs the cookie with the HMAC signing key defined in the node properties or the secret store with the mapped secret label. Configure nodes that read the persistent cookie, for example Persistent Cookie Decision node, with the same HMAC signing key.
Compatibility
| Product | Compatible? |
|---|---|
ForgeRock Identity Cloud |
Yes |
ForgeRock Access Management (self-managed) |
Yes |
ForgeRock Identity Platform (self-managed) |
Yes |
Inputs
When the authentication tree completes successfully, the CreatePersistentCookieTreeHook treehook
for this node uses session properties to create the persistent cookie.
Dependencies
A secret store configured for storing the dynamic secret label mapping to the cookie’s signing key.
Configuration
| Property | Usage | ||
|---|---|---|---|
Idle Timeout |
The maximum amount of idle time allowed before the persistent cookie is invalidated, in hours. If no requests are received before the timeout, the cookie is no longer valid. |
||
Max life |
The length of time the persistent cookie remains valid, in hours. After this time has passed, the cookie is no longer valid. |
||
Use Secure Cookie |
When enabled, adds the If the |
||
Use HTTP Only Cookie |
When enabled, adds the When the |
||
HMAC Signing Key |
A key to use for HMAC signing of the persistent cookie.
Values must be base64-encoded and at least 256 bits (32 bytes) long. To generate an HMAC signing key, run one of the following commands: or |
||
HMAC Signing Key Secret Label Identifier |
An identifier used to create a secret label for mapping to a secret in a secret store. AM uses this identifier to create a specific secret label for the signing key for this node.
The secret label takes the form
If you set an HMAC Signing Key Secret Label Identifier and AM finds a matching secret in a secret store, the HMAC Signing Key is ignored. If HMAC Signing Key is empty, AM uses the value configured for
For greater security, you should rotate signing keys periodically. When you rotate a key, update the corresponding mapping in the realm secret store configuration to reflect this identifier.
|
||
Persistent Cookie Name |
The name used for the persistent cookie. |
Outputs
The node stores the cookie name in the session properties.
The node adds the CreatePersistentCookieTreeHook treehook, which runs when the tree completes.
Errors
The node logs the following warning messages:
-
Unable to create signing key from provided configuration.
The node logs the following error messages:
-
Tree hook creation exception -
No signing keys available to sign JWT -
Error creating jwt string
Example
Refer to the Persistent Cookie Decision node example.