If the directory/file paths specified in this guide do not exist in your WSO2 product, see Directory Structure of WSO2 Products to locate the paths applicable to your product.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

You can protect HTTP GET requests sent as a result of resource inclusions and links can by appending a relevant token in the “href” or “src” attributes. Include these tokens manually using provided JSP tag library or by using a JavaScript based automated injection mechanism. AJAX requests are protected by injecting an additional header, which contains a CSRF token.You can use the following approaches to mitigate CSRF attacks.

Configuring applications in WSO2 product to mitigate CSRF attacks

Note

Before you begin, note the following:

  • If your WSO2 product is based on Carbon 4.4.6 or a later version, the configurations for mitigating CSRF attacks are enabled by default for all the applications that are built into the product. Therefore, you need to apply these configurations manually, only if you have any custom applications deployed in your product.
  • If your WSO2 product is based on a Carbon version prior to version 4.4.6, the configurations for mitigating CSRF attacks should be applied to all applications manually.

  • Important! Some updates of JDK 1.8 (for example, JDK1.8.0_151) are affected by a known issue related to GZIP decoding, which may prevent these CSRF-related configurations from working for your product. Therefore, until this issue is fixed, we recommend one of the following approaches:
    • Be sure that your product is running on JDK1.8.0_144 or JDK1.8.0_077. We have verified that these JDK versions are not affected by the known issue.
    • Alternatively, you can disable GZIP decoding for your product by following the steps given below. This will ensure that your product is not affected by the known issue.
      1. Open the catalina-server.xml file from the <PRODUCT_HOME>/repository/conf/tomcat/ directory.
      2. Set the compression parameter (under each of the connector configurations) to false as shown below:

        Code Block
        compression="off"
      3. Restart the server.

See the following for instructions on manually updating CSRF configurations in WSO2 products:

Table of Contents
maxLevel4
minLevel4

...

  1. Add the following configurations in the web.xml file of your application.

    Code Block
    languagexml
    <!-- OWASP CSRFGuard context listener used to read CSRF configuration -->
    <listener>
        <listener-class>org.owasp.csrfguard.CsrfGuardServletContextListener</listener-class>
    </listener>
    <!-- OWASP CSRFGuard session listener used to generate per-session CSRF token -->
    <listener>
        <listener-class>org.owasp.csrfguard.CsrfGuardHttpSessionListener</listener-class>
    </listener>
    <!-- OWASP CSRFGuard per-application configuration property file location-->
    <context-param>
        <param-name>Owasp.CsrfGuard.Config</param-name>
        <param-value>/repository/conf/security/Owasp.CsrfGuard.properties</param-value>
    </context-param>
    <!-- OWASP CSRFGuard filter used to validate CSRF token-->
    <filter>
        <filter-name>CSRFGuard</filter-name>
        <filter-class>org.owasp.csrfguard.CsrfGuardFilter</filter-class>
    </filter>
    <!-- OWASP CSRFGuard filter mapping used to validate CSRF token-->
    <filter-mapping>
        <filter-name>CSRFGuard</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
    <!-- OWASP CSRFGuard servlet that serves dynamic token injection JavaScript (application can customize the URL pattern as required)-->
    <servlet>
        <servlet-name>JavaScriptServlet</servlet-name>
        <servlet-class>org.owasp.csrfguard.servlet.JavaScriptServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>JavaScriptServlet</servlet-name>
        <url-pattern>/csrf.js</url-pattern>
    </servlet-mapping>
  2. Include the following JavaScriptServlet as the first JavaScript inclusion of the <head> element, in the HTML template of all pages of the application that you need to protect.

    Code Block
    languagejs
    … 
    <html>
    	<head>
    		…
    		<script type=”text/javascript” src=”/csrf.js”></script>
    
    		<!-- other JavaScript inclusions should follow “csrf.js” inclusion -->
    		<script type=”text/javascript” src=”/main.js”></script>
    		… 
    	</head>
    	<body>
    		...
    	</body>
    </html>
  3. Create a CSRF configuration properties file (e.g. abc.properties) within your application, and copy the content in the <CARBON_HOME>repository/conf/security/ Owasp.CsrfGuard.Carbon.properties file to it.
  4. Use the org.owasp.csrfguard.unprotected. prefix in the configuration property keys, for the relevant patterns that you need to exclude from CSRF protection. For example;

    Code Block
    languagejs
    org.owasp.csrfguard.unprotected.Default=%servletContext%/exampleAction
    org.owasp.csrfguard.unprotected.Default_1=%servletContext%/exampleAction
    org.owasp.csrfguard.unprotected.Example=%servletContext%/exampleAction/*
    org.owasp.csrfguard.unprotected.ExampleRegEx=^%servletContext%/.*Public\.do$
  5.   Change the following configuration properties, to further enhance security. You may need justifiable application level requirements to change them since they will affect performance or user experience.

    PropertyDescription
    org.owasp.csrfguard.PRNG=SHA1PRNG
    Defines the hashing algorithm used to generate the CSRF token.
    org.owasp.csrfguard.TokenLength=32Defines the length of the CSRF token.
    org.owasp.csrfguard.action.Invalidate=org.owasp.csrfguard.action.InvalidateInvalidates the user session, if a CSRF attack attempt was blocked by CSRFGuard.

Securing Jaggery applications

...

  1. Add the following configurations in the jaggery.conf file of your application.

    Code Block
    languagejava
     "listeners" : [
    	{
    		"class" : "org.owasp.csrfguard.CsrfGuardServletContextListener"	
    	},
    	{
    		"class" : "org.owasp.csrfguard.CsrfGuardHttpSessionListener"	
    	}
        ],
        "servlets" : [
    	{
    		"name" : "JavaScriptServlet",
    		"class" : "org.owasp.csrfguard.servlet.JavaScriptServlet"
    	}
        ],
        "servletMappings" : [
    	{
    		"name" : "JavaScriptServlet",
    		"url" : "/csrf.js"
    	}
        ],
        "contextParams" : [
    	{
    		"name" : "Owasp.CsrfGuard.Config",
    		"value" : "/repository/conf/security/Owasp.CsrfGuard.dashboard.properties"
    	}
        ]
  2. Include the following JavaScriptServlet as the first JavaScript inclusion of the <head> element in the HTML template of all pages of the application that you need to protect.

    Code Block
    languagejs
    <html>
    	<head>
    		…
    		<script type=”text/javascript” src=”/csrf.js”></script>
    
    		<!-- other JavaScript inclusions should follow “csrf.js” inclusion -->
    		<script type=”text/javascript” src=”/main.js”></script>
    		… 
    	</head>
    	<body>
    		...
    	</body>
    </html>
  3. Create a CSRF configuration properties file (e.g. abc.properties) within your application, and copy the content in the <CARBON_HOME>repository/conf/security/ Owasp.CsrfGuard.Carbon.properties file to it.
  4. Use the org.owasp.csrfguard.unprotected. prefix in the configuration property keys, for the relevant patterns that you need to exclude from CSRF protection. For example;

    Code Block
    languagejs
    org.owasp.csrfguard.unprotected.Default=%servletContext%/exampleAction
    org.owasp.csrfguard.unprotected.Default_1=%servletContext%/exampleAction
    org.owasp.csrfguard.unprotected.Example=%servletContext%/exampleAction/*
    org.owasp.csrfguard.unprotected.ExampleRegEx=^%servletContext%/.*Public\.do$
  5. Change the following configuration properties, to further enhance security. You may need justifiable application level requirements to change them since they will affect performance or user experience.

    PropertyDescription
    org.owasp.csrfguard.PRNG=SHA1PRNG Defines the hashing algorithm used to generate the CSRF token.
    org.owasp.csrfguard.TokenLength=32
    Defines the length of the CSRF token.
    org.owasp.csrfguard.action.Invalidate=org.owasp.csrfguard.action.Invalidate
    Invalidates the user session, if a CSRF attack attempt was blocked by CSRFGuard.