Header Normalization filter

Versioned Documentation Transition

Repose is currently transitioning to a new versioned documentation system accessible from the Repose home page. This transition is planned for completion in Repose 9.

This page is valid for versions: 2.0.0 – 8.4.1.0

The first versioned documentation for this filter is: 8.5.0.1

For future versions, refer to the Repose home page and select the desired version of Repose in the drop down menu in the top right corner.  You can also look at the latest version of this filter's documentation.

Purpose

Normalization is the process of modifying or standardizing content to optimize the flow of information. The Header Normalization filter normalizes the headers of the request by performing two separate functions. The filter uses blacklisting to prevent specific request headers from passing to the origin service, and it uses whitelisting to pass only approved headers to the origin service. The headers can be matched by URI regular expression (uri-regex) or HTTP method type (http-methods).

General filter information

Filter name: header-normalization

Filter configuration: header-normalization.cfg.xml

Released: version 2.0.0

Request prerequisites

Headers: The Header Normalization filter has no required request headers.

Required preceding filters: The Header Normalization filter has no required preceding filters.

Standard filter order: When you set the order of Repose filters, place the Header Normalization filter near the top of the sequence to clean the request. This sequence prevents unexpected request headers from passing to the origin service.

Basic header normalization configuration

Configure the Header Normalization filter by editing the header-normalization.cfg.xml file.

1. Set Up Repose 
Configure Repose using either a cluster or a single instance configuration.

2. Add the Header Normalization Filter 
Add the Header Normalization filter to your system model configuration. Place this filter near the top of the filter sequence below the Logging filter.

3. Configure the Header Normalization Filter 

  • Specify uri-regex to match against incoming requests. The default is .*, which matches against any URI.
  • Specify http-methods to match against request methods. The default is ALL.

  • To whitelist or blacklist headers, specify the HTTP headers with the corresponding element.

4.  Test Header Normalization 

Blacklist Feature:

  1. Send a request with a blacklisted header included.
  2. Check the response body for that header. If it is not there, the filter is configured properly

Whitelist Feature:

  1. Send a request with a whitelisted header included.
  2. Check the response body for that header. If it is there, the filter is configured properly.

  3. Send a request without a whitelisted header. 
  4. Check the response body for that header. If it is not there, the filter is configured properly.

Configurable parameters

XML schema definition

Example configuration

The header-normalization.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the system model configuration.

Elements

Attributes

Required/

Optional

DescriptionVersion Available
<header-normalization>-RequiredSpecifies the sub-elements and attributes to define your header normalization configuration.
<header-filters>-Optional - Deprecated

Lists the target objects that are used to normalize requests.

This element is now deprecated and will be removed in v10.0.0.0


<target>

-Required

Specifies a normalizer for a given uri-regex http-methods to act against.

It is deprecated for a <target> to directly contain either a <blacklist> or <whitelist>.

In v10.0.0.0 a target will be required to contain either a <request> or <response> which will be required to contain one and only one subordinate <blacklist> or <whitelist>.

v8.4.2.0

uri-regex

OptionalThe regular expression that is matched against incoming requests. If no uri-regex is configured, the Header Normalization component defaults to .*, meaning that the current target can match against any URI.


http-methodsOptional

The method or methods that this target matches against. Valid methods are GET, DELETE, POST, PUT, HEAD, OPTIONS, CONNECT, TRACE, and ALL. If  http-methods is blank, the Header Normalization component defaults to ALL.


<blacklist>

-OptionalLists HTTP headers that are extracted from the request.

id

Optional - Deprecated

Unique identifier for a blacklist.

This attribute is now deprecated and will be removed in v10.0.0.0


<whitelist>

-OptionalLists approved HTTP headers that the request can contain.

idOptional - Deprecated

Unique identifier for a whitelist.

This attribute is now deprecated and will be removed in v10.0.0.0


<header>

-

Required

Specifies the headers to be blacklisted or whitelisted.

id

Required

Uniquely identifies the header to be blacklisted or whitelisted.
<request>-OptionalA <request> is required to contain one and only one subordinate <blacklist> or <whitelist>.v8.4.2.0
<response>-OptionalA <response> is required to contain one and only one subordinate <blacklist> or <whitelist>.v8.4.2.0

Header normalization features

The Header Normalization filter has two features that perform separate functions. The features are blacklist and whitelist. 

Blacklist 

The blacklist feature extracts the headers that you do not want to pass to the origin service. The following example uses the <blacklist> element and the id attribute to name the HTTP headers that will be extracted from the request. 

Whitelist

The whitelist feature enables you to specify only the HTTP headers that you want to pass to the origin service. All other requests are extracted and are not passed on. The following example uses the <whitelist> element and the id attribute to name the only HTTP headers that will be passed to the origin service. 

Return codes and conditions

  • The Header Normalization filter will never return error codes. The request will simply pass through to the next filter or the origin service.
  • The Header Normalization filter extracts headers that are configured, ignores everything else, and lets the request pass to the origin service.

Request headers created

The Header Normalization filter does not create any request headers; however, it does block and allow specified headers.

Header normalization process

When a request gets to the Header Normalization filter, the filter matches the request’s URI and method against the list of configured <target> elements. The first <target> element that matches applies its normalizer to the processed request.

Header normalization lifecycle