Persistent Cookie Decision node
The Persistent Cookie Decision node checks for the existence of a specified persistent cookie (default: session-jwt).
If the cookie is present, the node verifies the signature of the JWT stored in the cookie with the configured signing key.
If the configured signing key isn’t valid, AM checks the signature against all valid signing keys mapped to the configured secret label.
If the signature is valid, the node decrypts 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 decrypted JSON payload includes information, such as the UID of the identity and the client IP address. Enable Enforce Client IP to verify that the current IP address and the client IP address in the cookie are the same.
|
This node recreates the specified persistent cookie,
updating the value for the idle time property and the JWT Therefore, the node has cookie creation properties similar to the Set Persistent Cookie node. |
Compatibility
| Product | Compatible? |
|---|---|
ForgeRock Identity Cloud |
Yes |
ForgeRock Access Management (self-managed) |
Yes |
ForgeRock Identity Platform (self-managed) |
Yes |
Dependencies
To authenticate successfully, the tree must have set a persistent cookie using a node such as the Set Persistent Cookie node.
Configuration
| Property | Usage | ||
|---|---|---|---|
Idle Timeout |
The maximum idle time allowed before the persistent cookie is invalidated, in hours. If no requests are received and the time is exceeded, the cookie is no longer valid. |
||
Enforce Client IP |
When enabled, ensures that the persistent cookie is only used from the same client IP to which the cookie was issued. |
||
Use Secure Cookie |
When enabled, adds the If the |
||
Use HTTP Only Cookie |
When enabled, adds the When the |
||
HMAC Signing Key |
The 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 of the persistent cookie to check. |
Outputs
The node copies shared state into the outgoing node state. It records the user identity and stores the cookie name as a session property.
The node adds the UpdatePersistentCookieTreeHook, which runs when the tree completes.
Outcomes
-
True -
False
Evaluation continues along the True outcome path
if the persistent cookie is present and all the verification checks are satisfied;
otherwise, evaluation continues along the False outcome path.
Errors
The node logs the following warning messages:
-
Attempt to verify JWT failed, attempting other valid keys -
Failed to parse universal id username from claim openam.usr
The node logs the following error messages:
-
Claims context not found -
Failed to find signing key with associated keyID -
jwt reconstruction error -
Authentication failed. Jwt claim Realm does not match -
Authentication failed. Cannot read the user from null claims -
Authentication failed. Cannot read the user from empty claims -
Failed to parse universal Id from claim: openam.usr -
Authentication failed. Client IP is different
