Cross-Site Request Forgery (CSRF) is an exploit where the attacker attempts to gain information or perform actions while a user is logged into JasperReports Server in another window or tab of the same browser. This is called session riding. For example, a server administrator logged into JasperReports Server is tricked into opening a malicious website that invisibly uses the browser session to create a new user with administrator permissions, which the attacker can then use to access the system at a later time.
JasperReports Server uses the latest release of CSRFGuard from OWASP (Open Web Application Security Project). CSRFGuard verifies that every POST, PUT, and DELETE request submits a valid token previously obtained from the server. Thisincludes every request submitted via forms or AJAX. When a malicious request arrives without the proper token, the server does not reply and logs an error for administrators to analyze later.
Tokens have the following syntax, however they are sent in HTTP headers or parameters, and the entire exchange is invisible to users:
OWASP_CSRFTOKEN: K8E9-L4NZ-58H6-Z4P2-ZG75-KKBW-U53Z-ZL6X
In the default configuration of the server, CSRF protection is active. We recommend leaving this setting unchanged:
| | In order to fully implement CSRF and secure your server, you must configure the domain whitelist as explained in the section below. |
| CSRF Protection | ||
| Configuration File | ||
| .../WEB-INF/csrf/jrs.csrfguard.properties | ||
| Property | Value | Description |
| org.owasp.csrfguard.Enabled | true <default> | Turns CSRF protection on or off. By default, CSRF protection is enabled. Setting this value to false will disable the CSRF filter and allow any request regardless of tokens. |
| | The configuration file contains many settings that are preconfigured for JasperReports Server. We do not recommend changing any other settings. In particular, the two configOverlay properties are unreliable and not supported. |
After making any changes to the jrs.csrfguard.properties file, you must restart JasperReports Server for the new values to take effect.
Setting the Cross-Domain Whitelist
Applications that use the embedded Visualize.js library typically access JasperReports Server from a different domain. For this reason, CSRF protection includes a whitelist of domains that you specifically allow to access the server. Initially, all your Visualize.js applications can access the server, but you should configure the whitelist so that only your domains have access. Then, any Visualize.js request from an unknown domain will fail with HTTP error 401, and the server will log a CSRF warning.
| | In all cases, even if you do not use Visualize.js, you must configure the whitelist. You should never use a server in production with the default whitelist. |
The domain whitelist is implemented through attributes named domainWhitelist at the user, organization, or server level. Different values can be specified at each level, with the value defined at according to the attribute hierarchy. In addition, the domainWhitelist attribute is defined with administer permissions, meaning that organization admins can set their own values. You can set attributes through the server UI or through the REST API. For more information on how to define attributes and how their values are determined by hierarchy, see the JasperReports Server Administrator Guide.
There are four cases listed in the table below, choose the one suited to your use of Visualize.js.
| Cross-Domain Whitelist | ||||||||
| Configuration Location | ||||||||
| Attribute named domainWhitelist defined at the server level. For security, always set the server level as described below, in addition to setting any alternate values at the organization or user levels.
| ||||||||
| Attribute | Value | Description | ||||||
| domainWhitelist at server level | <blank>
| If you do not have any Visualize.js-enabled web applications, you should explicitly set the whitelist to blank (attribute defined with an empty value). | ||||||
| domainWhitelist at server level | <blank>
| If you have Visualize.js-enabled web applications that will access your server from the same domain as the server, then they will not trigger error 401, and you should explicitly set the whitelist to blank (empty value). | ||||||
| domainWhitelist at server level | example.com (see below) | If you have Visualize.js-enabled web applications that will access your server from a different domain, then specify an expression that will match the domain name. For the syntax of this expression, see below. | ||||||
| domainWhitelist at server level domainWhitelist at org1 level domainWhitelist at user2 level ... | <blank> example1.com example2.com ... (see below) | If your organizations or users have Visualize.js applications on specific domains, you could use the hierarchy of attributes to set the whitelist according to each organization's or each user's individual domain. In this case, make sure the whitelist at the server level is defined as blank. For the syntax of this expression, see below. | ||||||
| domainWhitelist1 domainWhitelist2 | <regexp> <regexp> | Additional whitelist attributes. If you want to add more than one regular expression to the whitelist, define these additional attributes at the same level as domainWhitelist. If you need further attributes, you can specify them in the additionalWhitelistAttributes property of the crossDomainFilter bean in the file .../WEB-INF/applicationContext.xml. | ||||||
The actual value of the attribute is a simplified expression that the server converts into the full regular expression. The value must include the protocol (http), any sub-domains that you use, and the port as well. The value you write can use * and . which the server translates into proper form as .* and .. The server also adds ^ and $ to the ends of the expression. For example, a typical value for this attribute would be:
http://*.myexample.com:80d0 which is translated to ^http://.*.myexample.com:80d0$
This will match the following domains you might use:
http://bi3.myexample.com:8080 and http://bi3.myexample.com:8090
http://bi4.myexample.com:8080 and http://bi4.myexample.com:8090
But it will not match the following:
http://myexample.com:8080 or http://bi3.myexample.com:8081
If you wish to write your own complete regular expression, surround it with ^ and $, and it will be used as-is by the server.
Remember that if you add Visualize.js applications that run on different domains, or change the domains where they run, then you must update the whitelist attributes accordingly. Visualize.js applications on domains that are not whitelisted will not work.
| | Do not delete the domainWhitelist property from the server level. That will remove the whitelist, but upon upgrading the server, the attribute will be restored with a less secure default value. When the attribute is defined, even with an empty value, it will remain during any server upgrade. |
Sending REST Requests from a Browser
If you use the REST API to access JasperReports Server from within an application, this does not trigger a CSRF warning because the application is separate from any access through the browser. However, some browser plug-ins can be used to send REST API requests, and using these to send POST, PUT, or DELETE requests will trigger a CSRF warning and fail. GET requests from a browser REST client are safe and do not fail the CSRF check.
To allow REST API requests through a browser, configure your browser REST client to include the following header in every request:
X-REMOTE-DOMAIN: 1
CSRF Browser Compatibility
Because only browsers are susceptible to CSRF, the CSRF protection mechanism detects browsers based on their user-agent string embedded in the request. For performance reasons, the current configuration only filters for Mozilla and Opera user-agents, because these cover more than 99% of all browsers in use, such as Chrome, Firefox, Internet Explorer, and Safari.
If your users have browsers with user-agents other than Mozilla, they will not be protected against CSRF by default.
| | All browsers officially supported by JasperReports Server are protected against CSRF. The following instructions are provided for testing purposes only. |
To enable CSRF protection for these browsers, you can add the corresponding user-agent to the CSRF filter:
| 1. | Find the name of the user-agent for the given browser. If you cannot find the user-agent, many are listed on the following website: |
http://www.useragentstring.com/pages/Browserlist/
| 2. | Open the file .../WEB-INF/applicationContext.xml for editing. |
| 3. | Locate the csrfGuardFilter bean and its protectedUserAgentRegexs property. Each list value is a regular expression that is matched against every request's user-agent value in its entirety. |
| 4. | Add a regular expression to the protectedUserAgentRegexs property list that will match the user-agent string from your desired browser. |
| 5. | Restart JasperReports Server. |
Recommended Comments
There are no comments to display.