PingGateway 2024.11

SetCookieUpdateFilter

Updates the attribute values of Set-Cookie headers in a cookie. This filter facilitates the transition to the SameSite and secure cookie settings required by newer browsers. Use SetCookieUpdateFilter at the beginning of a chain to guarantee security along the chain.

Set-Cookie headers must conform to grammar in RFC 6265: Set-Cookie.

Usage

{
  "name": string,
  "type": "SetCookieUpdateFilter",
  "config": {
   "cookies": {
     "cookie-name": {
       "attribute-name": "attribute-value",
       ...
     }
     ...
   }
 }
}

Properties

"cookies": map, required

Configuration that matches case-sensitive cookie names to response cookies, and specifies how matching cookies attribute values should be updated. Each cookie begins with a name-value pair, where the value is one or more attribute-value pairs.

cookie-name: pattern, required

The name of a cookie contained in the Set-Cookie header, as a pattern.

To change the attribute value on all existing cookies, specify .*.

If a cookie is named more than once, either explicitly or by the wildcard (*), the rules are applied to the cookie in the order they appear in the map.

In the following example, the SameSite attribute of the CSRF cookie first takes the value none, and then that value is overwritten by the value LAX.

"cookies": {
  "CSRF": {
    "value": "myValue",
    "secure": ${true},
    "SameSite": "none"
  }
  ".*": {
    "SameSite": "LAX"
  }
}
attribute-name: enumeration, required

A case-insensitive enumeration of a Set-Cookie attribute name.

Attribute names include SameSite, secure, http-only, value, expires, Max-Age, path, and domain. For more information, refer to RFC 6265: Set-Cookie.

Use the now dynamic binding to dynamically set the value of a cookie attribute that represents time. For example, set the value of the attribute expires to one day after the expression is evaluated, as follows:

{
  "type": "SetCookieUpdateFilter",
    "config": {
      "cookies": {
        ".*": {
          "expires": "${now.plusDays(1).rfc1123}",
...
attribute-value: runtime expression<string, boolean, or integer>, required

The replacement value for the named attribute. The value must conform to the expected type for the attribute name:

  • secure: runtime expression<boolean>. Required if SameSite is none

  • http-only: runtime expression<boolean>.

  • Max-Age: runtime expression<number>.

  • SameSite, and all other attribute names: runtime expression<string>.

For all values except expires, specify ${previous} to reuse the existing value for the attribute. The following example adds five seconds to the Max-Age attribute:

"Max-Age": "${integer(previous+5)}",

If the named the Set-Cookie header doesn’t contain the named attribute, ${previous} returns null.

Examples

The following example updates attributes of all existing Set-Cookie headers:

{
  "name": "SetCookieUpdateFilter",
  "condition": "${find(request.uri.path, '/home')}",
  "baseURI": "https://app.example.com:8444",
  "heap": [],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [{
        "type": "SetCookieUpdateFilter",
        "config": {
          "cookies": {
            ".*": {
              "SameSite": "LAX",
              "domain": "ig.example.com",
              "Max-Age": "${session.maxAge}",
              "Secure": "${true}",
              "expires": 155...833
            }
          }
        }
      }],
      "handler": "ReverseProxyHandler"
    }
  }
}

More information

org.forgerock.openig.filter.SetCookieUpdateFilter