CSRFGuard 3 Configuration

Overview

The most important aspect of deploying OWASP CSRFGuard is configuration of the Owasp.CsrfGuard.properties file. There are a minimum number of configuration settings that users should review and specify before running an instance of OWASP CSRFGuard. Such configurations include specifying the new token landing page, enabling Ajax support for applications making use of XMLHttpRequest, capturing pages that should not be protected, as well as configuring one or more actions that should be invoked when a CSRF attack is identified. The purpose of this article is to provide an overview of key OWASP CSRFGuard configuration settings.

New Token Landing Page

The new token landing page property (org.owasp.csrfguard.NewTokenLandingPage) defines where to send a user if the token is being generated for the first time. CSRFGuard will redirect the user to the current page without any parameters if the property is not specified. Preventing the protected application from consuming a request whose session does not yet have a CSRF token through the use of a redirect prevents the execution of a one-time CSRF attack. The following configuration snippet instructs OWASP CSRFGuard to redirect the user to /Owasp.CsrfGuard.Test/index.html when they visit a protected resource without having a corresponding CSRF token present in the HttpSession object.

org.owasp.csrfguard.NewTokenLandingPage=/Owasp.CsrfGuard.Test/index.html

Ajax and XMLHttpRequest Support

The Ajax and XMLHttpRequest property (org.owasp.csrfguard.Ajax) indicates whether or not OWASP CSRFGuard should check for the presence of the X-Requested-With (case insensitive) header in the HTTP request. If the header is found, then we have strong evidence that the request was sent using the XMLHttpRequest object. As long as the browser properly enforces the Same Origin Policy with regards to the use of XMLHttpRequest, verification of the header is a strong defense against CSRF attacks for Ajax applications. Note that verification of the X-Requested-With header takes precedence over verification of the CSRF token supplied as an HTTP parameter. More specifically, CSRFGuard does not verify the presence of the CSRF token if the Ajax support property is enabled and the X-Requested-With header is embedded within the request. The following code snippet instructs OWASP CSRFGuard to support Ajax requests by verifying the presence of the X-Requested-With header.

org.owasp.csrfguard.Ajax=true

Referrer Checking

The check referrer header property (org.owasp.csrfguard.Referrer) verifies that the supplied referrer header matches a regular expression. When enabled, verification of the referrer header will take precedence over verification of the CSRF token in the HTTP request. Referrer headers are consistently sent by browsers for pure HTTPS communications. Verification of the referrer header is a strong defense against CSRF attacks when consistently using HTTPS as a CSRF attack will not include this header in the request(s) unless the malicious HTML is embedded within the site for which the attack is targeted. Inclusion of the referrer header is less consistent when using traditional HTTP traffic across browsers. CSRFGuard will fall back to verifying the presence of the CSRF token if the referrer header was not included in the HTTP request. The following code snippet instructs OWASP CSRFGuard to verify that the referrer header matches the regular expression .*localhost.*, ensuring the request came from a local resource.

org.owasp.csrfguard.Referrer=.*localhost.*

Unprotected Pages

The unprotected pages property (org.owasp.csrfguard.unprotected.*) defines a series of pages that should not be protected by CSRFGuard. Such configurations are useful when the CsrfGuardFilter is aggressively mapped (ex: /*). The syntax of the property name is org.owasp.csrfguard.unprotected.[PageName], where PageName is some arbitrary identifier that can be used to reference a resource. The syntax of defining the uri of unprotected pages is the same as the syntax used by the JavaEE container for uri mapping. Specifically, CSRFGuard will identify the first match (if any) between the requested uri and an unprotected page in order of declaration. Match criteria is as follows:

Case 1: exact match between request uri and unprotected page

Case 2: longest path prefix match, beginning / and ending /*

Case 3: extension match, beginning *.

Default: requested resource must be validated by CSRFGuard

The following code snippet illustrates the three use cases over four examples. The first two examples (Tag and JavaScriptServlet) look for direct URI matches. The third example (Html) looks for all resources ending in a .html extension. The last example (Public) looks for all resources prefixed with the URI path /MySite/Public/*.

org.owasp.csrfguard.unprotected.Tag=/Owasp.CsrfGuard.Test/tag.jsp
org.owasp.csrfguard.unprotected.JavaScriptServlet=/Owasp.CsrfGuard.Test/JavaScriptServlet
org.owasp.csrfguard.unprotected.Html=*.html
org.owasp.csrfguard.unprotected.Public=/MySite/Public/*

Actions: Responding to Attacks

The actions directive (org.owasp.csrfguard.action.*) gives the user the ability to specify one or more actions that should be invoked when a CSRF attack is detected. Every action must implement the org.owasp.csrfguard.action.IAction interface either directly or indirectly through the org.owasp.csrfguard.action.AbstractAction helper class. Many actions accept parameters that can be specified along with the action class declaration. These parameters are consumed at runtime and impact the behavior of the associated action.

The syntax for defining and configuring CSRFGuard actions is relatively straight forward. Let us assume we wish to redirect the user to a default page when a CSRF attack is detected. A redirect action already exists within the CSRFGuard bundle and is available via the class name org.owasp.csrfguard.actions.Redirect. In order to enable this action, we capture the following declaration in the Owasp.CsrfGuard.properties file:

syntax: org.owasp.csrfguard.action.[actionName]=[className]
example: org.owasp.csrfguard.action.class.Redirect=org.owasp.csrfguard.actions.Redirect

The aforementioned directive declares an action called "Redirect" (i.e. [actionName]) referencing the Java class "org.owasp.csrfguard.actions.Redirect" (i.e. [className]). Anytime a CSRF attack is detected, the Redirect action will be executed. You may be asking yourself, "but how do I specify where the user is redirected?"; this is where action parameters come into play. In order to specify the redirect location, we capture the following declaration in the Owasp.CsrfGuard.properties file:

syntax: org.owasp.csrfguard.action.[actionName].[parameterName]=[parameterValue]
example: org.owasp.csrfguard.action.Redirect.ErrorPage=/Owasp.CsrfGuard.Test/error.html

The aforementioned directive declares an action parameter called "ErrorPage" (i.e. [parameterName]) with the value of "/Owasp.CsrfGuard.Test/error.html" (i.e. [parameterValue]) for the action "Redirect" (i.e. [actionName]). The Redirect action expects the "ErrorPage" parameter to be defined and will redirect the user to this location when an attack is detected.

There are several "out of the box" actions made available with the OWASP CSRFGuard distributable.

org.owasp.csrfguard.action.Log

Creates a customized log message whenever a CSRF attack is detected by OWASP CSRFGuard. The log message is captured using the logger mechanism defined by the org.owasp.csrfguard.Logger directive in the Owasp.CsrfGuard.properties file. Log accepts the following action parameters:

org.owasp.csrfguard.action.Log.Message

Allows the user to define the format of the log message to be recorded. The Message parameter supports several formatting options to aide in the customization of the message to the particular attack. The following formatting options are supported:

%exception - String representation of the CsrfGuardException thrown by the CsrfGuard class.
%exception_message - Localized exception message of the class CsrfGuardException thrown by the CsrfGuard class.
%remote_ip - Remote IP address of the client that sent the CSRF attack to the server.
%remote_host - Remote host name of the client that sent the CSRF attack to the server.
%remote_port - Remote port of the client that sent the CSRF attack to the server.
%local_ip - Local IP address of the server that detected the CSRF attack.
%local_host - Local host name of the server that detected the CSRF attack.
%local_port - Local port of the server that detected the CSRF attack.
%request_uri - Request URI for which the CSRF attack was targeting.
%request_url - Request URL for which the CSRF attack was targeting.
%user - User information as made available by the javax.servlet.http.HttpServletRequest.getRemoteUser() method invocation.

org.owasp.csrfguard.action.Invalidate

Invalidate any existing HttpSession associated with the current HttpServletRequest. Note that this is the session of the victim for which the CSRF attack was targeting. Invalidating the JavaEE container's session generally results in the user having to re-authenticate. There are no action parameters associated with this action.

org.owasp.csrfguard.action.Redirect

Redirects the user to the URI specified in the Page action parameter. Attempting to utilize this action in combination with Forward will generally result in the JavaEE container throwing IllegalStateException. The action accepts the following action parameters:

org.owasp.csrfguard.action.Redirect.Page

Defines the URI for which the user is redirected when a CSRF attack is detected.

org.owasp.csrfguard.action.Forward

Forwards the user to the URI specified in the Page action parameter. Attempting to utilize this action in combination with Redirect will generally result in the JavaEE container throwing IllegalStateException. The action accepts the following action parameters:

org.owasp.csrfguard.action.Forward.Page

Defines the URI for which the user is forwarded when a CSRF attack is detected.

org.owasp.csrfguard.action.RequestAttribute

Makes the CsrfGuardException thrown by the CsrfGuard class when an attack is detected programmatically available as an attribute in the HttpServletRequest object. The action accepts the following action parameters:

org.owasp.csrfguard.action.RequestAttribute.AttributeName

Defines the attribute name that should be used when placing the CsrfGuardException in the HttpServletRequest attributes collection.

org.owasp.csrfguard.action.SessionAttribute

Makes the CsrfGuardException thrown by the CsrfGuard class when an attack is detected programmatically available as an attribute in the HttpSession object. The action accepts the following action parameters:

org.owasp.csrfguard.action.SessionAttribute.AttributeName

Defines the attribute name that should be used when placing the CsrfGuardException in the HttpSession attributes collection.