2. Configuring Protection Filter Against Cross Site Request Forgery Attacks

A Cross Site Request Forgery (CSRF) attack attempts to force a user to execute functionality without their knowledge. Typically the attack is initiated by presenting the user with a link or image that when clicked invokes a request to another site with which the user already has an established an active session. CSRF is typically a browser based attack.

The only way to create a HTTP request from a browser is with a custom HTTP header is to use Javascript XMLHttpRequest or Flash, etc. Browsers have built-in security that prevent web sites from sending requests to each other unless specifically allowed by policy. This means that a website www.bad.com cannot send a request to http://bank.example.com with the custom header X-XSRF-Header unless they use a technology such as a XMLHttpRequest. That technology would prevent such a request from being made unless the bank.example.com domain specifically allowed it. This then results in a REST endpoint that can only be called via XMLHttpRequest (or similar technology).


After enabling CSRF protection within the gateway, a custom header is required for all clients that interact with it, not just browsers.

To add a CSRF protection filter:

  1. Open the cluster topology descriptor file, $cluster-name .xml, in a text editor.

  2. Add a WebAppSec webappsec provider to topology/gateway with a parameter for each service as follows:

    <provider> <role>webappsec</role> <name>WebAppSec</name> <enabled>true</enabled> <param> <name>csrf.enabled</name> <value> $csrf_enabled </value> </param> <param> <!-- Optional --> <name>csrf.customHeader</name> <value> $header_name </value> </param> <param> <!-- Optional --> <name>csrf.methodsToIgnore</name> <value> $HTTP_methods </value> </param> </provider>


    • $csrf_enabled is either true or false.

    • $header_name when the optional parameter csrf.customHeader is present the value contains the name of the header that determines if the request is from a trusted source. The default, X-XSRF-Header, is described by the NSA in its guidelines for dealing with CSRF in REST.

    $http_methods when the optional parameter csrf.methodsToIgnore is present the value enumerates the HTTP methods to allow without the custom HTTP header. The possible values are GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT, or PATCH. For example, specifying GET allows GET requests from the address bar of a browser. Only specify methods that adhere to REST principals in terms of being idempotent.

  3. Save the file.

    The gateway creates a new WAR file with modified timestamp in $gateway /data/deployments.

loading table of contents...