--- title: HeaderFilter description: Removes headers from and adds headers to request and response messages. Headers are added to any existing headers in the message. To replace a header, remove the header and then add it again. component: pinggateway version: 2023.11 page_id: pinggateway:reference:HeaderFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/HeaderFilter.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-03T11:21:31Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/HeaderFilter.html section_ids: HeaderFilter-usage: Usage HeaderFilter-properties: Properties HeaderFilter-example: Examples HeaderFilter-example-replacing: Replace host header on an incoming request HeaderFilter-example-cookie: Add a header to a response HeaderFilter-example-adding: Add headers to a request HeaderFilter-example-token: Add a token value to a response HeaderFilter-example-logging: Add headers and logging results HeaderFilter-moreinfo: More information --- # HeaderFilter Removes headers from and adds headers to request and response messages. Headers are added to any existing headers in the message. To replace a header, remove the header and then add it again. ## Usage ```json { "name": string, "type": "HeaderFilter", "config": { "messageType": configuration expression, "remove": [ configuration expression, ... ], "add": { string: [ runtime expression, ... ], ... } } } ``` ## Properties * \`"messageType": *configuration expression<[enumeration](preface.html#definition-enumeration)>, required* The type of message for which to filter headers. Must be either `"REQUEST"` or `"RESPONSE"`. * `"remove"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* The names of header fields to remove from the message. * `"add"`: *[object](preface.html#definition-object), optional* One or more headers to add to a request, with the format `name: [ value, …​ ]`, where: * *name* is a string for a header name. * *value* is a runtime expression that resolves to one or more header 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`: ```json { "name": "ReplaceHostFilter", "type": "HeaderFilter", "config": { "messageType": "REQUEST", "remove": [ "host" ], "add": { "host": [ "myhost.com" ] } } } ``` ### Add a header to a response The following example adds a `Set-Cookie` header to the response: ```json { "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: ```json { "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: ```json { "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 IG and the sample application set up as described in the [Quick install](../getting-started/preface.html), access this route on . ```json { "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 IG. 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`. ```http # 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 IG) 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 IG) HTTP/1.1 200 OK Content-Length: 1809 MyHeaderFilter_response: Added by HeaderFilter to response ``` ## More information [org.forgerock.openig.filter.HeaderFilter](../_attachments/apidocs/org/forgerock/openig/filter/HeaderFilter.html)