HeaderFilter

Removes, adds, or replaces headers in request or response messages.

Usage

{
  "name": string,
  "type": "HeaderFilter",
  "config": {
    "messageType": configuration expression<enumeration>,
    "remove": [ configuration expression<string>, ... ],
    "add": {
      string: [ runtime expression<string>, ... ], ...
    }
    "replace": {
      string: [ runtime expression<string>, ... ], ...
    }
  }
}

Properties

`"messageType": configuration expression<enumeration>, required

The type of message for which to filter headers. Must be either "REQUEST" or "RESPONSE".

"remove": array of configuration expression<strings>, optional

The names of header fields to remove.

"add": object, optional

One or more headers to add with the format name: [ value, … ]:

name is a string for a header name.
value is a runtime expression that resolves to one or more header values.

"replace": object, optional

One or more headers to replace with the format name: [ value, … ]

name is a string for a header name.
value is a runtime expression that resolves to one or more header values.

PingGateway removes current values for the name headers and adds the specified values.

Examples

Replace host header on an incoming request

The following example replaces the host header on the incoming request with the value myhost.com:

{
  "name": "ReplaceHostFilter",
  "type": "HeaderFilter",
  "config": {
    "messageType": "REQUEST",
    "replace": {
      "host": [ "myhost.com" ]
    }
  }
}

The following example adds a Set-Cookie header to the response:

{
  "name": "SetCookieFilter",
  "type": "HeaderFilter",
  "config": {
    "messageType": "RESPONSE",
    "add": {
      "Set-Cookie": [ "mysession=12345" ]
    }
  }
}

Add headers to a request

The following example adds the headers custom1 and custom2 to the request:

{
  "name": "SetCustomHeaders",
  "type": "HeaderFilter",
  "config": {
    "messageType": "REQUEST",
    "add": {
      "custom1": [ "12345", "6789" ],
      "custom2": [ "abcd" ]
    }
  }
}

Add a token value to a response

The following example adds the value of session’s policy enforcement token to the pef_sso_token header in the response:

{
  "type": "HeaderFilter",
  "config": {
    "messageType": "RESPONSE",
    "add": {
      "pef_sso_token": ["${session.pef_token}"]
    }
  }
}

Add headers and logging results

The following example adds a message to the request and response as it passes through the Chain, and the capture on the ReverseProxyHandler logs the result. With PingGateway and the sample application set up as described in the Quick install, access this route on http://ig.example.com:8080/home/chain.

{
  "condition": "${find(request.uri.path, '^/home/chain')}",
  "handler": {
    "type": "Chain",
    "comment": "Base configuration defines the capture decorator",
    "config": {
      "filters": [
        {
          "type": "HeaderFilter",
          "comment": "Add a header to all requests",
          "config": {
            "messageType": "REQUEST",
            "add": {
              "MyHeaderFilter_request": [
                "Added by HeaderFilter to request"
              ]
            }
          }
        },
        {
          "type": "HeaderFilter",
          "comment": "Add a header to all responses",
          "config": {
            "messageType": "RESPONSE",
            "add": {
              "MyHeaderFilter_response": [
                "Added by HeaderFilter to response"
              ]
            }
          }
        }
      ],
      "handler": {
        "type": "ReverseProxyHandler",
        "comment": "Log request, pass it to the sample app, log response",
        "capture": "all",
        "baseURI": "http://app.example.com:8081"
      }
    }
  }
}

The chain receives the request and context and processes it as follows:

The first HeaderFilter adds a header to the incoming request.
The second HeaderFilter manages responses not requests, so it simply passes the request and context to the handler.
The ReverseProxyHandler captures (logs) the request.
The ReverseProxyHandler forwards the transformed request to the protected application.
The protected application passes a response to the ReverseProxyHandler.
The ReverseProxyHandler captures (logs) the response.
The second HeaderFilter adds a header added to the response.
The first HeaderFilter is configured to manage requests, not responses, so it simply passes the response back to PingGateway.

The following example lists some of the HTTP requests and responses captured as they flow through the chain. You can search the log files for MyHeaderFilter_request and MyHeaderFilter_response.

# Original request from user-agent
GET http://ig.example.com:8080/home/chain HTTP/1.1
Accept: /
Host: ig.example.com:8080

# Add a header to the request (inside PingGateway) and direct it to the protected application
GET http://app.example.com:8081/home/chain HTTP/1.1
Accept: /
Host: ig.example.com:8080
MyHeaderFilter_request: Added by HeaderFilter to request

# Return the response to the user-agent
HTTP/1.1 200 OK
Content-Length: 1809
Content-Type: text/html; charset=ISO-8859-1

# Add a header to the response (inside PingGateway)
HTTP/1.1 200 OK
Content-Length: 1809
MyHeaderFilter_response: Added by HeaderFilter to response

More information

org.forgerock.openig.filter.HeaderFilter

PingGateway 2024.9