PingAM 7.5.1

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 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?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping 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 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

A 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 this node generates, ensure the nodes use the same HMAC signing key.

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.

Outcomes

Single outcome path.

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.