Revision as of 22:09, 13 December 2010

Overview

The purpose of this article is to provide guidance around the installation of OWASP CSRFGuard within a JavaEE web application. Installation of OWASP CSRFGuard 3 is very straight forward requiring three simple steps. First, you must copy the Owasp.CsrfGuard.jar file to your application's classpath. After copying over the OWASP CSRFGuard library, declare and map the CsrfGuardFilter in your application's web.xml deployment descriptor. This instructs the application server to initialize the OWASP CSRFGuard Filter protecting those resources that match the Filter mapping. Finally, customize the Owasp.CsrfGuard.properties file as you see fit. You'll need to make sure you tell CsrfGuardFilter the location of your CSRFGuard properties file via a JavaEE Filter init-param directive. Please refer to the following sub-sections for more detailed information on each of the aforementioned installation steps.

Copy Owasp.CsrfGuard.jar to Classpath

The first thing you need to do is copy the Owasp.CsrfGuard.jar library into your classpath. The most common classpath location to place Owasp.CsrfGuard.jar is within the lib directory of the web application's WEB-INF folder. OWASP CSRFGuard 3 has no additional dependencies outside of the traditional JavaEE runtime environment.

Declare and Map CsrfGuardFilter in web.xml

After placing Owasp.CsrfGuard.jar in your application's classpath, you'll need to declare and map the CsrfGuardFilter in web.xml. All CSRF token verification logic is encompassed within CsrfGuard integrated via the stand-alone filter CsrfGuardFilter. The following web.xml snippet was extracted from the Owasp.CsrfGuard.Test web application:

	<filter>
		<filter-name>CSRFGuard</filter-name>
		<filter-class>org.owasp.csrfguard.CsrfGuardFilter</filter-class>
		<init-param>
			<param-name>config</param-name>
			<param-value>WEB-INF/Owasp.CsrfGuard.properties</param-value>
		</init-param>
		<init-param>
			<param-name>print-config</param-name>
			<param-value>true</param-value>
		</init-param>
	</filter>

We create a filter with the name of CSRFGuard and specify a classname of org.owasp.csrfguard.CsrfGuardFilter. The filter accepts two initialization parameters: config and print-config. The config parameter is required and specifies the location of the CSRFGuard properties file. CSRFGuard will search for the properties file specified by searching the following locations in order of appearance: the application's classpath, a directory accessible by the container, or an arbitrary absolute path. The print-config parameter is optional and simply instructs CSRFGuard to display the parsed properties to the application server log file.

Configure Owasp.CsrfGuard.properties

The Owasp.CsrfGuard.properties file controls how OWASP CSRFGuard behaves at runtime. CSRFGuard looks for the file in the following locations in order: application's classpath, servlet context directory, and current directory. You are encouraged to make use of the sample Owasp.CsrfGuard.properties file bundled with CSRFGuard to help kick-start your deployment efforts. There are various properties supported by CSRFGuard. At a minimum, you'll want to configure the new token landing page and the action properties. Click here for more information regarding the configuration of OWASP CSRFGuard.