AM 7.3.1

Persistent Cookie Decision node

Checks for the existence of a specified persistent cookie, the default being session-jwt.

If the cookie is present, the node verifies the signature of the JWT stored in the cookie with the signing key specified in the HMAC signing key property.

If the signature is valid, the node decrypts the payload of the JWT. It uses the key pair specified in the Persistent Cookie Encryption Certificate Alias property, found in the AM admin UI under Realms > Realm Name > Authentication > Settings > Security. The global level 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 identical.

This node recreates the received persistent cookie, updating the value for the idle time property.

Cookie creation properties for the Set Persistent Cookie node are therefore available in this node as well.

Outcomes

  • True

  • False

Evaluation continues along the True outcome path if the persistent cookie is present and all the verification checks above are satisfied; otherwise, evaluation continues along the False outcome path.

Properties

Property Usage

Idle Timeout

Specifies the maximum amount of 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 (required)

Specifies 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 consume the persistent cookies generated by the Set Persistent Cookie node, ensure they are using the same HMAC signing key.

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

Persistent cookie name

Specifies the name of the persistent cookie to check.

Example

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

The persistent cookie decision in context