Skip to content

Persistent Cookie module

vharseko edited this page Apr 27, 2018 · 9 revisions
Clone this wiki locally

Тhe Persistent Cookie module supports the configuration of cookie lifetimes based on requests and a maximum time. Note that by default, the persistent cookie is called session-jwt.

If Secure Cookie is enabled Configuration > Servers and Sites > Default Server Settings > Security > Cookie, the Persistent Cookie module only works over HTTPS.

Configuration > Servers and Sites > Default Server Settings > Security > Cookie

Before you begin, make sure a public key alias is defined in AM. The Persistent Cookie module encrypts a JSON Web Token (JWT) using a public key from the AM keystore. The keystore must be configured under Realms > Realm Name > Authentication > All Core Settings > Security > Persistent Cookie Encryption Certificate Alias. If the keystore changes and the default test key is no longer present, the public key alias must be updated to reflect the change, otherwise the module will fail. Similarly, in multi-instance deployments, the keypair must be available on all AM instances.

Realms > Realm Name > Authentication > All Core Settings > Security

To configure the Persistent Cookie module globally in the AM console, navigate to Configuration > Authentication, and then click Persistent Cookie. In the window that appears you should see the following attributes:

Module Instances > Persistent Cookie

For example, to generate an HMAC signing key, run the following:

openssl rand -base64 32


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

Default: a random 256-bit secret key.

When the Persistent Cookie module enforces the client IP address, and AM lies behind a load balancer or proxy layer, configure the load balancer or proxy to send the address by using the X-Forwarded-For header, and configure OpenAM to consume and forward the header as necessary. For details, see Handling HTTP Request Headers in the Installation Guide.

The Persistent Cookie module belongs with a second module in an Authentication Chaining. To see how this works, navigate to Realms > Realm Name > Authentication > Authentication Chaining. Create a new chain and add modules as shown in the figure. The following example shows how a Persistent Cookie module is sufficient. If the persistent cookie does not yet exist, authentication relies on LDAP:

Module Instances > Persistent Cookie > Chain

You should now be able to authenticate automatically, as long as the cookie exists for the associated domain.

ssoadm service name: iPlanetAMAuthPersistentCookieService

Idle Timeout

Specifies the maximum idle time between requests in hours. If that time is exceeded, the cookie is no longer valid.

ssoadm attribute: openam-auth-persistent-cookie-idle-time

Max Life

Specifies the maximum life of the cookie in hours.

ssoadm attribute: openam-auth-persistent-cookie-max-life

Enforce Client IP

When enabled, enforces that the persistent cookie can only be used from the same client IP to which the cookie was issued.

ssoadm attribute: openam-auth-persistent-cookie-enforce-ip

Use secure cookie

When enabled, adds the "Secure" attribute to the persistent cookie.

ssoadm attribute: openam-auth-persistent-cookie-secure-cookie

Use HTTP only cookie

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

ssoadm attribute: openam-auth-persistent-cookie-http-only-cookie

HMAC Signing Key

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.

ssoadm attribute: openam-auth-persistent-cookie-hmac-key

Check box name

The name of the check box, which means that the function is enabled by the user

ssoadm attribute: openam-auth-persistent-cookie-input

Repository field

The name of the field in the repository in which the issued tokens are stored

ssoadm attribute: openam-auth-persistent-cookie-field

Maximum devices

Maximum number of tokens (devices) per user

ssoadm attribute: openam-auth-persistent-cookie-field-max

Cookie name

default session-jwt

ssoadm attribute: openam-auth-persistent-cookie-name

other Authentication modules