JasperReports Server Security Guide Jasper Reports

User Manual:

Open the PDF directly: View PDF .
Page Count: 92

Download
Open PDF In Browser	View PDF

TIBCO JASPERREPORTS® SERVER
SECURITY GUIDE
RELEASE 6.4

http://www.jaspersoft.com

Copyright ©2005-2017 TIBCO Software Inc. All Rights Reserved. TIBCO Software Inc.
This is version 0217-JSP64-04 of the TIBCO JasperReports Server Security Guide.

TABLE OF CONTENTS
Chapter 1 Introduction to JasperReports® Server

7

Chapter 2 Overview of JasperReports Server Security

9

2.1 Authentication
2.2 Authorization Overview
Chapter 3 Application Security
3.1 Encrypting Passwords in Configuration Files
3.1.1 Encrypting Configuration Passwords on Tomcat
3.1.2 Encrypting Configuration Passwords on Enterprise Servers
3.1.3 Encrypting Additional Properties in default_master.properties
3.1.4 Password Encryption for External Authentication
3.1.5 Encryption Options
3.2 Configuring CSRF Protection
3.2.1 Setting the Cross-Domain Whitelist
3.2.2 Sending REST Requests from a Browser
3.2.3 CSRF Browser Compatibility
3.3 Protecting Against SQL Injection
3.3.1 Customizing the Error Message
3.3.2 Understanding Query Validation
3.3.3 Adding Validation for Stored Procedures
3.4 Protecting Against Cross-Site Scripting
3.4.1 Configuring Input Validation
3.4.2 Customizing Security Error Messages
3.4.3 Understanding Input Validation
3.4.4 Customizing Rules and Expressions
3.4.5 Further Configuration
3.5 Restricting File Uploads
3.6 Restricting Groovy's Access
3.7 Hiding Stack Trace Messages
3.8 Defining a Cross-Domain Policy for Flash
3.9 Enabling SSL in Tomcat
3.9.1 Setting Up an SSL Certificate
3.9.2 Enabling SSL in the Web Server

TIBCO Software Inc.

9
10
13
14
14
15
15
17
19
20
20
22
23
23
24
24
26
27
27
28
28
29
31
32
34
35
37
38
38
39

3

TIBCO JasperReports Server Security Guide

3.9.3 Configuring JasperReports Server to Use Only SSL
3.10 Disabling Unused HTTP Verbs
3.11 Configuring HTTP Header Options
3.12 Setting the Secure Flag on Cookies
3.13 Setting httpOnly for Cookies
3.13.1 Setting httpOnly for Tomcat 7
3.13.2 Setting httpOnly for Tomcat 6
3.14 Protection Domain Infrastructure in Tomcat
3.14.1 Enabling the JVM Security Manager
3.14.2 Restoring Disallowed Permissions
3.14.3 Additional Customizations for Previous Versions of Tomcat
3.15 Encrypting Passwords in URLs
Chapter 4 User Security
4.1 Configuring the User Session Timeout
4.2 Configuring User Password Options
4.2.1 Configuring Password Memory
4.2.2 Enabling Password Expiration
4.2.3 Allowing Users to Change their Passwords
4.2.4 Enforcing Password Patterns
4.3 Encrypting User Passwords
4.3.1 Dropping and Recreating the Database in PostgreSQL
4.3.2 Dropping and Recreating the Database in MySQL
4.3.3 Dropping and Recreating the Database in Oracle
4.3.4 Dropping and Recreating in the Database in Microsoft SQL Server
4.4 Encrypting User Session Login
4.4.1 Dynamic Key Encryption
4.4.2 Static Key Encryption
Chapter 5 Securing Data in a Domain
5.1 Business Case
5.2 Process Overview
5.3 Sales Domain
5.4 Roles, Users, and Attributes
5.4.1 Roles
5.4.2 Users
5.4.3 User Attributes
5.5 Setting Up Logging and Testing
5.5.1 Enabling Logging
5.5.2 Creating a Test Report
5.6 Creating a Domain Security File
5.6.1 Access Grant Syntax
5.6.2 Row-level Security
5.6.3 Column-level Security
5.6.4 CZS’s Item Group Access Grants for Sales Data
5.6.5 Uploading the Security File
5.7 Testing and Results

4

40
40
41
41
42
42
43
43
43
44
45
46
47
47
48
48
48
49
49
50
52
52
53
53
53
55
55
57
58
58
59
60
60
61
61
62
62
63
63
64
65
67
67
68
68

TIBCO Software Inc.

5.8 Updating your Security File
5.9 Domain and Security Recommendations
5.10 Domain Reference Material
5.10.1 Domain Design in XML Format
5.10.2 Domain Security File

71
72
74
74
77

Glossary

79

Index

89

TIBCO Software Inc.

5

TIBCO JasperReports Server Security Guide

6

TIBCO Software Inc.

INTRODUCTION TO JASPERREPORTS® SERVER

CHAPTER 1

TIBCO JasperReports® Server builds on TIBCO JasperReports® Library as a comprehensive family of Business
Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis
capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end
BI suite utilizing common metadata and provide shared services, such as security, a repository, and scheduling.
The server exposes comprehensive public interfaces enabling seamless integration with other applications and
the capability to easily add custom functionality.
This section describes functionality that can be restricted by the software license for JasperReports
Server. If you don’t see some of the options described in this section, your license may prohibit you from
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

The heart of the TIBCO Jaspersoft® BI Suite is the server, which provides the ability to:
•
•
•
•
•

Easily create new reports based on views designed in an intuitive, web-based, drag and drop Ad Hoc
Editor.
Efficiently and securely manage many reports.
Interact with reports, including sorting, changing formatting, entering parameters, and drilling on data.
Schedule reports for distribution through email and storage in the repository.
Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey
business trends.

For users interested in multi-dimensional modeling, we offer Jaspersoft® OLAP, which runs as part of the server.
While the Ad Hoc Editor lets users create simple reports, more complex reports can be created outside of the
server. You can either use Jaspersoft® Studio or manually write JRXML code to create a report that can be run
in the server. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the
JasperReports file structure.
You can use the following sources of information to learn about JasperReports Server:
•

•

Our core documentation describes how to install, administer, and use JasperReports Server and Jaspersoft
Studio. Core documentation is available as PDFs in the doc subdirectory of your JasperReports Server
installation. You can also access PDF and HTML versions of these guides online from the Documentation
section of the Jaspersoft Community website.
Our Ultimate Guides document advanced features and configuration. They also include best practice
recommendations and numerous examples. You can access PDF and HTML versions of these guides online
from the Documentation section of the Jaspersoft Community website.

TIBCO Software Inc.

7

TIBCO JasperReports Server Security Guide

•

•
•

Our Online Learning Portal lets you learn at your own pace, and covers topics for developers, system
administrators, business users, and data integration users. The Portal is available online from the Professional
Services section of our website.
Our free samples, which are installed with JasperReports Library, Jaspersoft Studio, and JasperReports
Server, are available and documented online. Please visit our GitHub repository.
If you have a subscription to our professional support offerings, please contact our Technical Support team
when you have questions or run into difficulties. They're available on the web at https://support.tibco.com
and through email at js-support@tibco.com.

JasperReports Server is a component of both a community project and commercial offerings. Each integrates the
standard features such as security, scheduling, a web services interface, and much more for running and sharing
reports. Commercial editions provide additional features, including Ad Hoc views and reports, advanced charts,
dashboards, Domains, auditing, and a multi-organization architecture for hosting large BI deployments.

8

TIBCO Software Inc.

Chapter 2 Overview of JasperReports Server Security

CHAPTER 2

OVERVIEW OF JASPERREPORTS SERVER SECURITY

JasperReports Server ensures that people can access only the data they're allowed to see. The settings that define
organizations, users, roles, and repository resources work together to provide complete access control that
includes:
•
•
•

Authentication – Restricts access to identified users and protects that access with passwords. Defines roles
for grouping users and assigning permissions.
Authorization – Controls access to repository objects, pages, and menus based on users and roles.
Data level security (commercial version only) – Defines row and column level permissions to access your
data. Row and column level permissions can be defined and enforced in Domains.

Administrators must keep security in mind at all times when managing organizations, user, roles, and resources,
because the security settings behind each of these rely on the others.
The bundled installer is not meant for use in either production environments or security testing; it's only intended for
evaluation purposes. The application server provided in that package has been configured with minimal security.
We recommend that production environments use the WAR package deployed to an application server configured
to your security standards.
This guide focuses on security concerns specific to JasperReports Server. However, you should consider other
security precautions in your environment. For example, an end-user can potentially exploit JasperReports Server's
Test Connection option when scheduling reports to an FTP server. If this is a concern, you can secure the port (by
default, port 21) at the operating system level.

This chapter contains the following sections:
•
•

2.1

Authentication
Authorization Overview

Authentication
The first part of security is to define user accounts and secure them with passwords to give each user an identity
within JasperReports Server. The server stores user definitions, including encrypted passwords, in a private
database. Administrators create, modify, and delete user accounts through the administrator pages, as described
in the JasperReports Server Administrator Guide.
JasperReports Server also implements roles for creating groups or classes of users with similar permissions. A
user can belong to any number of roles and have the privileges of each The server stores role definition in its
private database, and administrators create, modify, and delete roles through the administrator pages, as
described in the JasperReports Server Administrator Guide.

TIBCO Software Inc.

9

TIBCO JasperReports Server Security Guide

JasperReports Server relies on the open source Spring security framework; it has many configurable options for:
•
•
•
•
•
•

External authentication services such as LDAP (used by Microsoft Active Directory and Novell eDirectory)
Single sign-on using JA-SIG's Central Authentication Service (CAS)
Java Authentication and Authorization Service (JAAS)
Container security (Tomcat, Jetty)
SiteMinder
Anonymous user access (disabled by default)

JasperReports Server also supports these encryption and authentication standards:
•
•
•
•

HTTPS, including requiring HTTPS
HTTP Basic
HTTP Digest
X509

The Spring framework is readily extensible to integrate with custom and commercial authentication services and
transports.
Authentication occurs by default through the web user interface, forcing login, and/or through HTTP Basic
authentication for web services, such as Jaspersoft Studio and for XML/A traffic. The server can automatically
synchronize with an external authentication service. External users don’t need to be created manually in the
server first. Both users and roles are created automatically in the server from their definitions in an external
authentication service. For an overview of the authentication system and details about external authentication,
see the JasperReports Server Authentication Cookbook.

2.2

Authorization Overview
With a user’s identity and roles established, JasperReports Server controls the user’s access in these ways:

10

Menu options and
pages

The menus appear in JasperReports Server UI depending on the user’s roles. For
example, only users with the administrator role can see the Manage menu and
access the administrator pages. By modifying the server’s configuration, you can
modify access to menus, menu items, and individual pages. Refer to the
JasperReports Server Source Build Guide and JasperReports Server Ultimate
Guide for more information.

Organization scope

Users belong to organizations and are restricted to resources within their
organizations. Organizations have their own administrators who each see only the
users, roles, and resources of their own organization. When JasperReports Server
is configured with multiple organizations, those organizations are effectively
isolated from each other, although the system admin can share resources through
the Public folder. For more information, see the JasperReports Server Administrator
Guide.

TIBCO Software Inc.

Chapter 2 Overview of JasperReports Server Security

Resource permissions

Administrators can define access permissions on every folder and resource in the
repository. You can define permissions for every role and every user, or leave them
undefined to be inherited from the parent folder. For example, user may have readwrite access to a folder where they create reports, but the administrator can also
create shared reports in the same folder that are set to read-only. The possible
permissions are: no access, execute only, read-only, read-delete, read-write-delete,
and administer (see "Repository Administration" in the JasperReports Server
Administrator Guide).
Permissions are enforced when accessing any resource whether directly through
the repository interface, indirectly when called from a report, or programmatically
through the web services. A user's access to resources is limited by the permissions
defined in the user's roles.

Administrator privileges

JasperReports Server distinguishes between reading or writing a resource in the
repository and viewing or editing the internal definition of a resource. For security
purposes, granting a user read or write permission on a resource does not allow
viewing or editing the resource definition. For example, users need execute or read
permission on a data source to run reports that use it, but they cannot view the data
source’s definition, which includes a database password. Also, only administrators
can interact with theme folders to upload, download, and activate CSS files that
control the UI's appearance.

Data-level security

Data-level security determines the data that can be retrieved and viewed in a report,
based on the username and roles of the user running the report. For example, a
management report could allow any user to see the management hierarchy,
managers would see the salary information for their direct employees, and only
human resource managers would see all salary values.
Data-level security in Domains is explained in the JasperReports Server User
Guide. Data-level security through OLAP views is covered in the Jaspersoft OLAP
User Guide.
Note: This type of security is available only in the commercial edition of
JasperReports Server.

User attributes

User attributes are name-value pairs associated with a user, organization, or server.
User attributes provide additional information about the user and can also be used
to restrict a user's access to data through Domain security files and OLAP schemas.
For information on defining user attributes, see "Editing User Attributes" in the
JasperReports Server Administrator Guide.
User, organization and server attributes can be used to customize the definition of a
data source or as parameters of a report. See "Attributes in Data Source Definitions"
and "Attribute-Based Parameters for Queries and Reports" in the JasperReports
Server Administrator Guide

TIBCO Software Inc.

11

TIBCO JasperReports Server Security Guide

12

TIBCO Software Inc.

CHAPTER 3

APPLICATION SECURITY

This chapter describes the configuration settings that protect JasperReports Server and its users from
unauthorized access. The configuration properties appear in two locations:
•

•

Some properties must be configured during the installation and deployment phase, before users access the
server. These settings are configured through files used by the installation scripts. These settings are
available only when performing a WAR file installation.
Properties you can configure after installation are located in files in various folders. Configuration file paths
are relative to the  directory, which is the root of your JasperReports Server installation. To
change the configuration, edit these files then restart the server.

Because the locations of files described in this chapter vary with your application server, the paths specified in
this chapter are relative to the deployed WAR file for the application. For example, the applicationContext.xml
file is shown as residing in the WEB-INF folder. If you use the Tomcat application server bundled with the
installer, the default path to this location is:
C:\Program Files\jasperreports-server-6.4\apache-tomcat\webapps\jasperserver-pro\WEB-INF
Use caution when editing the properties described in this chapter. Inadvertent changes may cause
unexpected errors throughout JasperReports Server that may be difficult to troubleshoot. Before changing
any files, back them up to a location outside of your JasperReports Server installation.
Do not modify settings not described in the documentation. Even though some settings may appear
straightforward, values other than the default may not work properly and may cause errors.

This chapter contains the following sections:
•
•
•
•
•
•
•
•
•
•
•
•
•

Encrypting Passwords in Configuration Files
Configuring CSRF Protection
Protecting Against SQL Injection
Protecting Against Cross-Site Scripting
Restricting File Uploads
Restricting Groovy's Access
Hiding Stack Trace Messages
Defining a Cross-Domain Policy for Flash
Enabling SSL in Tomcat
Disabling Unused HTTP Verbs
Configuring HTTP Header Options
Setting the Secure Flag on Cookies
Setting httpOnly for Cookies

TIBCO Software Inc.

13

TIBCO JasperReports Server Security Guide

•
•

3.1

Protection Domain Infrastructure in Tomcat
Encrypting Passwords in URLs

Encrypting Passwords in Configuration Files
In JasperReports Server version 5.5 or later, administrators can obfuscate passwords that appear in the
configuration files. This satisfies security audit requirements and prevents the passwords from being seen by
unauthorized individuals. Typically, the following are encrypted:
•
•
•

The password to JasperReports Server's internal database (jasperserver).
The passwords to the sample databases (foodmart and sugarcrm).
On Tomcat, passwords in JNDI resource definitions.

You can change the configuration to also encrypt:
•
•

The password for the mail server used by the scheduler (quartz.mail.sender.password)
The password for LDAP external authentication.

Passwords in configuration files are encrypted during JasperReports Server installation. If the installation
deploys to the Tomcat application server, the database password is also automatically encrypted in the JNDI
configuration (in the file context.xml).
Full password security cannot be guaranteed from within JasperReports Server. A user with sufficient
privileges and knowledge of JasperReports Server can gain access to the encryption keys and the
configuration passwords. While you could require a password on every server restart, this is impractical
for most users. The only practical way to guarantee password security is through backup and restriction
of access to the keystore property file.

3.1.1

Encrypting Configuration Passwords on Tomcat
To encrypt passwords in a Tomcat installation, modify the installation procedure:
1.

Depending on the database you use, copy the installation configuration file as usual:
from: /buildomatic/sample_conf/_master.properties
to: /buildomatic/default_master.properties

2.

Edit the default_master.properties file:
•
•
•

3.

Enter values specific to your installation.
Enter your passwords in plain text.
Turn on configuration file encryption by uncommenting the encrypt=true property. You don't have
to uncomment any other encryption properties because they all have the default values shown.
• Unless you're using Oracle, uncomment propsToEncrypt and set it to dbPassword,sysPassword.
• Optionally, specify additional properties to encrypt as described in 3.1.3, “Encrypting Additional
Properties in default_master.properties,” on page 15.
• Optionally, change the settings for configuration file encryption as described in 3.1.5, “Encryption
Options,” on page 19.
Run the buildomatic installation script (js-install) and all other installation steps according to the
JasperReports Server Installation Guide. This will have the following effects:
a.

14

The plain text passwords in default_master.properties are overwritten with their encrypted equivalents.
There is no warning when you run js-install with encrypt=true.

TIBCO Software Inc.

Chapter 3 Application Security

4.

b.

The encrypted passwords are propagated to all configuration files.

c.

The installation proceeds and copies files to their final locations.

After installation, passwords are encrypted in the following locations:
•
•
•

In all server configuration files in .../WEB-INF/applicationContext*.xml.
In JNDI definitions in .../META-INF/context.xml.
In the default_master.properties files that remain after installation.

If you get an error like the following when restarting the server:
javax.naming.NamingException: KeystoreManager.init was never called or there are errors instantiating an instance

you may need to add the following to your Tomcat service start properties:
-Duser.home=c:\Users\

3.1.2

Encrypting Configuration Passwords on Enterprise Servers
Most enterprise servers, like JBoss, Glassfish, WebSphere, and WebLogic, have proprietary ways to set up
password encryption. You should use these encryption methods. JasperReports Server doesn't automatically set
up encrypted passwords for these servers during deployment. In this case, you can encrypt the passwords in the
buildomatic file after deployment:
1.

Deploy JasperReports Server to your enterprise server as specified in the JasperReports Server Installation
Guide. The resulting JasperReports Server instance will have unencrypted JNDI data source passwords. If
you want to encrypt these passwords, refer to your application server's documentation.

2.

After the server has been successfully configured, encrypt the JasperReports Server configuration files as
follows:
a.

In default_master.properties, turn on encryption by uncommenting encrypt=true.

b.

Run the target js-ant refresh-config. This will remove and recreate all the configuration files
without deploying them to the application server. Now the buildomatic files will have the database
passwords encrypted. You should still be able to execute import/export or other scripts.
Do not run js-install or js-ant deploy-webapp-pro. These commands will overwrite the WAR file
created in step 1 and render the server data sources inaccessible. If you need to redeploy the WAR file,
reset the database password(s) to plain text in your default_master.properties and start again with step 1.

3.1.3

Encrypting Additional Properties in default_master.properties
You can encrypt additional properties in the default_master.properties file. To work correctly, these properties
need to be decrypted when used. Currently decryption is supported for properties loaded into the Spring
application context via the propertyConfigurer bean in applicationContext-webapp.xml.

TIBCO Software Inc.

15

TIBCO JasperReports Server Security Guide

If a property is defined via JNDI, we recommend pointing there instead of encrypting:




The following code sample shows the propertyConfigurer bean in applicationContext-webapp.xml:



/WEB-INF/hibernate.properties
/WEB-INF/js.quartz.properties
/WEB-INF/js.spring.properties
/WEB-INF/js.scheduling.properties
/WEB-INF/mondrian.connect.string.properties
/WEB-INF/js.diagnostic.properties
/WEB-INF/js.aws.datasource.properties
/WEB-INF/js.config.properties
/WEB-INF/js.externalAuth.properties


...

Because we extended Spring's PropertyPlaceholderConfigurer class as DecryptingPropertyPlaceholderConfigurer, all the loaded properties are scanned for the special marker ENC--. If that marker is found around the property value, that property is decrypted before it's loaded into Spring context. To determine if your property is scanned by propertyConfigurer, search the files in propertyConfigurer's locations to see if it's defined in one of these files. For example, suppose you want to encrypt the password property of the reportSchedulerMailSender bean in applicationContext-report-scheduling.xml: false The use of the ${...} syntax tells you that report.scheduler.mail.sender.password is most likely defined via the propertyConfigurer bean. Search through the propertyConfigurer locations to verify. This property is defined in /WEB-INF/js.quartz.properties as follows: report.scheduler.mail.sender.password=${quartz.mail.sender.password}. 16 TIBCO Software Inc. Chapter 3 Application Security Once you've verified that the quartz.mail.sender.password property can be encrypted using defaultmaster.properties, you set up encryption before installation as follows: 1. Set the password for quartz.mail.sender.password in default-master.properties: quartz.mail.sender.password=cleartextpassword 2. Uncomment the encrypt=true property in the same file. 3. Uncomment propsToEncrypt=dbPassword in default-master.properties. 4. Add quartz.mail.sender.password to propsToEncrypt: quartz.mail.sender.password=cleartextpassword ... encrypt=true propsToEncrypt=dbPassword,quartz.mail.sender.password 3.1.4 5. Configure and install your JasperReports Server WAR installation as described in the JasperReports Server Installation Guide. 6. Verify that report.scheduler.mail.sender.password was encrypted in both default-master.properties and in /WEB-INF/js.quartz.properties. Password Encryption for External Authentication As of JasperReports Server 5.6, you can encrypt the passwords in the external authentication configuration files for LDAP and external database authentication. Here we cover only the encryption of these passwords; for details about configuring external authentication, see the JasperReports Server External Authentication Cookbook. To enable encryption during installation, property values in the external authentication sample configuration are referenced from other configuration files. For example, if you're using LDAP to authenticate, the sample configuration file contains the following reference to the LDAP password: The values referenced by the ${...} format are defined in the js.externalAuth.properties file and imported into Spring context via the propertyConfigurer. For example, the LDAP properties are defined in js.externalAuth.properties as follows: external.ldap.url=${external.ldapUrl} external.ldap.username=${external.ldapDn} external.ldap.password=${external.ldapPassword} The ${...} syntax again references other configuration properties that must be set in default_master.properties before installation or upgrade. The following example shows the syntax of the properties in the default_ master.properties file: external.ldapUrl=ldap://hostname:389/dc=example,dc=com external.ldapDn=cn=Administrator,dc=example,dc=com external.ldapPassword=password TIBCO Software Inc. 17 TIBCO JasperReports Server Security Guide To encrypt the password property, set the following values in default_master.properties before installation or upgrade: external.ldapPassword=cleartextpassword ... encrypt=true propsToEncrypt=dbPassword, external.ldapPassword During the installation process, the password value in default_master.properties and its reference in js.externalAuth.properties are overwritten with the encrypted value. If your external authentication is configured to create organizations for external users, and you're using JasperReports Server 6.0, or later, there is another password to encrypt. When external authentication creates an organization, it uses the information in ExternalTenantSetupUser of the externalTenantSetupProcessor bean to create the organization administrator. ROLE_ADMINISTRATOR ROLE_USER The values referenced by the ${...} format are defined in the js.config.properties file as follows: ## New tenant creation: user config new.tenant.user.name.1=jasperadmin new.tenant.user.fullname.1=jasperadmin ... new.tenant.user.password.1=jasperadmin new.tenant.user.email.1= The default values for new tenant (organization) administrators in js.config.properties apply only to external authentication. They do not apply to organizations created by administrators through the UI or REST interface. To encrypt this password, modify the js.config.properties file as follows: new.tenant.user.password.1=${tenant.user.password} Then add the following lines to default_master.properties before installation or upgrade: tenant.user.password=cleartextpassword ... encrypt=true propsToEncrypt=dbPassword, external.ldapPassword, tenant.user.password 18 TIBCO Software Inc. Chapter 3 Application Security During the installation process, the password value in default_master.properties and its reference in js.config.properties are overwritten with the encrypted value. 3.1.5 Encryption Options In buildomatic installation scripts, the passwords are symmetrically encrypted: the same secret key is used for both encryption and decryption. The key and its containing keystore file are randomly generated on each machine during the first JasperReports Server installation. All subsequent JasperReports Server installations on the same server rely on the same keystore; they don't regenerate the key. The keystore is an encrypted file used to securely store secret keys. JasperReports Server uses keystore properties to access the keystore. Both the keystore and keystore properties files are created by default in the user home directory. Alternatively, before running js-install, you can specify different locations for the keystore and keystore properties files via the environmental variables ks and ksp. By default, database passwords are encrypted with the AES-128 algorithm in Cipher Block Chaining mode with PKCS5 padding. The AES algorithm is the current industry encryption standard. You can choose to modify the encryption strength by choosing either a different algorithm, a longer secret key size (for example AES-256), or a different encryption mode. Edit the following properties in your default_master.properties and set these options. If a property is commented out, the default is used: Property Description Default build.key.algo Algorithm used to encrypt the properties in configuration files. AES build.key.size Size of the encryption key as in AES-128. 128 (bits) To increase the key size, if it has not been done before, you might have to install "Unlimited Strength Jurisdiction Policy Files" from the Oracle site for your Java version. To install the files, download US_export_ policy.jar and local_policy.jar. AFTER backing up the old files, extract the jars into %JAVA_HOME%/jre/lib/security directory. Alternatively, you may download one of the reputable providers such as Bouncy Castle (ships with JasperReports Server). You would need to add the Bouncy Castle provider to the list in %JAVA_HOME%/jre/lib/security/java.security file: security.provider.= org.bouncycastle.jce.provider.BouncyCastleProvider enc.transformation So-called encryption mode. See Java's javax.crypto documentation to understand the modes and padding better. AES/CBC /PKCS5 Padding enc.block.size The size of the block that's encrypted. Encrypted text can contain many blocks. Usually the block is changed together with the encryption algorithm. 16 (bytes) propsToEncrypt A comma separated list of the properties to encrypt. dbPassword TIBCO Software Inc. 19 TIBCO JasperReports Server Security Guide 3.2 Configuring CSRF Protection 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. 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 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 .../WEB-INF/csrf/jrs.csrfguard.properties Property Value Description org.owasp.csrfguard.Enabled true false 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. 3.2.1 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. 20 TIBCO Software Inc. Chapter 3 Application Security 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 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. Attribute Value Description 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 example.com 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. (see below) domainWhitelist at server level domainWhitelist at org1 level example1.com domainWhitelist at user2 level example2.com ... ... (see below) TIBCO Software Inc. 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. 21 TIBCO JasperReports Server Security Guide Cross-Domain Whitelist domainWhitelist1 domainWhitelist2 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:80\d0 which is translated to ^http://.*\.myexample\.com:80\d0$ 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. 3.2.2 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 plugins 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 22 TIBCO Software Inc. Chapter 3 Application Security 3.2.3 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/ 3.3 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. Protecting Against SQL Injection SQL injection is an attack that uses malicious SQL queries in reports to gain access or do damage to your databases. By default, JasperReports Server validates query strings to protect against SQL injection. If you want to allow special queries such as stored procedures, you can modify the default settings. Whenever the server runs an SQL query, the server validates the query string with the following rules: • • • SQL queries must start with SELECT. Comments in queries are not allowed. Multiple queries separated by semi-colons (;) are also prohibited. If your reports or Domains use such queries, you need to either change your queries or update the security configuration to allow them. Users who run a report with a query that does not meet the rules will see an error. Administrators can monitor the server logs to search for evidence of attempted security breaches. SQL query validation is enabled by default when installing JasperReports Server. To turn off this protection, edit the following file: TIBCO Software Inc. 23 TIBCO JasperReports Server Security Guide SQL Query Validation Configuration File .../WEB-INF/classes/esapi/security-config.properties Property Value Description security.validation.sql.on true Turns SQL query validation on or off in the server. Any other value besides caseinsensitive “false” is equivalent to true. SQL query validation rules were added to comply with security guidelines for web applications. Turning off query validation or modifying the validation rules may make the server more vulnerable to web attacks. 3.3.1 Customizing the Error Message When query validation blocks a query that violates a security rule, the server displays an error in the UI. By default, security messages are intentionally generic to avoid alerting potential attackers to security errors. We highly recommend that external deployments customize the security error message to be unique, yet still generic. You can change both the message and the error number. Choose any combination of numbers or letters so administrators can easily search the logs to detect security violations. Query Validation Messages Configuration File .../WEB-INF/bundles/security.properties Property Value message.validation.sql An error has occurred. Please contact your system administrator. (6632) If you translate your application into other languages, be sure to create a locale-specific copy of this file and translate these messages as well. 3.3.2 Understanding Query Validation Query validation uses the same mechanism as input validation, but the query executor process performs the validation before running every query. The validation process is defined by a validation rule that references a validator expression. The rule and the expression are defined in separate files. 24 TIBCO Software Inc. Chapter 3 Application Security Query Validation Rule Configuration File .../WEB-INF/classes/esapi/security.properties Property Value sqlQueryExecutor Alpha,ValidSQL,500000,true,SQL_Query_Executor_context The validation rule contains 5 comma-separated values: • • • • • Alpha – Not used for query validation. ValidSQL – The name of the SQL validator expression in the other file. 500000 – The maximum length allowed for the query. true – Whether the query can be blank. SQL_Query_Executor_context – Context string for log messages. SQL Validator Expression Configuration File .../WEB-INF/classes/esapi/validation.properties Property Value Validator.ValidSQL ^\\s*((?i)select)\\s+[^;]+$ The validator expression is a regular expression that must match the query string. By default, this expression enforces the following: • Queries may only use the SELECT statement, which is read-only. The following write statements are forbidden: DROP, INSERT, UPDATE, DELETE • • SQL comments are forbidden. Multiple queries separated by semi-colons (;) will be rejected. The following example will cause a security error: SELECT f1,f2 FROM tbl_1; SELECT f3 from tbl_2; Do not modify the default SQL validator expression provided with the server. We have thoroughly tested this expression to provide reasonable query validation security while allowing for the general use of the application. If you wish to use a different validator expression for queries, always create a new validator expressions with a new name. For more details about the validation mechanism, see 3.4, “Protecting Against Cross-Site Scripting,” on page 27. TIBCO Software Inc. 25 TIBCO JasperReports Server Security Guide 3.3.3 Adding Validation for Stored Procedures If you want to use stored procedures as your queries, the default query validation rule above will not allow them. You must add a custom validator expression to the validation.properties file. To allow stored procedures in addition to SQL queries: 1. Make a backup copy of the file /WEB-INF/classes/esapi/security.properties, then open it for editing. 2. Add the second validation rule for queries, as shown in the following table: Stored Procedure Rule Configuration File .../WEB-INF/classes/esapi/security.properties Property Value sqlQueryExecutor Alpha,ValidSQL,500000,true,SQL_Query_Executor_context sqlQueryExecutor2 Alpha,ValidPROC,500000,true,SQL_SProc_Executor_context 3. Make a backup copy of the file /WEB-INF/classes/esapi/validation.properties, then open it for editing. 4. Add the validator expression for procedures, as shown in the following table: Stored Procedure Expression Configuration File .../WEB-INF/classes/esapi/validation.properties Property Value Validator.ValidSQL ^\\s*((?i)select)\\s+[^;]+$ Validator.ValidPROC ^\\s*\\(((?i)call)\\s+[^;]+\\)$ 5. Save the files, and restart the server or redeploy its web application. With multiple rules for query validation, each rule is applied in the order listed until one passes (equivalent to a logical OR). The rules that fail still appear as security warnings in the logs. This means that every time a stored procedure is validated, the rule with the ValidSQL expression will fail first and appear as a false-positive in the logs. 26 TIBCO Software Inc. Chapter 3 Application Security 3.4 Protecting Against Cross-Site Scripting Cross-site scripting (XSS) is a security threat where attackers submit malicious code in fields of the UI, such as a resource description, so that the code is executed when the field is displayed again. As of JasperReports Server 6.1, all output in the UI is escaped so that no malicious code can run. For example, if an attacker inserts the