Description

The XForwardedFilter is a Java Servlet API port of mod_remoteip, this filter replaces the apparent client remote IP address and hostname for the request with the IP address list presented by a proxy or a load balancer via a request headers (e.g. "X-Forwarded-For").

Another feature of this filter is to replace the apparent scheme (http/https) and server port with the scheme presented by a proxy or a load balancer via a request header (e.g. "X-Forwarded-Proto").

Filter Configuration

Note: In most cases, the XForwardedFilter should precede all the other filter and in particular precede logging, authentication, authorization or remote IP related filters.

Basic configuration to handle x-forwarded-for

The filter will process the x-forwarded-for http header.

<web-app ...>
   ...
   <filter>
      <filter-name>XForwardedFilter</filter-name>
      <filter-class>fr.xebia.servlet.filter.XForwardedFilter</filter-class>
   </filter>
   
   <filter-mapping>
      <filter-name>XForwardedFilter</filter-name>
      <url-pattern>/*</url-pattern>
      <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
   ...
</web-app>

Basic configuration to handle x-forwarded-for and x-forwarded-proto

The filter will process x-forwarded-for and x-forwarded-proto http headers. Expected value for x-forwarded-proto https connections is https (case insensitive).

<web-app ...>
   ...
   <filter>
      <filter-name>XForwardedFilter</filter-name>
      <filter-class>fr.xebia.servlet.filter.XForwardedFilter</filter-class>
      <init-param>
         <param-name>protocolHeader</param-name>
         <param-value>x-forwarded-proto</param-value>
      </init-param>
   </filter>
   
   <filter-mapping>
      <filter-name>XForwardedFilter</filter-name>
      <url-pattern>/*</url-pattern>
      <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
   ...
</web-app>

Advanced samples

Sample with internal proxies

XForwardedFilter configuration:

 <filter>
    <filter-name>XForwardedFilter</filter-name>
    <filter-class>fr.xebia.servlet.filter.XForwardedFilter</filter-class>
    <init-param>
       <param-name>allowedInternalProxies</param-name><param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPHeader</param-name><param-value>x-forwarded-for</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPProxiesHeader</param-name><param-value>x-forwarded-by</param-value>
    </init-param>
    <init-param>
       <param-name>protocolHeader</param-name><param-value>x-forwarded-proto</param-value>
    </init-param>
 </filter>
 
 <filter-mapping>
    <filter-name>XForwardedFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

Request values:

Note : x-forwarded-by header is null because only internal proxies as been traversed by the request. x-forwarded-by is null because all the proxies are trusted or internal.

Sample with trusted proxies

XForwardedFilter configuration:

 <filter>
    <filter-name>XForwardedFilter</filter-name>
    <filter-class>fr.xebia.servlet.filter.XForwardedFilter</filter-class>
    <init-param>
       <param-name>allowedInternalProxies</param-name><param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPHeader</param-name><param-value>x-forwarded-for</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPProxiesHeader</param-name><param-value>x-forwarded-by</param-value>
    </init-param>
    <init-param>
       <param-name>trustedProxies</param-name><param-value>proxy1, proxy2</param-value>
    </init-param>
 </filter>
 
 <filter-mapping>
    <filter-name>XForwardedFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

Request values:

Note : proxy1 and proxy2 are both trusted proxies that come in x-forwarded-for header, they both are migrated in x-forwarded-by header. x-forwarded-by is null because all the proxies are trusted or internal.

Sample with internal and trusted proxies

XForwardedFilter configuration:

 <filter>
    <filter-name>XForwardedFilter</filter-name>
    <filter-class>fr.xebia.servlet.filter.XForwardedFilter</filter-class>
    <init-param>
       <param-name>allowedInternalProxies</param-name><param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPHeader</param-name><param-value>x-forwarded-for</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPProxiesHeader</param-name><param-value>x-forwarded-by</param-value>
    </init-param>
    <init-param>
       <param-name>trustedProxies</param-name><param-value>proxy1, proxy2</param-value>
    </init-param>
 </filter>
 
 <filter-mapping>
    <filter-name>XForwardedFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

Request values:

Note : proxy1 and proxy2 are both trusted proxies that come in x-forwarded-for header, they both are migrated in x-forwarded-by header. As 192.168.0.10 is an internal proxy, it does not appear in x-forwarded-by. x-forwarded-by is null because all the proxies are trusted or internal.

Sample with an untrusted proxy

XForwardedFilter configuration:

 <filter>
    <filter-name>XForwardedFilter</filter-name>
    <filter-class>fr.xebia.servlet.filter.XForwardedFilter</filter-class>
    <init-param>
       <param-name>allowedInternalProxies</param-name><param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPHeader</param-name><param-value>x-forwarded-for</param-value>
    </init-param>
    <init-param>
       <param-name>remoteIPProxiesHeader</param-name><param-value>x-forwarded-by</param-value>
    </init-param>
    <init-param>
       <param-name>trustedProxies</param-name><param-value>proxy1, proxy2</param-value>
    </init-param>
 </filter>
 
 <filter-mapping>
    <filter-name>XForwardedFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

Request values:

Note : x-forwarded-by holds the trusted proxy proxy1. x-forwarded-by holds 140.211.11.130 because untrusted-proxy is not trusted and thus, we can not trust that untrusted-proxy is the actual remote ip. request.remoteAddr is untrusted-proxy that is an IP verified by proxy1.

Install / Download

• Maven Project, add the following to pom.xml

<project ...>
   ...
   <dependencies>
      ...
      <dependency>
         <groupId>fr.xebia.web</groupId>
         <artifactId>xebia-servlet-extras</artifactId>
         <version>1.0.6</version>
      </dependency>
      ...
   </dependencies>
   ...
</project>

• Jar : Drop the jar xebia-servlet-extras-1.0.6.jar (sources) in your web application classpath.
• Java class : XForwardedFilter.java
• Java project : svn checkout http://xebia-france.googlecode.com/svn/web/xebia-servlet-extras/tags/xebia-servlet-extras-1.0.6/

Implementation Details

This filter proceeds as follows:

If the incoming request.getRemoteAddr() matches the filter's list of internal proxies :

• Loop on the comma delimited list of IPs and hostnames passed by the preceding load balancer or proxy in the given request's Http header named $remoteIPHeader (default value x-forwarded-for). Values are processed in right-to-left order.
• For each ip/host of the list:
• if it matches the internal proxies list, the ip/host is swallowed
• if it matches the trusted proxies list, the ip/host is added to the created proxies header
• otherwise, the ip/host is declared to be the remote ip and looping is stopped.
• If the request http header named $protocolHeader (e.g. x-forwarded-for) equals to the value of protocolHeaderHttpsValue configuration parameter (default https) then request.isSecure = true, request.scheme = https and request.serverPort = 443. Note that 443 can be overwritten with the $httpsServerPort configuration parameter.

Regular expression vs. IP address blocks: mod_remoteip allows to use address blocks (e.g. 192.168/16) to configure RemoteIPInternalProxy and RemoteIPTrustedProxy ; as Tomcat doesn't have a library similar to apr_ipsubnet_test, XForwardedFilter uses regular expression to configure allowedInternalProxies and trustedProxies in the same fashion as RequestFilterFilter does.

Change Log

1.0.6 - 2012/03/30 : response.sendRedirect(location) ignores the overwritten scheme. Fix provided by Marc van Andel.

Resources

• RemoteIpValve : the equivalent of XForwardedFilterintegrated in Tomcat. It has been proposed to the Tomcat project as Bug 47330 - proposal : port of mod_remoteip in Tomcat as RemoteIpValve.
• Wikipedia X-Forwarded-For page.
• How to enable the X-Forwarded-For http header on F5 BIGIP/Viprion : Dev Central - Using "X-Forwarded-For" in Apache or PHP].
• Apache mod_proxy X-Forwarded http headers (X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server) : Reverse Proxy Request Headers.
• Apache mod_remoteip module to handle X-Forwarded-For header in Apache.
• Squid Proxy X-Forwarded-For configuration.
• Firefox Modify Headers X-Forwarded-For Spoofer add-ons. Modify Headers allows you to test both X-Forwarded-For and X-Forwarded-Proto.
• Jetty connector configuration to handle X-Forwarded-For.
• Tomcat : Adresse IP de l’internaute, load balancer, reverse proxy et header Http X-Forwarded-For : a french tutorial on X-Forwarded-For handling in Java.
• Tomcat, SSL, communications sécurisées et X-Forwarded-Proto : a french tutorial on Tomcat, SSL, X-Forwarded-Proto and secured communications.