PingAM 7.5.1

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 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 kid header with the stable ID used to sign the JWT.

Therefore, the node has cookie creation properties similar to the Set Persistent Cookie node.

Compatibility

Product Compatible?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node requires the realm property, which AM sets by default.

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 Secure flag to the persistent cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP Only Cookie

When enabled, adds the HttpOnly flag to the persistent cookie.

When the HttpOnly flag is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the HttpOnly flag, "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (for example, a web browser API that exposes cookies to scripts)."

HMAC Signing Key

The key to use for HMAC signing of the persistent cookie.

This property is deprecated. Use the HMAC Signing Key Secret Label Identifier instead.

If you set an HMAC Signing Key Secret Label Identifier, this signing key is ignored.

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:

$ openssl rand -base64 32

or

$ cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1|base64

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 am.authentication.nodes.persistentcookie.identifier.signing where identifier is the value of HMAC Signing Key Secret Label Identifier. The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

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 am.default.authentication.nodes.persistentcookie.signing for the realm, or at the global level if undefined.

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.

To read the persistent cookies generated by the Set Persistent Cookie node, ensure the nodes use the same HMAC signing key.

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

The following example authenticates the user based on a persistent cookie, if possible:

The persistent cookie decision in context