CSRFGuard 3 Token Injection

Overview

OWASP CSRFGuard implements a variant of the synchronizer token pattern to mitigate the risk of CSRF attacks. In order to implement this pattern, CSRFGuard must offer the capability to place the CSRF prevention token within the HTML produced by the protected web application. CSRFGuard 3 provides developers more fine grain control over the injection of the token. Developers can inject the token in their HTML using either dynamic JavaScript DOM manipulation or a JSP tag library. CSRFGuard no longer intercepts and modifies the HttpServletResponse object as was done in previous releases. The currently available token injection strategies are designed to make the integration of CSRFGuard more feasible and scalable within current enterprise web applications. Developers are encouraged to make use of both the JavaScript DOM Manipulation and the JSP tag library strategies for a complete token injection strategy. The JavaScript DOM Manipulation strategy is ideal as it is automated and requires minimal effort on behalf of the developer. In the event the JavaScript solution is insufficient within a particular application context, developers should leverage the JSP tag library. The purpose of this article is to describe the token injection strategies offered by OWASP CSRFGuard 3.

JavaScript DOM Manipulation

OWASP CSRFGuard 3 supports the ability to dynamically inject CSRF prevention tokens through the DOM all within the user's browser. This strategy is extremely valuable with regards to server-side performance as it simply requires the serving of a dynamic JavaScript file. There is little to no performance hit when the fetched dynamic JavaScript updates the browser's DOM. Making use of the JavaScript token injection solution requires the developer map a Servlet and place a JavaScript HTML tag within all pages sending requests to protected application resources. Developers are strongly encouraged to leverage the JavaScript token injection strategy by default. This strategy requires minimal effort on behalf of the developer as most of the token injection logic is automated. In the event that the JavaScript automated solution may be insufficient for a specific application context, developers should leverage the OWASP CSRFGuard JSP tag library.

Declare and Configure JavaScriptServlet

The JavaScript file used for token injection is dynamically generated by the JavaScriptServlet class using a template file. Ensure that the Owasp.CsrfGuard.jar file is found within the target application's classpath. Copy the Owasp.CsrfGuard.js template file from the OWASP CSRFGuard distribution folder to a non-publicly accessible directory within the target application. For the remainder of this section, we assume the Owasp.CsrfGuard.js template file was placed in the application's WEB-INF folder. Edit the deployment descriptor (web.xml) to declare the JavaScriptServlet class along with any associated initialization parameters. Consider the following configuration snippet taken from the Owasp.CsrfGuard.Test application:

<servlet>
     <servlet-name>JavaScriptServlet</servlet-name>
     <servlet-class>org.owasp.csrfguard.servlet.JavaScriptServlet</servlet-class>
     <init-param>
          <param-name>source-file</param-name>
          <param-value>WEB-INF/Owasp.CsrfGuard.js</param-value>
     </init-param>
     <init-param>
          <param-name>inject-into-forms</param-name>
          <param-value>true</param-value>
     </init-param>
     <init-param>
          <param-name>inject-into-attributes</param-name>
          <param-value>true</param-value>
     </init-param>
    <init-param>
          <param-name>domain-strict</param-name>
          <param-value>false</param-value>
    </init-param>
</servlet>

The aforementioned configuration snippet declares the JavaScriptServlet class using the name "JavaScriptServlet". JavaScriptServlet accepts various initialization parameters augmenting the behavior of the class at runtime. The provided configuration snippet instructs JavaScriptServlet to...

1. Leverage the template JavaScript file at WEB-INF/Owasp.CsrfGuard.js
2. Inject the token into all HTML forms
3. Inject the token into all src and href attributes
4. Leverage loose same origin matching criteria when placing the token in URL resources

Consider the following for a more detailed listing of the initialization parameters supported by JavaScriptServlet:

token-name-identifier

Identifier used to denote where in the JavaScript template file JavaScriptServlet should place the token name. The default value is %TOKEN_NAME%. Developers need only consider the use of this property if customizing the JavaScript template file.

token-value-identifier

Identifier used to denote where in the JavaScript template file JavaScriptServlet should place the token value. The default value is %TOKEN_VALUE%. Developers need only consider the use of this property if customizing the JavaScript template file.

domain-strict-identifier

Identifier used to denote where in the JavaScript template file JavaScriptServlet should place the domain strict local variable value. The default value is %DOMAIN_STRICT%. Developers need only consider the use of this property if customizing the JavaScript template file.

inject-into-forms-identifier

Identifier used to denote where in the JavaScript template file JavaScriptServlet should place the inject into forms local variable value. The default value is %INJECT_FORMS%. Developers need only consider the use of this property if customizing the JavaScript template file.

inject-into-attributes-identifier

Identifier used to denote where in the JavaScript template file JavaScriptServlet should place the inject into attributes local variable value. The default value is %INJECT_ATTRIBUTES%. Developers need only consider the use of this property if customizing the JavaScript template file.

source-file

Denotes the location of the JavaScript template file that should be consumed and dynamically augmented by the JavaScriptServlet class. The default value is WEB-INF/Owasp.CsrfGuard.js. Use of this property and the existence of the specified template file is required.

domain-strict

Boolean value that determines whether or not the dynamic JavaScript code should be strict with regards to what links it should inject the CSRF prevention token. With a value of true, the JavaScript code will only place the token in links that point to the same exact origin from which the HTML originated. With a value of false, the JavaScript code will place the token in links that contain, but may not exactly match, the originating domain.

cache-control

Allows the developer to specify the value of the Cache-Control header in the HTTP response when serving the dynamic JavaScript file. The default value is private, maxage=28800. Caching of the dynamic JavaScript file is intended to minimize traffic and improve performance. Note that the Cache-Control header is always set to "no-store" when the "Rotate" option is set to true in Owasp.CsrfGuard.properties.

inject-into-forms

Boolean value that determines whether or not the dynamic JavaScript code should inject the CSRF prevention token as a hidden field into HTML forms. The default value is true. Developers are strongly discouraged from disabling this property as most server-side state changing actions are triggered via a POST request.

inject-into-attributes

Boolean value that determines whether or not the dynamic JavaScript code should inject the CSRF prevention token in the query string of src and href attributes. Injecting the CSRF prevention token in a URL resource increases its general risk of exposure to unauthorized parties. However, most JavaEE web applications respond in the exact same manner to HTTP requests and their associated parameters regardless of the HTTP method. The risk associated with not protecting GET requests in this situation is perceived greater than the risk of exposing the token in protected GET requests. As a result, the default value of this attribute is set to true. Developers that are confident their server-side state changing controllers will only respond to POST requests (i.e. discarding GET requests) are strongly encouraged to disable this property.

Map JavaScriptServlet

Developers must map the JavaScriptServlet to a URI space such that the Servlet class can be remotely accessed by the dynamic JavaScript code. Consider the following configuration snippet taken directly from the Owasp.CsrfGuard.Test application:

<servlet-mapping>
     <servlet-name>JavaScriptServlet</servlet-name>
     <url-pattern>/JavaScriptServlet</url-pattern>
</servlet-mapping>

The aforementioned configuration snippet maps the Servlet referenced by the name "JavaScriptServlet" to the URI space "/JavaScriptServlet". Any request sent to the /JavaScriptServlet URI will produce a dynamically generated CSRFGuard JavaScript file specific to the user's current session.

Inject Dynamic JavaScript

Developers are required to place an HTML script tag within all pages that are known to send requests to CSRF protected resources. All requests within the current HTML page are augmented to ensure they submit the correct CSRF token for the user's current session. Consider the following code snippet taken directly from the Owasp.CsrfGuard.Test application:

<script src="/Owasp.CsrfGuard.Test/JavaScriptServlet"></script>

The script tag retrieves and executes the dynamically generated JavaScript from the Servlet mapped at /Owasp.CsrfGuard.Test/JavaScriptServlet. This JavaScript code will register an event handler with window.onload. Once triggered, the code will iterate over every HTML element within the DOM looking for either form tags and or tags containing href or src attributes as configured by the JavaScriptServlet initialization parameters. Forms are dynamically updated to include the CSRFGuard token via a hidden field and tags using src and href attributes are updated to include the CSRFGuard token via a query string parameter.

JSP Tag Library

OWASP CSRFGuard 3 exposes a JSP tag library providing developers more fine grain control over token injection. The library exposes JSP tags that allow access to the token name, the token value, and the token name value pair delimited by an equals (=) sign. In order to make use of the tag library, ensure the Owasp.CsrfGuard.jar file is found within the target application's classpath. For example, the Owasp.CsrfGuard.Test application places the OWASP CSRFGuard jar file within the WebContent/WEB-INF/lib directory. After placing the library in the classpath, developers can reference the tags in JSP pages using predefined URI reference. The following JSP code snippet imports the tag library and makes it available using the prefix "csrf":

<%@ taglib uri="http://www.owasp.org/index.php/Category:OWASP_CSRFGuard_Project/Owasp.CsrfGuard.tld" prefix="csrf" %>

The benefit of using the JSP tag library to inject the CSRF prevention token is the fine grain level of control. Developers can place the token in all the correct locations within the context of their applications. This strategy is useful in application contexts where the JavaScript DOM Manipulation strategy is insufficient.

Display Token Name

The OWASP CSRFGuard token name can be obtained through the token-name tag. The token-name tag is useful when injecting the CSRFGuard token name in a non-query string context. Consider the following code snippet taken from the Owasp.CsrfGuard.Test application. This code makes use of the token-name tag to reference the token name in the name attribute of a hidden input field:

<form name="test1" action="protect.html">
     <input type="text" name="text" value="text"/>
     <input type="submit" name="submit" value="submit"/>
     <input type="hidden" name="<csrf:token-name/>" value="<csrf:token-value/>"/>
</form>

Display Token Value

The OWASP CSRFGuard token value can be obtained through the token-value tag. The token-value tag is useful when injecting the CSRFGuard token value in a non-query string context. Consider the following code snippet taken from the Owasp.CsrfGuard.Test application. This code makes use of the token-value tag to reference the token value in the value attribute of a hidden input field:

<form name="test1" action="protect.html">
     <input type="text" name="text" value="text"/>
     <input type="submit" name="submit" value="submit"/>
     <input type="hidden" name="<csrf:token-name/>" value="<csrf:token-value/>"/>
</form>

Display Token Name Value Pair

The OWASP CSRFGuard token name value pair, delimited by an equals sign (=), can be obtained though the token tag. The token tag is useful when injecting the CSRFGuard token value in a query string context. Consider the following code snippet taken from the Owasp.CsrfGuard.Test application. This code makes use of the token tag to reference the token name value pair in the href attribute of an anchor tag:

<a href="protect.html?<csrf:token/>">protect.html</a>