PingFederate Server

Configuring the PingFederate cookie

PingFederate uses the PingFederate cookie to identify sessions. Some adapters, such as the HTML Form Adapter, also use this cookie to manage adapter sessions. Use this task to configure PingFederate cookie settings in session-cookie-config.xml, including the cookie name, length, security flags, domain, and lifetime.

Steps

  1. In a text editor, open the <pf_install>/pingfederate/server/default/data/config-store/session-cookie-config.xml file.

  2. Modify the appropriate parameter in session-cookie-config.xml. Refer to the PingFederate cookie parameters table for parameter information.

    (Optional) Alternatively, you can update a cookie parameter using a REST call to the PingFederate administrative API. For example:

    curl -u <username:password> -X 'PUT' \
  'https://<PF_host>/pf-admin-api/v1/configStore/session-cookie-config/cookie-domain' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-Header: PingFederate' \
  -d '{"id":"cookie-domain","type":"STRING","stringValue":".example.com"}'

    To update another parameter, use the same request pattern and replace the parameter name and value. Learn more in Accessing the API interactive documentation.

  3. If you updated the file directly, save and close the file.

  4. Restart PingFederate.

  5. For a clustered PingFederate environment, perform these steps on the console node. Then, click Replicate Configuration on System > Server > Cluster Management.

Result

After you restart PingFederate, the Set-Cookie HTTP header reflects your changes. For example, if you configure cookie-domain, cookie-secure-flag, and cookie-httponly-flag, the header can look like this:

Set-Cookie: PF=aDfPx6uwbbWGFhwE6zEhEG;Path=/;Domain=.example.com;Secure;HttpOnly

For browser restart support without a persistent PingFederate cookie, configure externally stored authentication sessions instead. Learn more in Sessions.

The session-cookie-config.xml file contains the following parameters to configure the PingFederate cookie:

Parameter Default value Description

cookie-name

PF

Sets the name of the PingFederate cookie. The configured name displays in the Set-Cookie header and in subsequent browser requests.

cookie-length

22

Sets the length of each generated PingFederate session ID value. PingFederate also uses this value when parsing the PF cookie into its internal session ID components.

cookie-secure-flag

true

Controls whether PingFederate marks the cookie as Secure. When enabled, browsers send the cookie only over encrypted HTTPS connections.

cookie-httponly-flag

true

Controls whether PingFederate marks the cookie as HttpOnly. When enabled, client-side scripts cannot access the cookie.

cookie-domain

None

Adds domain information to the Set-Cookie HTTP header. By default, PingFederate does not include domain information in the header. When set, PingFederate includes the Domain attribute in the Set-Cookie header.
Example configuration: <c:item name="cookie-domain">.example.com</c:item>.

cookie-max-age

-1

Defines the cookie lifetime in seconds. The default value of -1 makes the PingFederate cookie a transient session cookie. A positive integer makes the cookie persistent and saves it to disk, allowing the browser to reuse it after a restart.