Configuring CSRF Protection¶

Cross-Site Request Forgery (CSRF) enables an attacker to either gain information or perform actions while a user is logged into JasperReports Server. The user may be logged 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 user with administrator permissions. The attacker can then use it to access the system later.

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. This includes 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 are sent in HTTP headers or parameters, and the entire exchange is invisible to users. Tokens have the following syntax:

OWASP_CSRFTOKEN: K8E9-L4NZ-58H6-Z4P2-ZG75-KKBW-U53Z-ZL6X

Warning

In the default configuration of the server, CSRF protection is active. We recommend leaving this setting unchanged.

However, to fully implement CSRF and secure your server, you must configure the domain whitelist as explained in the next section.

CSRF Protection
Configuration File
`.../WEB-INF/csrf/jrs.csrfguard.properties`
Property	Value	Description
`org.owasp.csrfguard.Enabled`	`true` <default> `false`	Turns CSRF protection on or off. By default, CSRF protection is enabled. Setting this value to false disables the CSRF filter and allows any request regardless of tokens.

Note

This 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 updating the jrs.csrfguard.properties file, you must restart JasperReports Server for the new values to take effect.

Setting the Cross-Domain Whitelist¶

Warning

In all cases, even if you do not use Visualize.js, you must configure the whitelist. Never use a server in production with the default 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 fails with HTTP error 401, and the server logs a CSRF warning.

The domain whitelist is implemented through attributes named domainWhitelist at the user, organization, or server-level. You may specify different values at each level. The values are defined according to the attribute hierarchy. In addition, the domainWhitelist attribute is defined with administrator permissions, implying that organization admins can set their own values. The attributes are set 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, refer to 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
The attribute `domainWhitelist` is defined at the server level. In addition to setting any alternate values at the organization or user levels, for security, always set the server level as described below: Server level: as system admin (`superuser`), select Manage > Server Settings then Server Attributes. Organization or user level: as any administrator, select Manage > Organizations or Manage > Users, then select the organization or user, click Edit in the right-hand panel, and select the Attributes tab.
Attribute	Value	Description
`domainWhitelist` at server level	<blank>	Explicitly set the whitelist to blank (attribute defined with an empty value) if: you do not have any Visualize.js-enabled web applications, OR you have Visualize.js-enabled web applications that access your server from the `same` domain as the server
`domainWhitelist` at server level	`example.com` (See below)	If you have Visualize.js-enabled web applications that access your server from a `different` domain, then specify an expression that matches 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 that the whitelist at the server level is defined as blank. For the syntax of this expression, see below.
`domainWhitelist1` `domainWhitelist2`	<regexp> <regexp>	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 can contain * and . which the server translates into the 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:80\d0 which is translated to ^http://.*\.myexample\.com:80\d0$

This matches the following domains that 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 does 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 do not work.

Warning

Do not delete the domainWhitelist property from the server level. That removes the whitelist, but on upgrading the server, the attribute is restored with a less secure default value. When the attribute is defined, even with an empty value, it remains 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. Using these to send POST, PUT, or DELETE requests 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¶

Only browsers are susceptible to CSRF. Hence, the CSRF protection mechanism detects browsers based on the user-agent string embedded in the request. For performance reasons, the current configuration only filters for Mozilla and Opera user-agents. They cover more than 99% of the 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.

Note

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:

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/
Open the file .../WEB-INF/applicationContext.xml for editing.
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.
Add a regular expression to the protectedUserAgentRegexs property list that matches the user-agent string from your desired browser.
Restart JasperReports Server.