Revision as of 16:35, 11 November 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 two simple steps. First, you must copy the Owasp.CsrfGuard.jar file and map the CsrfGuardFilter in your application's deployment descriptor (web.xml). 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. 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 the 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 the stand-alone filter. 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.