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 Description

cookie-name

Sets the name of the PingFederate cookie. The default value is PF.

The configured name displays in the Set-Cookie header and in subsequent browser requests.

cookie-length

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

cookie-secure-flag

Controls whether PingFederate marks the cookie as Secure. The default value is true.

When enabled, browsers send the cookie only over HTTPS connections.

cookie-httponly-flag

Controls whether PingFederate marks the cookie as HttpOnly. The default value is true.

When enabled, client-side scripts can’t access the cookie.

cookie-domain

Adds domain information to the Set-Cookie HTTP header. By default, PingFederate doesn’t 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

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