CSRFGuard 2.0 Installation

Overview
The second installment of the OWASP CSRFGuard utilizes an HTML Parser for greater accuracy and usability. This page details all of the steps necessary to deploy CSRFGuard 2.x in your web application.

Quick Steps:


 * Copy ${PROJECT}/dist/OWASP-CSRFGuard-2.0.jar and ${PROJECT}/lib/htmlparser.jar to a directory accessible by your container.
 * Add a 'filter' entry to your web deployment descriptor.
 * Add a mapping for the newly created filter entry.

Note: If you map OWASP CSRFGuard to a resource that does not contain nor generate HTML (ex. images, Javascript source, etc.), you will get runtime exceptions!

Add OWASP CSRFGuard To ClassPath
In order for your web application container to invoke the OWASP CSRFGuard filter, it will need to be accessible in the classpath. If you are working with a single application, we recommend placing OWASP CSRFGuard and the htmlparser.jar dependency within the WEB-INF/lib folder of your web application project. If you have multiple projects (ex. an EAR) that make use of the filter, we recommend placing OWASP CSRFGuard and the htmlparser.jar dependency in a single library folder that is accessible by your container. For example, if our application container were Tomcat and we had multiple applications making use of OWASP CSRFGuard, we would place the Jar file in the tomcat/common/lib directory. OWASP CSRFGuard can now be utilized by every application deployed by the container.

Update Deployment Descriptor
Java EE filters provide the ability to intercept, view, and modify both the request and associated response for the requesting client. In order for our application to make use of the OWASP CSRFGuard filter, we must modify the application's web.xml file. First we must declare the filter and any initialization parameters that it may accept. Currently, the OWASP CSRFGuard 2.x series accepts 5 initialization parameters. These parameters are as follows:

error-page    -  The page an end user is directed to when a CSRF attack is detected token-name    -  The parameter name of the unique request token. The default value is OWASP_CSRFTOKEN. token-length  -  The length of the unique request token. The default value is 16. prng-algorithm - The name of the PRNG used to generate the random token. The default value is SHA1PRNG debug         -  Whether or not to display debug information. The default value is false.

The following is a sample entry used to test CSRFGuard in WebGoat:

CSRFGuard org.owasp.csrf.CSRFGuard  error-page attack   token-name OWASP_CSRFTOKEN   token-length</param-name> 32</param-value> </init-param>  prng-algorithm</param-name> SHA1PRNG</param-value> </init-param>  debug</param-name> true</param-value> </init-param>

After declaring the filter in the descriptor, we must specify what resources this filter should handle. We can instruct the filter to handle requests for entire servlets or specific URL patterns. The following example instructs the OWASP CSRFGuard to handle all requests to the 'WebGoat' servlet as well as any requests ending in a .jsp:

<filter-mapping> CSRFGuard</filter-name> <servlet-name>WebGoat</servlet-name> </filter-mapping>

<filter-mapping> CSRFGuard</filter-name> <url-pattern>*.jsp</url-pattern> </filter-mapping>

Note: If you map OWASP CSRFGuard to a resource that does not contain nor generate HTML (ex. images, Javascript source, etc.), you will get runtime exceptions!