Skip to end of metadata
Go to start of metadata

This filter is deprecated, as functionality is reproduced in the Header Normalization filter and the URI Normalization filter. This filter will be removed as of 8.0.0.0.

 

The Content Normalization filter normalizes the headers and media type of the request by performing three separate functions. The filter uses blacklisting to prevent specific requests from passing to the origin service, it uses whitelisting to pass only approved headers to the origin service, or it uses media typing to normalize accept headers. The Content Normalization filter does not modify the response.

 

Prerequisites

Required headers: The Content Normalization filter has no required request headers.

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

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

Basic content normalization configuration

Configure the Content Normalization filter by editing the content-normalization.cfg.xml file.

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

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

3. Configure the Content Normalization Filter 

  • If you are using the Content Normalization filter to blacklist or whitelist configure <header-filters> with the appropriate sub-elements. 
  • If you are using the Content Normalization filter to normalize media, configure the <media-type> element. 

You may configure the Content Normalization filter to blacklist or whitelist headers and to normalize media using both the <header-filters> and the <media-type> elements in the configuration.

4. Test Content Normalization

Blacklist feature:

  1. Send a request to a reflection service, such as http://httpbin.org, with the 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 to a reflection service, such as http://httpbin.org, with the 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. If it is not there, the filter is configured properly.

Media type feature:

  1. Send a request to a reflection service, such as http://httpbin.org, that ends in the media-type that you want captured.
  2. Check the response for the appropriate Accept header. If it is there, the filter is configured properly.

XML schema definition

Example configuration

Optional configurations

The Content Normalization filter has three features that perform separate functions. The features are blacklist, whitelist, and media type. 

Media type

Use the media-type feature to normalize the accept header by mapping a media type to a URI extension.  The Content Normalization filter will strip the extension from the URI and set the configured media type name. The filter sets the accept header but does not change the content body of the request.

  • If an accept header matches a configured variant extension, the configured media type is used.
  • If no accept header is present or if no accept headers match any media type in the list, the preferred media type is used.

Content Normalization Configuration with Media Type
<media-types>
  <media-type name="application/xml" variant-extension="xml" preferred="true" />
  <media-type name="application/atom+xml" variant-extension="atom" />
  <media-type name="application/json" variant-extension="json" />
</media-types> 
Request
curl http://50.57.184.12:8887/v1/usertest1.xml
Headers Passed to Origin Service
accept: application/xml

 

Blacklist

Use the blacklist feature to extract 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. 

Content Normalization Configuration with Blacklist
<header-filters>
   <blacklist id="rate-limit-headers">
     <header id="X-Black-Listed1" />
     <header id="X-Black-Listed2" />
   </blacklist>
</header-filters>
Request
curl http://50.57.184.12:8887/v1/usertest1.xml -H "x-auth-token:358484212:99493" -H "black-listed1:should" -H "black-listed2:disappear" -H "nonblacklisted:should"
Headers Passed to Origin Service
X-Auth-Token
non-blacklisted

 

Whitelist

Use the whitelist feature to list 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. 

Content Normalization Configuration with Whitelist
<header-filters>
  <whitelist id="rate-limit-headers">
    <header id="X-Auth-Token" />
    <header id="X-Whitelisted-Header" />
  </whitelist>
</header-filters>
Request
curl http://50.57.184.12:8887/v1/usertest1.xml -H "x-auth-token:358484212:99493" -H "X-Auth-Group:should" -H "X-Auth-Header:disappear" -H "X-Whitelisted-Header:allowed"
Headers passed to origin service
X-Auth-Token
X-Whitelisted-Header

Configurable parameters

The content-normalization.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the System Model Configuration.

Element


Attribute

Required/

Optional

Description
<content-normalization>-RequiredUses the accompanying sub-elements and attributes to define your content normalization configuration.

<header-filters>

-OptionalUses the blacklist or whitelist sub element to define the headers that are extracted or passed to the origin service.

<blacklist>

-OptionalDefines the list of headers that are extracted from the request.

<whitelist>

-OptionalDefines the list of request headers that are allowed to pass to the origin service.

<header>

-Required only if using blacklist or whitelist.The header that will be blacklisted or whitelisted.

idRequired only if using header.Unique identifier of the given group.

<media-types>

-OptionalDefines a list of accept headers for the URIs that match a configured variant-extension.

<media-type>

-OptionalDefines the media type that will be normalized.

nameRequired only if using media-type.Names the media-type.

variant-extensionOptionalDefines the variant extension that the configured media type applies to.

preferredOptionalDefines the default media type to apply to the request if no media type variation or accept type is supplied. 

Return codes and conditions

  1. The Content Normalization filter never returns error codes. The request will simply pass through to the next filter or the origin service.
  2. The Content Normalization filter extracts content that is configured, ignores everything else, and lets the request pass to the origin service.

Content normalization use cases

  1. As an administrator, I want to prevent a malicious user from programmatically altering request parameters or headers that prevent caching of responses. My service caches responses based on request URIs, parameters, and headers so that it can respond quickly with little load on the service. 
  2. As an administrator, I want my service to support requests with multiple media types in the URL extensions.

Request headers created

You can configure the Content Normalization filter to create accept headers.

Content normalization process

    1. The client sends the request.
    2. Repose processes the request with the blacklist or whitelist feature, or with the media type feature. 

      The media-type feature may be used with the blacklist or the whitelist feature. However, the blacklist and whitelist features should not be used simultaneously.

    3. Repose sends the request to the origin service.
    4. The origin service processes the request.
    5. The origin service returns the response.
    6. Repose passes the response. (The Content Normalization filter does not modify the response.)
    7. Repose returns the response to the client 

 

  • No labels