Jump to content
JasperReports 7.0 is now available ×
  • This documentation is an older version of JasperReports Server Security Guide. View the latest documentation.

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



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

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

    CSRF Protection

    Configuration File






    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.


    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 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


    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.

    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.

    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 TIBCO 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.

    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.




    domainWhitelist at server level


    If you do not have any Visualize.js-enabled web applications, or if you have Visualize.js-enabled web applications that will access your server from the same domain as the server, you should explicitly set the whitelist to blank (attribute defined with an empty value).

    domainWhitelist at server level


    (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






    (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.





    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:


    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:


    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.

    User Feedback

    Recommended Comments

    There are no comments to display.

    This is now closed for further comments

  • Create New...