Jasperreportsserver Auth Cookbook
Jasperreportsserver Auth Cookbook
Authentication Cookbook
Software Release 8.0
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO
SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED
TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO
SOFTWARE OR FOR ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT
FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE
AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF
THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT
OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF
THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF
AND AN AGREEMENT TO BE BOUND BY THE SAME.
ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDER SEPARATE SOFTWARE LICENSE TERMS AND
IS NOT PART OF A TIBCO PRODUCT. AS SUCH, THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR
AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES, AND INDEMNITIES.
DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWN DISCRETION AND SUBJECT TO THE LICENSE TERMS
APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE
FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.
This document is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the
written authorization of TIBCO Software Inc.
TIBCO, the TIBCO logo, Jaspersoft, JasperReports, and Visualize.js are registered trademarks of TIBCO Software Inc. in the United States and/or other
countries.
Java and all Java based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for
identification purposes only.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY
ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO
SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER
DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ
ME" FILES.
This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer to TIBCO's Virtual Patent Marking document
(https://www.tibco.com/patents) for details.
Copyright © 2005-2021. TIBCO Software Inc. All Rights Reserved.
Index 121
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.
• 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 and through email at
http://support.tibco.com and [email protected].
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.
This chapter contains the following sections:
• JasperReports Server Version Supported
• Spring Security
• Terminology
JasperReports Server currently uses Spring Security 4.2. If you are upgrading from an earlier version of
JasperReports Server, you may need to migrate your configuration files. See the TIBCO JasperReports
Server External Authentication Cookbook, available from the support portal or the community website.
JasperReports Server relies on Spring Security 4.2 to provide the mechanisms that authenticate and authorize
users. If you plan to make extensive customizations, we recommend that you delve more deeply into Spring
Security by visiting its project pages and participating in its community. For more information, see the Spring
Security website Spring Security website and refer to the documentation for Spring Security 4.2:
https://docs.spring.io/spring-security/site/docs/4.2.4.RELEASE/reference/htmlsingle/
1.3 Terminology
This guide uses the following terms in very specific ways.
• Users – JasperReports Server users are either people who access the web-based interface or applications that
access the same content through web services. Authentication is slightly different for each type of access
but operates on the same principles. For simplicity, this guide considers users to be people accessing the
web-based interface.
• Internal database – User accounts are created by administrators and stored in a private, internal database. For
example, when you install JasperReports Server with the default settings, it requires a PostgreSQL database
server where it stores the internal database tables containing user information. The internal database is
independent of databases that store your operational data, although it may be on the same database server.
• Authentication – Authentication is the verification of a user’s identity to allow access to JasperReports
Server. By default, anonymous access is disabled, and all users must present valid credentials to log in: a
user ID, a password, and in certain cases an organization ID. Authentication is more than gathering the user
credentials, it's a process that ensures that every page is secure — either displayed to a verified user or
denied until valid credentials are provided.
• External authentication – External authentication is the process of gathering and verifying user credentials
through a third-party application, for example, a corporate LDAP directory. The external application is
called an authority because it's trusted to contain valid user information. The process of external
authentication depends on the nature of the external authority, and the various configurations support
different use scenarios. For example, with simple external authentication, users log into the JasperReports
Server page, but their credentials are verified externally; in a single sign-on configuration, the user may log
into another application, then navigate to JasperReports Server without seeing the server’s login page.
• Principal object – Authentication happens only once at the beginning of the user’s session. After
authentication, the user’s session is represented by an in-memory instance referred to as the principal object.
The existence of the principal object determines that the user is logged on and can access pages throughout
the application. The principal object also stores the user's roles and organization ID, which are required for
authorization within JasperReports Server.
• Authorization – Authorization is the verification of a user’s roles and organization ID to access features of
the server, resources in the repository, and, in some cases, data. For every page the user requests, the server
determines which menu items, resources, and report contents the user can access, based on the principal
object. Authorization happens every time a user accesses a resource.
In the JasperReports Server architecture, which is based on the Spring Framework and Spring Security,
authentication may be configured through an external authority, but authorization is always performed by
internal mechanisms. Part of configuring external authentication is to define a mapping of external roles and
organization IDs into the principal object so authorization can proceed internally. Profile attributes can also
be mapped from the external authority; however, you need to write a custom processor to do so. See
“Creating a Custom Processor” on page 104.
• Synchronization – When an external session is established, the user's current organization and roles are
mapped into the principal object. The first time an external user logs in, the synchronization mechanism
creates the user's organization folder, roles and user account in the internal database. The server uses these
structures to enforce authorization for the external user just as for internally-defined users. The
synchronization mechanism updates the roles every time the external user logs in, so that the internal
database reflects the contents of the external authority.
The procedures in this guide assume you're familiar with JasperReports Server installation, deployment,
and administration. You must have system administrator privileges within JasperReports Server and its
application server and read and write access to their files on the host.
If you're setting up external authentication, you may need to understand how JasperReports Server performs
internal authentication, or how external roles and organizations in JasperReports Server are created when
external authorization has been set up. This chapter gives background information that can help you configure
external authentication correctly.
This chapter contains the following sections:
• Locating and Working With Sample Files
• Default Internal Authentication
• Organizations and Users in JasperReports Server
Installed server Once you've installed your server, either through a platform installer or any other
deployment, the configuration files are deployed in the application server. The location
depends on the application server where you installed JasperReports Server. If you used the
bundled Apache Tomcat application server, the modified configuration files should be placed
in:
<js-webapp>/WEB-INF = <js-install>/apache-tomcat/webapps/jasperserver[-pro]/WEB-INF
After modifying the configuration files, restart the application server to use the settings.
WAR file When you download the WAR file distribution, you can customize your deployment of
distribution JasperReports Server and possibly install it on several machines. You can find the WAR file
in the following location:
<js-webapp> = <js-install>/jasperserver[-pro].war
After modifying the WAR file distribution, you need to redeploy it to your application server,
as described in the TIBCO JasperReports Server Installation Guide. But every time you
redeploy your modified WAR file, external authentication is pre-configured.
Source code The JasperReports Server source code contains the XML source of the configuration files. If
you maintain other customizations in the source code, you can modify the configuration files
for external authentication. The modified configuration files for source code are placed in:
<js-webapp>/WEB-INF = <js-src>/jasperserver/jasperserver-war/src/main/webapp/WEB-INF
When building the source, these files are copied into the WAR file that you must then deploy
into a running application server. See the TIBCO JasperReports Server Source Build Guide
for more information.
When working with the WAR file distribution or source code, you usually modify the files in an
installed server for testing. But after testing, you copy the changes into your WAR file or source code.
When working with the WAR file distribution or servers installed in application servers other than Apache
Tomcat, the WAR file is kept as a single archive file from which you must extract, modify and replace the files.
The following code sample shows one way to do this from the command line.
cd <js-webapp>
"%JAVA_HOME%\bin\jar" xf jasperserver[-pro].war <path/filename>
<edit> <path\filename>
"%JAVA_HOME%\bin\jar" uf jasperserver[-pro].war <path/filename>
delete <path\filename>
In this sample:
• <path/filename> refers to the relative path and name of the file to modify within the WAR file
• -pro is part of the WAR file name if you installed a commercial edition of JasperReports Server.
For example:
You must restart the server for your changes to take effect. For more information about log configuration, see the
TIBCO JasperReports Server Administrator Guide.
You can reduce impact on performance by restricting logging to functionality that you are interested in, for
example, to a subset of Spring Security instead of all of Spring Security. Table 2-1 shows some logger
classnames commonly used when debugging authentication.
CAS org.jasig.cas
JasperReports com.jaspersoft.jasperserver.multipleTenancy.security.externalAuth
Server external
authentication API
Enabling a logger and a sublogger together creates duplicate entries in the logs. For example,
org.springframework.security and org.springframework.security.ldap creates duplicate
entries.
The interaction between the user’s browser and JasperReports Server includes these general steps:
1. An unauthenticated user requests any page in JasperReports Server.
Often, users bookmark the login page and begin directly at step 3, but this step covers the general case and
secures every possible access to the server. For example, this step applies when a user clicks the page of an
expired session or if a user enters the direct URL to a report in the repository.
2. JasperReports Server detects that the user is not logged in and replies with a redirect to the login page.
For convenience, the server includes the original URL in the login screen request so that the user goes
directly to the requested page after logging in.
3. The user enters a username, password, and possibly an organization ID.
JasperReports Server compares these credentials with the existing user accounts in the internal user
database, and if they are valid, creates a principal object. The user is now authenticated, and the principal
object represents the user session, including any roles found in the user database.
4. JasperReports Server sends the requested content to the user, or if none was specified, the home page.
Content that is sent to the user is subject to authorization. For example the home page has different options
for administrators than for end-users, as determined by the roles of the user in the principal object. If the
user is viewing the repository, the folders and objects returned depend on the organization ID and roles in
the principal object.
organization, the server creates a local user account, role definitions, and organization folders. This process is
called synchronization.
The users and roles defined through external authentication appear in the management interface, but are labeled
as “external.” Administrators can view and delete the external users and roles, but the synchronization will re-
create the necessary users and roles as long as external authentication is configured. External user accounts and
roles are placeholders for use by the synchronization and permissions mechanisms. Administrators can disable
specific external users in JasperReports Server to prevent those external users from logging into JasperReports
Server.
There are three important aspects to managing external users, roles, and organizations:
• The synchronization of external users, roles, and organizations with the internal database is automatic once
external authentication is configured. This is done by the ExternalDataSynchronizer bean. For more
information, see “Advanced Topics” on page 101.
• Permissions in the repository must be initialized manually for the external roles after their creation.
• Maintenance of the external users is necessary only when creating or deleting roles, when creating new
organizations from an external authority, or when disabling external users in JasperReports Server.
When you deploy JasperReports Server in a production environment, you need to set up role permissions before
your users access the server. However, you cannot create external roles or organizations directly; you can create
them only by logging in as an external user with the desired roles and permissions. To set up role permissions,
you must understand the synchronization process. For maintenance, you must be aware of how changes in the
external authority impact permissions in JasperReports Server. These processes are explained in the following
sections.
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.
Some commercial editions allow several distinct organizations to coexist within the same server instance. Each
organization, also known as a tenant, has its own users, roles, and possibly a hierarchy of sub-organizations,
each of which is invisible to other organizations. For information about deploying multiple organizations, see
the TIBCO JasperReports Server Administrator Guide.
When you deploy JasperReports Server, there are three distinct cases with respect to the organization
architecture:
Commercial edition Configuring external authentication for multiple organizations requires extra steps.
with multiple In the chapter for each authentication mechanism, look for the additional section on
organizations mapping the organization. All other configurations for external authentication remain
the same.
Commercial edition When JasperReports Server has the organization architecture, but only implements
with no organizations a single default organization, the organization ID is mapped automatically. You can
skip any section that refers to mapping the organization ID.
Community Project JasperReports Server Community Project does not use the organization
architecture. You can skip any section that refers to mapping the organization ID.
Another name for multiple organizations is multi-tenancy, sometimes abbreviated mt in file and bean
names. However, the mt prefix appears in both community and commercial editions.
Default admins for new organizations can be customized only when using external authentication. When
you create organizations manually, the jasperadmin user is created.
• If the user ID does not match an account in the internal database, an external user account is created. If
an organization ID is specified, the account is created within that organization. Finally, all of the
external roles along with any configurable default internal roles are assigned to the new user account.
For more information about organizations, roles, and user accounts see the TIBCO JasperReports Server
Administrator Guide.
A user account created for an external user has the same structure as an internal user account but differs in the
following ways:
• A database flag marks it as externally defined.
• The full name of the user is the same as the user ID, which is always the same as the login name entered by
the user.
• The external user account does not store the password.
• It does not have any values for optional user properties, such as the user's email or profile attributes. The
default implementation of external authentication does not include these properties. An administrator can
manually include these properties.
An external authority such as LDAP contains information like the user’s full name, email address, and
profile attributes, which can be mapped into the external user account. However, this requires
customizing the mapping and synchronization beans. See Chapter 7, “Advanced Topics,” on
page 101.
After synchronization, the external user fits in cohesively with all the structures and mechanisms of
JasperReports Server, especially those required for authorization. But the JasperReports Server administrator's
management of an external account is limited to the ability to disable the account and prevent the external user
from logging in.
An external user cannot log in when the external authority is offline; external accounts do not store the
password and are not meant for failover. Once external authentication is configured, only the information in the
external authority determines who can log in and what roles they have. However, administrators may view
external organizations, users, and roles to determine if all mappings from the external authority are correct.
In the first phase of synchronization, the principal object has a set of role names derived from role definitions in
the external authority. The goal is a JasperReports Server role for each of the mapped role names.
• If you're using organizations, all target roles are created within the user's mapped organization.
• If a role with the target name is already defined in JasperReports Server, that role is assigned to the user.
Otherwise a new external role with this name is created and assigned.
• By default, roles are mapped to external roles, even if an internal role has the same name. If an external role
name conflicts with an existing internal role in the target organization, a suffix like _EXT is added to the
role name.
• You must explicitly map external roles to internal roles. If you're mapping a role to an internal role, you can
specify whether to assign the internal role at the organization level or at the system (root) level. Roles
mapped at the organization level have no administrative privileges. Roles at the system administrative
privileges and access to the repositories of all organizations. To map to an internal role at the organization
level, append |* to the name of the internal role. To map to an internal role at the system level, do not
modify the internal role name.
The goal of the second phase of synchronization is to update the user with the set of roles mapped from the
external authority. The origin of a role determines how the synchronizer assigns and removes the role from an
external user account:
• All of roles identified or created in the first phase — internal, external, and system — are assigned to the
external user. Any role not yet in the user's account, is assigned by the synchronization process.
• External roles that are assigned to the user — but not among those mapped and identified in the first phase
— are removed from the user. This way, roles removed from the external authority are also removed from
the user's JasperReports Server account.
• Internal and system roles created by synchronization during a previous login — but no longer mapped and
identified from the external authority — are removed from the user. If an internal role that was assigned or
removed by an administrator appears in the mapping configuration, the mapping from the external role takes
precedence. This means that a manually assigned role may be added or removed based on the state of the
external database. Therefore, to ensure that synchronization automatically makes all roles reflect those in the
external authority, you should not manually assign internal roles.
Action in External
Impact on JasperReports Server
Authority
Creating a new user JasperReports Server automatically creates the new external user account when the
user first accesses the server. As long as the user relies on existing roles in an
existing organization, no server changes are required. If the user is associated with
new roles, see 2.4.5.2, “Managing External Role Definitions,” on page 21.
Updating a password JasperReports Server doesn't store the passwords of external users, and is not
affected by changes to user passwords or policies on the external authority.
Updating personal With the default mapping of external users, only the login name is stored in an
information external user account. If you configure role mapping based on personal information in
the external user entry, you need to account for any possible change in the content or
structure of the external authority. For example, if a role is based on a user’s
department attribute, make sure the user can't modify this attribute in the external
authority. Otherwise, the user could inadvertently or maliciously change his or her
roles within JasperReports Server.
Changing When organizations represent departments within a company, a user may change
organization organizations, as mapped from the external authority. From JasperReports Server’s
membership point of view, this is the same as deleting a user in the old organization and creating a
user in another organization.
Disabling or deleting When the user can no longer authenticate with the external authority, he can’t access
a user JasperReports Server. Even though the external user account remains in the internal
database, it can't be used for logging in. The defunct user account has no impact on
the server; you can safely delete it.
An external user can be disabled in JasperReports Server.
The following table describes the impact on JasperReports Server when modifying role definitions in the
external authority:
Action in External
Impact on JasperReports Server
Authority
Creating a new role Role definitions are not directly mapped to JasperReports Server; only roles that are
assigned to users who log in are mapped. When you create a new role and assign it
to a user who accesses JasperReports Server, determine which case applies:
• The role is significant to access control within JasperReports Server. You must
initialize this role in the server with a test user and define all necessary repository
authorization rules to secure your data before you deploy this role to real users, as
described in 2.4.3, “Synchronization of Roles,” on page 18.
• The role is not significant to users within JasperReports Server. Synchronization
automatically creates the role and assigns it to users according to their mapping,
but with no authorization rules based on the role, it has no impact.
Modifying role Changes in role membership are reflected the next time a role member starts a new
membership session in JasperReports Server, as described in 2.4.2, “Synchronization of
External Users,” on page 17. Roles that were previously unknown to the server are
treated as new roles as described above, and roles that are no longer assigned to a
user are deleted as described below.
Deleting a role External users no longer have the role, and it is removed from each external user by
synchronization upon the next login. The role remains in the internal database, and
permissions that reference the role remain in the repository. The role may still be
assigned to external users who have not logged in since the role was removed.
• If the role definition in the external authority was mapped to an external role in
JasperReports Server, it has no impact on the server and you can safely delete it.
• If the role definition is mapped to an internally defined role in JasperReports
Server, you can delete the role or modify the configuration file to remove the
mapping. If you remove the mapping, the internal role can be assigned manually
by an administrator. If you do not modify the configuration file and you attempt to
assign the internal role manually to a user in JasperReports Server, the role is
automatically removed during synchronization.
When you want to change the target role for an existing role mapping, you should create a dummy
mapping that maps a non-existent role definition to the JasperReports Server role you no longer want to
use.
For example, suppose you have Sales Manager as a role in your external authority, and you initially map it to
ROLE_ADMINISTRATOR in JasperReports Server.
Sales Manager Mandy logs into JasperReports Server and is assigned ROLE_ADMINISTRATOR.
You then create a new role in JasperReports Server, ROLE_SALES_MANAGER, and modify your role mapping
so Sales Manager in the external authority is now mapped to ROLE_SALES_MANAGER in JasperReports
Server. You then restart the server.
By default, the next time Mandy logs in, she's assigned ROLE_SALES_MANAGER. But because ROLE_
ADMINISTRATOR no longer appears in your application context file, synchronization doesn't check for it and
remove it. Mandy now has two roles: ROLE_ADMINISTRATOR and ROLE_SALES_MANAGER.
You can remove ROLE_ADMINISTRATOR from Mandy's account by creating a dummy mapping with ROLE_
ADMINISTRATOR as the target. For example, if no one in your external authority has the role definition No
Such Role, you can add a mapping in your application context file from No Such Role to ROLE_
ADMINISTRATOR then restart the server. The next time Mandy logs in, the synchronizer finds that she doesn't
have the No Such Role role definition and removes ROLE_ADMINISTRATOR.
It is possible for a role in JasperReports Server to be the target of more than one role mapping. If
multiple role definitions map to the same role in JasperReports Server, users who have any one of
the role definitions will receive the role in JasperReports Server.
Action in External
Impact on JasperReports Server
Authority
Adding an Organizations are not directly mapped to JasperReports Server, rather a new
organization organization ID is mapped when synchronizing the first user in the organization that
accesses the server. At that time, synchronization creates the organization and the
user within it, along with any roles assigned to the user. Determine which of the
following cases applies:
• Your organization definitions and mappings create the same role names in every
organization. You should configure the organization folder templates so the
default contents and permissions work with the known role names. Your external
organization definitions should then map to organizations that work as soon as
the first user logs in.
• Each of your externally defined organizations has different role names or requires
specific repository contents. You should create test users in the new organizations
first, so you can configure the new organization folder, synchronize external roles,
and assign repository permissions before actual users have access. See the
procedure in “Initialization of JasperReports Server for External Users” on
page 19.
Action in External
Impact on JasperReports Server
Authority
Modifying an Changing the users or roles in organizations defined in the external authority is the
organization same as adding users or roles to one organization and removing them from the other.
See the corresponding actions in 2.4.5.1, “Managing External Users,” on page 21
and 2.4.5.2, “Managing External Role Definitions,” on page 21.
Deleting an Because organization definitions are not mapped directly, deleting an organization
organization has the same effect as removing each of its users. The organization remains in the
internal database and repository, along with the external roles and users who last
accessed it. The unused organization has no impact on the server. You can safely
delete it.
Changing the default Default admin users are created only when the organization is created. Therefore,
admin users of organ- changes to the default admin users appear only in organizations created after the
izations changes were made. In particular, if you add or delete default admin users, your
changes affect only new organizations.
The following diagram shows the general steps involved in external LDAP authentication:
The following process explains the interaction of the user’s browser, JasperReports Server, and the LDAP server:
1. An unauthenticated user requests any page in JasperReports Server.
Often, users bookmark the login page and begin directly at step 3, but this step covers the general case and
secures every possible access to the server. For example, this step applies when a user clicks the web
interface of an expired session or if a user is given the direct URL to a report within the server.
2. JasperReports Server detects that the user is not logged in and redirects to the JasperReports Server login
page.
3. The user submits a username and password through the login page, even though the user credentials are not
verified internally.
In servers with multiple organizations, the organization ID must be left blank because it is supplied by the
external LDAP authority, except in the case of an internal login (such as an administrator), then the
organization ID must be provided.
4. JasperReports Server performs a search on the LDAP server with the given credentials. If they are valid, the
server creates a principal object to represent the user’s session in memory. In multi-organization
environments, the user’s organization ID is mapped from the LDAP entry. The server also performs a second
search to map the user’s LDAP groups to server roles.
The beans that perform LDAP authentication do not map information like the user’s full name, email
address, or profile attributes that may exist in the LDAP directory. This requires customizing the
JSFilterBasedLdapUserSearch bean, as described in Chapter 7, “Advanced Topics,” on
page 101.
The username, roles, and organization information are also synchronized with the internal database, where
the user account is marked as an external user. The user is now authenticated, the principal object represents
the user session, and the JasperReports Server environment reflects the user’s roles and organization defined
in LDAP. For more information about synchronization, see “Synchronization of External Users” on
page 17.
5. As with the default internal authorization, JasperReports Server now sends the requested content to the user
or, if none was specified, the home page appropriate for the user.
Content sent to the user is subject to authorization. For example the home page has different options for
administrators than for regular users, as determined by the roles of the user in the principal object. Or if the
user is viewing the repository, the folders and objects returned are determined by the organization ID and
roles in the principal object.
When comparing these steps with those in 2.3, “Default Internal Authentication,” on page 15, there are three
significant differences, all in step 3:
• JasperReports Server verifies the credentials through LDAP instead of using its internal user database.
• The roles and organization ID in the user’s principal object are mapped from the LDAP response.
• The internal database must be synchronized with any new information in the user’s principal object.
<js-webapp> is the location of the JasperReports Server web application in your application server, or
where you're modifying the configuration files, as explained in . The rest of this chapter refers to file
names alone.
<bean id="ldapContextSource"
class="com.jaspersoft.jasperserver.api.security.externalAuth.ldap.JSLdapContextSource">
<constructor-arg value="${external.ldap.url}" />
<property name="userDn" value="${external.ldap.username}" />
<property name="password" value="${external.ldap.password}"/>
</bean>
external.ldapUrl=ldap://hostname:389/dc=example,dc=com
external.ldapDn=cn=Administrator,dc=example,dc=com
external.ldapPassword=password
encrypt=true
propsToEncrypt=dbPassword,external.ldapPassword
See the TIBCO JasperReports Server Security Guide for more information on encrypting passwords using
buildomatic.
If you configured your LDAP connection during JasperReports Server installation or upgrade, do not set
the parameters using ldapContextSource. You can verify whether the parameters are set by looking at
the default_master.properties file.
If your LDAP server is configured to allow anonymous user lookup, you don't need to specify the
userDn and password properties.
Here's an example shows the syntax of the bean’s constructor and properties when manually configured:
<bean id="ldapContextSource"
class="com.jaspersoft.jasperserver.api.security.externalAuth.ldap.JSLdapContextSource">
<constructor-arg value="ldap://hostname:389/dc=example,dc=com" />
<property name="userDn"><value>cn=Administrator,dc=example,dc=com</value></property>
<property name="password"><value>password</value></property>
</bean>
Each time a user logs in, their roles and status are updated via your chosen method and synchronized
with the internal jasperserver database. If you want to disable an external user or modify their external
roles, you must do so in your LDAP directory.
Matching patterns is faster because it checks for a DN only in the LDAP directory, instead of a
searching all users. However, it's less flexible. userDnPatterns is not included in the sample files
by default.
• Configure the userSearch helper bean to perform a search for the login name provided by the user. Use
this method if the login name is the value of an attribute that doesn't appear in the RDN, or if your user
entries are located in a more complex structure. See 3.5.4, “Specifying userSearch Parameters,” on
page 33 for more information.
You can configure pattern matching and login name search at the same time. Patterns are matched first, and
login name search is done only if no match is found.
To find a user, JSBindAuthenticator takes the login name entered into JasperReports Server and attempts to
find the correct user in the LDAP directory using bind authentication, as follows:
1. Using the specified pattern matching or search for the login name, find a candidate user entry.
The LDAP username for this candidate does not have to be the JasperReports Server login name. If
they are different, the user in JasperReports Server is assigned the login name given during the login
process, and not the LDAP username.
2. Attempt to log into the LDAP server using the candidate LDAP username with the login password.
3. A successful bind indicates that the right user was found.
When you enter a pattern for RDN matching, make sure to use only the relative DN. Do not include the
base DN that you set up when creating the LDAP connection parameters.
In the example below, JasperReports Server looks for a user whose given login name appears in the uid
attribute of the RDN in the ou=users branch of the LDAP directory:
Notice that the domain name value only specifies ou=users. This is combined with the base DN defined by the
external.ldapUrl property in the default_master.properties file or the constructor-arg value in the
ldapContextSource bean to create the full DN.
When you enter a location for user search, make sure to use only the relative DN. Do not include the
base DN that you set up when creating the LDAP connection parameters.
The following example shows the syntax of the bean’s constructor and property:
The combination of these three parameters lets you optimize the search for your user entries and reduce the load
on your LDAP directory. For example, if your users are located in a dedicated branch of your LDAP structure,
specify it in the first constructor argument to avoid searching the entire tree.
<property name="userDnPatterns"><list>
<value>uid={0},ou=users,o=Finance</value>
<value>uid={0},ou=users,o=HR</value>
<value>uid={0},ou=users,o=Executive</value></list>
</property>
But if you have a large number of organizations, or if the number or names of organizations can change,
you need to search for every potential user. Depending on your LDAP structure, you may be able to specify
a search base in constructor-arg index="0"; the example below doesn't have one.
2. You cannot implement external authentication for two users with the same login name in different
organizations. LDAP supports this as long as the two users have distinct DNs, and JasperReports Server
supports this for the default internal authentication. But during external authentication, organization
mapping happens after user search, so the user search must return a single LDAP entry:
• Pattern matching stops at the first match based on the login name. As a result, only the user whose
LDAP entry pattern is listed higher in the list can log in.
• Search returns more than one entry. As a result, login fails for both users with the same login name.
location of the group definitions in LDAP, how to find the user's groups, and any transformation of the group
name for use in the server as a role name.
Some LDAP servers support other user-grouping mechanisms, like nsrole in the Sun Directory Server.
These can be mapped into JasperReports Server roles through the configuration parameters below, by
extending the JSDefaultLdapAuthoritiesPopulator class, or a combination of both. Such
configurations are beyond the scope of this guide.
All internal and external users are assigned ROLE_USER by default. So you never need to create or map
this role in your LDAP directory.
The following shows an example syntax of the constructor arguments and properties that uses
groupofuniquenames:
Be careful when defining the properties for mapping user roles. The search for groups in the LDAP directory
must not cause an error, otherwise the entire login will fail. For example, if you specify a branch DN that
doesn't exist, the search will cause an error, and users will be unable to log in. A successful search that returns
no results will allow users to log in, but without having the intended roles.
After the mapping has determined the role names given to the external user in JasperReports Server:
• In the community edition, which doesn't have the organization architecture, the roles are synchronized with
existing roles and assigned to the user.
• In commercial editions, which have the organization architecture, the external user and roles are assigned to
an organization that's either the default single organization or an organization mapped from the DN of the
LDAP user. Organization mapping is described in 3.7, “Mapping the User Organization,” on page 40.
If you intend for one of the mapped roles to provide administrator privileges, you must explicitly map it to
the system roles, as described in 3.6.2, “Mapping Roles to System Roles,” on page 36. Otherwise, all
mapped roles are created in the mapped organization.
Synchronization creates roles in JasperReports Server if they don’t exist, as described in 2.4.3,
“Synchronization of Roles,” on page 18.
Administrators of your LDAP server cannot log into JasperReports Server using their LDAP administrator
credentials.
In most LDAP servers, users and administrators are stored in different base DNs. For example, you might
store user entries in dc=example,dc=com, but administrators are stored under
cn=Administrators,cn=config or ou=system. The mechanism for locating users during authentication can
only search in a single base DN, so administrators in a different one cannot be found.
3.6.2.1 organizationRoleMap
System and organization admin privileges are determined by the ROLE_SUPERUSER and ROLE_ADMINISTRATOR
system roles at the root level. Using the organizationRoleMap property, you can assign these system roles to
LDAP entries based on custom group membership. This property can be used in addition to the properties that
map group names to organization roles.
Whether you map users and roles to a single organization or multiple organizations, you can define this
additional mapping between any role name that your mapping creates and any system role. You specify role
mapping via the organizationRoleMap property of the mtExternalUserSetupProcessor bean (commercial
editions) or externalUserSetupProcessor (community edition).
• organizationRoleMap property – A list of key/value pairs that maps external role names to internal ones.
The key should be a role name that your mapping creates, after adding the prefix and capitalization as
configured in JSDefaultLdapAuthoritiesPopulator. For commercial JasperReports Server deployments,
you need to choose the level at which the role is assigned:
• To map to an internal role at the organization level, append |* to the name of the internal role, for
example, ROLE_EXTERNAL_USER|*. Roles mapped at the organization level do not have administrative
privileges.
• To map to an internal role at the system (null) level, do not modify the internal role name, for example,
ROLE_EXTERNAL_ADMINISTRATOR. Roles at the system level are usually reserved for special
users like the system administrator and allow access to the repository folder of all other organizations.
For example, if your LDAP user belongs to a group named jrsadmin that's mapped to the name ROLE_ADMIN_
EXTERNAL_ORGANIZATION, the following code example would assign that user the ROLE_ADMINISTRATOR
system role that makes the user an organization admin. This example shows how to create this system role
mapping in a single organization configuration for commercial editions:
<property name="organizationRoleMap">
<map>
<entry>
<key>
<value>ROLE_ADMIN_EXTERNAL_ORGANIZATION</value>
</key>
<value>ROLE_ADMINISTRATOR</value>
</entry>
</map>
</property>
</bean>
If the value ROLE_ADMINISTRATOR in the key value pair had ended with |* (ROLE_ADMINISTRATOR|*), the user
would have been assigned ROLE_ADMINISTRATOR at the organization level.
Roles not mapped to system roles are created and synchronized in the mapped organization, as described in
2.4.3, “Synchronization of Roles,” on page 18. In particular, if the name ROLE_ADMINISTRATOR or ROLE_
SUPERUSER are mapped from the LDAP groups, but not mapped to system roles, they're created as organization
roles and assigned to the user. As organization roles, they don't grant any access permissions, which can be very
confusing for administrators. Avoid LDAP groups and role mappings that create these names as organization
roles.
<property name="defaultAdminRoles">
<list>
<value>ROLE_USER</value>
<value>ROLE_ADMINISTRATOR</value>
</list>
</property>
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
...
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
For example, to restrict the roles you create in JasperReports Server to roles that begin with JRS_ or EXT_ in
your external authority, you would configure permittedRolesRegex in a way similar to the following:
<property name="permittedRolesRegex">
<list>
<value>JRS_.*</value>
<value>EXT_.*</value>
</list>
</property>
To allow all roles, use .* or comment out the property. If the property is omitted, all roles in the external
authority are synchronized with roles in JasperReports Server.
Do not allow the following in role names: spaces, periods or |, [ ], `, ", ', ~, !, #, $, %, ^, &, [,], *, +, =, ;, :, ?, <, >,
}, {, ), (, ], [, /, or \. Adding these characters in the permittedExternalRoleNameRegex property may cause
unexpected behavior, such as the inability to delete or edit roles containing those characters.
Organizations are a feature of JasperReports Server commercial editions. Skip this section if you have
JasperReports Server community edition.
In implementation that supports multiple organizations, all users and roles except for system administrators and
system roles belong to organizations. In turn, each organization determines the folders that its users can access
in the repository. So the final part of mapping is to determine an organization ID for the external user and roles,
based on the user’s RDN in the directory.
If your JasperReports Server supports multiple organizations, you have two ways to set the user organization for
external users:
• Create a mapping from RDNs in your LDAP server to organizations in JasperReports Server, as described in
3.7.1, “Mapping to Multiple Organizations,” on page 41.
• If you want all users to be in just one of your organizations, use the externalTenantSetupProcessor
bean to specify the organization, as described in 3.7.2, “Mapping to a Single Organization,” on page 45.
If your JasperReports Server deployment supports only a single organization (all community deployments and
some professional editions), you do not need to set organization information.
The following example shows the syntax of the ldapExternalTenantProcessor bean and its properties:
For example, given the ldapExternalTenantProcessor bean configuration above, an LDAP user with the DN
uid=jack,ou=audit,ou=finance, dc=example,dc=com is placed in a organization named audit which is a
child of an organization named finance, which in turn is a child of organization_1. This example illustrates
that it's not possible to map only one of the two RDN components if they have the same attribute. In other
words, the mapping mechanism does not let you choose to create only the audit or the finance organization;
both are created if you specify ou in the list of organizationRDNs.
For security reasons, you should change the default password of any organization admin. See 2.4.4,
“Initialization of JasperReports Server for External Users,” on page 19 for a process to initialize the
server, including organization admins, before going into production with external authentication.
<property name="externalTenantSetupUsers">
<list>
<bean class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.MTAbstractExternalProcessor.ExternalTenantSetupUser">
<property name="username" value="${new.tenant.user.name.1}"/>
<property name="fullName" value="${new.tenant.user.fullname.1}"/>
<property name="password" value="${new.tenant.user.password.1}"/>
<property name="emailAddress" value="${new.tenant.user.email.1}"/>
<property name="roleSet">
<set>
<value>ROLE_ADMINISTRATOR</value>
<value>ROLE_USER</value>
</set>
</property>
</bean>
</list>
</property>
4. To create additional admin users for each external organization, create a bean of class
ExternalTenantSetupUser for each admin user you want.
<bean class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.MTAbstractExternalProcessor.ExternalTenantSetupUser">
<property name="username" value="${new.tenant.user.name.2}"/>
<property name="fullName" value="${new.tenant.user.fullname.2}"/>
<property name="password" value="${new.tenant.user.password.2}"/>
<property name="emailAddress" value="${new.tenant.user.email.2}"/>
<property name="roleSet">
<set>
<value>ROLE_ADMINISTRATOR</value>
<value>ROLE_USER</value>
</set>
</property>
</bean>
5. The ${...} syntax above references values configured in the following file:
<js-install>\buildomatic\conf_source\iePro\js.config.properties file.
To set these values, open <js-install>\buildomatic\conf_source\iePro\js.config.properties and edit the entries
there.
new.tenant.user.name.1=jasperadmin
new.tenant.user.fullname.1=jasperadmin
new.tenant.user.password.1=mynewpassword
new.tenant.user.email.1=
new.tenant.user.name.2=anotheradmin
new.tenant.user.fullname.2=Another Admin
new.tenant.user.password.2=anotherpassword
new.tenant.user.email.2=
Note: The property names, for example, new.tenant.user.name.1, are arbitrary. You can use any name
for each property as long as the name in the applicationContext-externalAuth-xxx.xml file matches the
name in the js.config.properties file.
6. If you want to obfuscate the default passwords in the js.config.properties files, encrypt them as described in
the TIBCO JasperReports Server Security Guide. Obfuscation must be implemented before you install the
server.
7. If you don't want to obfuscate default passwords, you can eliminate the reference to js.config.properties and
instead configure the values directly in the externalTenantSetupUsers property in the
applicationContext-externalAuth-xxx.xml file. For example:
<property name="organizationMap">
<map>
<entry key="External_Org_1" value="JRS_Org_1" />
<entry key="External_Org_2" value="JRS_Org_2" />
</map>
</property>
The organizationMap property is optional. Any organization in your external authority that is not listed in
organizationMap is mapped to an organization of the same name in JasperReports Server. However, if an
organization in your external authority contains unsupported characters, each sequence of unsupported
characters is replaced with a single underscore. For example, Human Resources maps to Human_Resources.
The tenantIdNotSupportedSymbols property of the configurationBean bean in the applicationContext.xml
file lists the unsupported characters, including spaces and the following characters: |, &, *, ?, <, >, /, \, ~, !, #,
$, %, ^, [, ], or a space. If you want to list additional characters that should be replaced with an underscore, you
can add them in this bean. However, we do not recommend removing any of the pre-defined characters, as
JasperReports Server may not handle them correctly.
The ldapExternalTenantProcessor bean is not available in the community edition. You don't need to
set the organization in the community edition.
ldapExternalTenantProcessor is an example of a processor. For more information about processors,
see 7.3, “Creating a Custom Processor,” on page 104.
The following example places all external users in the default organization, organization_1.
<bean id="ldapExternalTenantProcessor"
class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.ldap.LdapExternalTenantProcessor"
parent="abstractExternalProcessor">
<property name="ldapContextSource" ref="ldapContextSource"/>
<property name="multiTenancyService"><ref bean="internalMultiTenancyService"/></property>
<property name="excludeRootDn" value="true"/>
<property name="defaultOrganization" value="organization_1"/>
</bean>
Make sure you specify a value for the defaultOrganization. If defaultOrganization is left empty,
users may be mapped to the null organization id. This is usually reserved for special users like the system
administrator and allows access to the repository folder of all other organizations.
The ldapAuthenticationManager bean attempts to authenticate a user session with each provider in the list
in the order they appear. When one of the providers successfully authenticates the user, the rest of the providers
are skipped.
As shown in the example above, you can list other authentication providers with LDAP.
The daoAuthenticationProvider is the default internal authentication using the internal database. You may
keep this provider in the list to access the jasperadmin and superuser accounts, or any other administrator
accounts you've created. Or, if you have configured system role mapping as described in 3.6.2, “Mapping Roles
to System Roles,” on page 36, you can remove the daoAuthenticationProvider from the list.
The internal database contains accounts for all of the external users that have previously logged into the
server. However, these external accounts do not contain passwords and cannot be used for
authentication with the default internal authentication, for example when the LDAP server is unavailable.
You must also include a role mapping for any roles you want to import to JasperReports Server, and you must
include an organization mapping if you implement multiple organizations. For more information, see 3.6,
“Mapping the User Roles,” on page 34.
Note that for Active Directory, sAMAccountName must be in constructor-arg index="1" of the userSearch
bean.
<bean id="ldapContextSource"
class="com.jaspersoft.jasperserver.api.security.externalAuth.ldap.JSLdapContextSource">
<constructor-arg value="ldap://hostname:389/dc=example, dc=com" />
<property name="userDn">
<value>cn=Administrator, dc=example, dc=com</value>
</property>
<property name="password"><value>password</value></property>
<property name="referral" value="follow"/>
</bean>
source editor on the web, such as Apache Directory Studio. Many common IDEs, such as Eclipse, also
support LDIF plugins.
This error can be misleading, because it can come from a wide range of root causes, including problems that are
not directly related to the credentials used. These include:
• Communication issues
• User search issues
"Invalid credentials supplied" errors can be misleading, as they are not always related to the credentials
used.
javax.naming.CommunicationException
If you see this in the logs, you need to dig a little further to find the cause of the communication exception.
Problem
If the URL for the LDAP server is incorrect in applicationContext-externalAuth.xml, you will see an error such
as the following:
org.springframework.security.authentication.InternalAuthenticationServiceException: localhost:10399;
nested exception is javax.naming.CommunicationException: localhost:10399 [Root exception is
java.net.ConnectException: Connection refused: connect]
Solution
To fix this error, locate the following lines in applicationContext-externalAuth.xml and verify that
myLDAPServer is correct hostname for your LDAP server and that and port is your LDAP server port:
<bean id="ldapContextSource"
class="com.jaspersoft.jasperserver.api.security.externalAuth.ldap.JSLdapContextSource">
<constructor-arg value="ldap://myLDAPServer:port"/>
Problem
If the connection is timing out while trying to talk to the LDAP server, you will see a "Connection timed out"
error in the log, such as:
Solution
To fix this error, ensure that the LDAP server is reachable from the server that is hosting JasperReports Server.
Possible causes for connectivity problems include (but are not limited to): firewalls, anti-virus software, or an
incorrectly configured DMZ.
Problem
If JasperReports Server can’t find the user because you have not configured the server to communicate with an
existing branch within LDAP, you may see an "Invalid search base" error in jasperserver.log. For example:
Solution
To resolve this, check with your LDAP admin that the search base you are using exists within your LDAP
directory. The search base is usually specified in the <constructor-arg index="0"> parameter in the
userSearch bean in applicationContext-externalAuth.xml.
Problem
If JasperReports Server can’t find the user because the search is not configured to look in the correct partition,
you may see a "Cannot find a partition" error in jasperserver.log, for example:
Solution
This error can arise if you are importing your LDIF file. In this case, the partitions may not be created
automatically, and therefore are not searchable. Check the LDAP connection URL in the ldapContextSource
bean in applicationContext-externalAuth.xml. If the partition is not present, you can append it to the bean.
Problem
If the search filter is not constructed correctly in your applicationContext-externalAuth.xml file your connection
will fail. This error can be tricky because it does not always give an error code in the log. Instead, the query is
valid, but when it searches your LDAP directory, it simply returns nothing:
An invalid search filter is a filter that is malformed or cannot be loaded. You can also have a correctly
formed search filter that returns incorrect results. See 3.10.2.2.5, “User Not Found By Valid Search
Filter,” on page 50 for more information.
Solution
If you suspect the search filter might be invalid, run the query in a third-party LDAP client and see if it returns
any users. If the query does not return any users, correct the query to retrieve the users you want, then update
your applicationContext-externalAuth.xml file with the correct query.
Problem
In some cases, the user is found, but the bind process fails. You might see an error in the logs such as the
following:
Solution
A common reason for this is because of a mismatch in the DN format between what you specify in your search
query versus what is acceptable for your specific version of LDAP. The precise solution depends on the
implementation and configuration of your LDAP server. For more information, please consult documentation for
your LDAP solution.
Problem
A valid search filter that runs and returns results may not find all intended users. In this case you will see the
same failed authentication message in the log as you would for an unauthorized user:
Solution
This can happen for a number of causes. One of the most common is that the search filter is valid but is not
returning the set of users you want. You could have misconfigured your query or you could be pointing to the
wrong query in your applicationContext-externalAuth.xml file. Test the query shown in the log by running it in
a third-party LDAP client and see if it returns the missing user.
To fix an incorrect query, look for the search filter in the applicationContext-externalAuth.xml file. Search filters
are declared in the ldapAuthenticationManager bean, and the filter definition containing the query string is
defined later in the same file. Check to make sure the search string is correct and that
ldapAuthenticationManager is pointing to the correct search filter.
Problem
If your application context file, applicationContext-externalAuth.xml, is not a valid XML file, the login page
does not load. You may see a stack trace in the logs, specifying the invalid file:
Solution
Usually the stack trace shows the name of the invalid file, the location in the file that is causing the problem,
and the error that triggered the stack trace. The resolution depends on the error. In some cases, the location in
the stack trace will not be the location of the root problem in the file.
In the example above, there is a missing ending tag for property. To fix this, add the tag at the location
specified by <lineNumber> and <columnNumber>.
Problem
Role names can't contain certain special characters, including the XML reserved characters <, >, &, ', ", and \. If
you use a reserved character in a role name in your XML file, JasperReports Server attempts to interpret it as
XML, which results in a stack trace. The precise error depends on the special character. For example, if you use
an ampersand (&) in a role name, you see an error like this:
Solution
In general, it is safest to restrict role names to alpha-numeric characters. If extended characters are necessary for
your naming convention, choose non-reserved characters.
Problem
Jasper is trying to read a bean definition that doesn’t exist. In the error message, you see reference to the <type
of bean>, which typically refers to the actual java class name for that bean definition. The bean name in the
applicationContext-externalAuth.xml file may appear later in the error:
Solution
Check the following:
1. Make sure the bean is defined in your application context XML file.
2. Verify that the name of the bean is correct in your applicationContext-externalAuth.xml. If the bean name is
spelled wrong, it won't be found.
Problem
JasperReports Server can't find a Java class referenced in the XML file. The stack trace shows the name of the
class:
[className] for bean with name 'ldapAuthenticationProvider' defined in ServletContext resource [/WEB-
INF/applicationContext-externalAuth-LDAP-mt.xml]; nested exception is java.lang.ClassNotFoundEx-
ception: <className>
Solution
Check the following:
1. Make sure the jar containing the specified class can be found in the classpath, (for example, \jasperserver-
pro\WEB-INF\lib)
2. Verify that the name of the class is correct in your XML file. If the class name is spelled wrong, it won't be
found as the name won't match, even if the class is present in a jar in the classpath.
Problem
JasperReports Server displays the j_spring_security_check page:
Solution
Errors with DefaultLdapAuthoritiesPopulator indicate that no roles could be found for this user. As part of
the login process, the user is both authenticated and authorized. JasperReports Server uses LDAP and
DefaultLdapAuthoritiesPopulator to determine which roles to assign to the user. A user needs at least
ROLE_USER to log in. If no roles are assigned to the user, the login fails as above.
Ensure that you've configured role search correctly in the JSDefaultLdapAuthoritiesPopulator bean in
your LDAP file. Make sure that it is using the correct branch in your LDAP.
The overview in this section explains the major steps involved in the protocol between the CAS server and
JasperReports Server, as well as the Spring Security beans involved. This chapter does not explain CAS proxies,
but it does cover the Spring Security beans used to configure JasperReports Server’s response to CAS proxies.
The sample configuration has been verified with CAS 3.
See https://www.apereo.org/projects/cas and https://apereo.github.io/cas/4.2.x/index.html for more information.
The interaction between the user’s browser, JasperReports Server, and the CAS server includes these steps:
1. An unauthenticated user requests any page in JasperReports Server.
With SSO, JasperReports Server does not have a login page for users to bookmark. Instead, users can
bookmark their home page or any page that allows it in JasperReports Server. As a result, every user goes
through this step for every page they request from JasperReports Server, thereby securing every possible
access to JasperReports Server.
Internal users, such as jasperadmin or superuser, log in by going directly to the login page, for
example,
http://host1:8080/jasperserver[-pro]/login.html.
2. JasperReports Server detects that the user is not logged in and replies with a redirect to the CAS login page.
The redirect URL contains the service parameter that tells CAS where to redirect the user after successful
authentication. This URL activates JasperReports Server’s user authentication. For example:
http://host2:8443/cas/login?service=http://host1:8080/jasperserver[-pro]/j_spring_security_check.
URLs may appear translated when viewed in browsers or in log files. For example, the previous URL might
be written http://host2:8443/cas/login?service=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fhost1:8080%2Fjasperserver%2Fj_spring_
security_check.
3. The user’s browser requests the CAS login page from the CAS server. If the user has logged in previously
and has a Ticket Granting Ticket (TGT) cookie, the TGT is included in the request.
4. The CAS server attempts to authenticate the user’s credentials.
• If the CAS server detects the TGT cookie in the user’s login request, CAS skips verification of the user
credentials.
• If there's no TGT cookie, CAS serves its login page to the user. When the user enters a username and
password, CAS verifies them against its own data source.
After the user authenticates correctly, CAS issues the user a service ticket (for example:
http://host1:8080/jasperserver-[pro]/j_spring_security_check?ticket=ST-8670-123buTvFFjo980) and a TGT
cookie if one is not present. The TGT cookie can be used for single sign-on with other applications that use
the same CAS server.
If the user has disabled cookies, the CAS login protocol still works, but single sign-on fails. When no
cookie is detected on the user’s browser, the user is prompted to log into the CAS server every time
he accesses a client application.
5. CAS redirects the user to the JasperReports Server with the service ticket in the redirect URL.
6. The JasperReports Server authentication request filter is activated by the request for the j_spring_security_
check resource. As part of the user authentication process, JasperReports Server establishes a secure HTTP
connection (HTTPS) to CAS to validate the service ticket. If the ticket is valid, CAS replies with the
username; otherwise, CAS responds with an error.
7. If an external data source is configured, JasperReports Server connects to the data source and requests the
user organization and roles associated with the username returned by CAS. If the organization and roles are
configured statically, this step is skipped.
8. JasperReports Server creates the principal object that establishes the user’s session. The username, roles, and
organization are also synchronized with the internal database, where the user account is marked as an
external user. For more information, see 2.4.2, “Synchronization of External Users,” on page 17.
9. As with the default internal authorization, JasperReports Server now sends the requested content to the user.
Content sent to the user is subject to authorization. For example the home page has different options for
administrators than for regular users, as determined by the roles of the user in the principal object.
When comparing these steps with those in 2.3, “Default Internal Authentication,” on page 15, you'll notice
several significant differences:
• JasperReports Server must redirect to the CAS login page instead of its own.
• JasperReports Server must receive the service ticket as part of the security check.
• JasperReports Server must process the service ticket and communicate with the CAS server over HTTPS.
• The roles and organization ID in the user’s principal object are mapped from the response to the request for
user details.
• The internal database must be synchronized with any new information in the user’s principal object.
This section describes how to set up a simple CAS server for testing purposes. If you have a CAS server
you want to use, you can skip this section.
The CAS server is Java servlet built on the Spring Framework. Its primary responsibility is to authenticate users
and grant access to CAS-enabled services by issuing and validating tickets. You can download the server from
the following page: https://www.apereo.org/projects/cas/download-cas.
As described in the next section, the CAS validation service accepts only requests using a secure transport. This
means you must have a valid certificate on your CAS server machine, and your CAS client (the JasperReports
Server JVM) must be configured to trust that certificate. There are two important points to keep in mind:
• Test with the CAS server on a separate machine, not the localhost where JasperReports Server is installed.
For this purpose, you can use a virtual machine.
• Most issues in configuring CAS are caused by the improper use of certificates. The single most common
failure occurs when the hostname in the server’s certificate doesn’t match the actual hostname.
To create a certificate for the server you must use the Java keytool utility. Run the following command on the
host of the CAS server:
keytool -genkey -alias tomcat -keyalg RSA -validity 365 -keystore <filename>
The utility prompts you for several pieces of information, two of which are critical. When prompted for your
first and last name enter the hostname of the CAS server. When asked for the keystore password use changeit
to match what Apache Tomcat uses by default.
After installation of the CAS server, configure the Apache Tomcat application server that's running the CAS
server so it uses the certificate in the keystore created above. Modify $CATALINA_HOME/conf/server.xml,
locate the commented section about setting up a secure HTTPS connector, and follow the instructions it
contains. Restart the Tomcat server and test that it accepts HTTPS connections.
For further information about CAS, including deployment information, documentation, and community links,
refer to the CAS website https://www.apereo.org/projects/cas. In particular, the page
https://apereo.github.io/cas/4.2.x/installation/Troubleshooting-Guide.html can help you deploy your certificates.
CAS server is based on Spring Security, like JasperReports Server. In a production environment, you
must replace the built-in authentication for testing with an external authority that validates your users
when they log into CAS. As with JasperReports Server, you can configure CAS with a variety of external
authorities to suit your needs, including LDAP. However, the external authority used by CAS may not be
accessible to JasperReports Server.
Follow the CAS documentation to ensure you create a secure and robust configuration on your CAS
server.
A non-default cacerts location can be specified using the -Djavax.net.ssl.trustStore JVM parameter.
To use LDAP or an external database with CAS, configure the LDAP or database connection parameters
in default_master.properties before installing JasperReports Server. You can set up encryption for the
password to your LDAP server or database at that time. See the TIBCO JasperReports Server Security
Guide for more information.
To configure JasperReports Server to work with your implementation of CAS, select the sample configuration
file you want, then modify and deploy it:
1. Make a copy of the CAS sample file and name it in the form applicationContext-<Name>.xml, for example,
applicationContext-externalAuth-CAS-staticRoles-mt.xml.
2. Edit the file you created and configure the beans correctly for your deployment, as described in the
following sections.
3. Place the modified applicationContext-externalAuth-CAS-staticRoles-mt.xml file in the <js-webapp>/WEB-
INF directory.
<js-webapp> is the location of the JasperReports Server web application in your application server, or
where you're modifying the configuration files, as explained in 2.1.2, “WEB-INF Directory Location,” on
page 12. The rest of this chapter refers to file names alone.
<property name="defaultAdminRoles">
<list>
<value>ROLE_USER</value>
<value>ROLE_ADMINISTRATOR</value>
</list>
</property>
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
...
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
<property name="permittedRolesRegex">
<list>
<value>JRS_.*</value>
<value>EXT_.*</value>
</list>
</property>
To allow all roles, use .* or comment out the property. If the property is omitted, all roles in the external
authority are synchronized with roles in JasperReports Server.
Do not allow the following in role names: spaces, periods or |, [ ], `, ", ', ~, !, #, $, %, ^, &, [,], *, +, =, ;, :, ?, <, >,
}, {, ), (, ], [, /, or \. Adding these characters in the permittedExternalRoleNameRegex property may cause
unexpected behavior, such as the inability to delete or edit roles containing those characters.
Organizations are a feature of JasperReports Server commercial editions. Skip this section if you have
JasperReports Server community edition.
Spring’s default CAS configuration supports only user authentication. However, you can extend this to set
organizations in one of two ways:
• Extract organization data with an additional technology, such as LDAP or a JDBC database. See 4.8.1,
“Mapping to Multiple Organizations,” on page 66.
• Use the defaultOrganization property of the externalTenantSetupProcessor bean to set a single
organization assigned to all external users. See 4.8.2, “Mapping to a Single Organization,” on page 67.
Do not specify a null value for the defaultOrganization property. The null organization ID is usually
reserved for special users like the system administrator and allows access to the repository folder of all
other organizations.
Organizations created during external user login have an administrator with the default password. For security
reasons, you should change the default password of any organization admin. See 2.4.4, “Initialization of
JasperReports Server for External Users,” on page 19 for a process to initialize JasperReports Server,
including organization administrators, before going into production with external authentication.
To avoid confusion, you can remove or hide the Log Out link using the techniques in “Customizing the User
Interface” in the TIBCO JasperReports Server Ultimate Guide.
The following figure shows the general steps for external database authentication:
The interaction between the user’s browser, JasperReports Server, and the external database includes these steps:
1. An unauthenticated user requests any page in JasperReports Server.
2. JasperReports Server detects that the user is not logged in and replies with the JasperReports Server login
page.
3. The user enters their credentials.
4. The JasperReports Server establishes a connection to the database server to verify the user's credentials.
5. If the user submitted a valid username and password, the database server authenticates the user to
JasperReports Server.
6. JasperReports Server requests user details from the database server using a database query specified in the
configuration file.
7. The database server returns the requested details.
JasperReports Server maps the username to a predefined set of roles and an organization ID. The username,
roles, and organization are also synchronized with the internal database, where the user account is marked
as an external user. (Community editions don't need to synchronize the organization.) For more information,
see 2.4.2, “Synchronization of External Users,” on page 17.
8. JasperReports Server now sends the requested content to the user. Content that is sent to the user is subject
to authorization. For example, the home page has different options for administrators than for regular users.
The only difference between these steps and those in 2.3, “Default Internal Authentication,” on page 15, is
that instead of searching for the user in the jasperserver internal database, JasperReports Server makes a
JDBC call to the external database and then synchronizes the user details.
<js-webapp> is the location of the JasperReports Server web application in your application server, or
where you're modifying the configuration files. The rest of this chapter refers to file names alone.
• passwordValidator – Bean that specifies a key for encoding user passwords. First, import the same
cryptographic key that is used for passwords in your database. Then configure this bean with the key's alias
and password, as described in “Setting the Password Encryption ” on page 75.
• externalDataSynchronizer – Bean whose class creates a mirror image of the external user in the internal
jasperserver database. The sample includes the following processors:
• externalTenantSetupProcessor – Bean that sets up external organizations in the jasperserver
database. For multi-organization JasperReports Server deployments, configure this bean to specify the
mapping between fields and field values retrieved from the database and JasperReports Server
organizations, as described in “Setting the User Organization” on page 79.
• mtExternalUserSetupProcessor – Bean that creates and configures the internal user corresponding
to a successfully authenticated external user. Configure this bean to specify the default internal role
given to the external users in JasperReports Server and to map external user roles to internal
JasperReports Server roles if needed, as described in 5.7, “Mapping User Roles,” on page 76.
Optionally, you can assign administrative roles to specific users.
• externalUserFolderProcessor – Bean that creates a user folder as an example of additional post-
authentication processing. Post-authentication processing is described in “Authentication Based on
Request” on page 105.
• externalDataSource – Configure this bean with the JDBC connection information to the external
database to which users are authenticated, as described in “Setting the Database Connection Parameters”
on page 72.
• externalAuthProperties – This bean stores properties necessary to configure JasperReports Server for
external authentication. For multi-organization deployments of JasperReports Server, configure this bean to
require an organization ID on the login form, as described in “Configuring the Login Page for a Single-
Organization Deployment” on page 82
external.jdbcDriverClass=com.mysql.jdbc.Driver
external.jdbcUrl=jdbc:mysql://127.0.0.1:3306/external_sso_test
external.dbUsername=username
external.dbPassword=password
encrypt=true
propsToEncrypt=dbPassword,external.dbPassword
See the TIBCO JasperReports Server Security Guide for more information on encrypting passwords using
buildomatic.
If you configured your database connection during JasperReports Server installation, don't set the
parameters using externalDataSource. You can verify whether the parameters are set by looking at
the default_master.properties file.
To set the connection parameters for the external database server directly in the application context file,
configure the externalDataSource helper bean as follows:
1. In sample-applicationContext-externalAuth-db-mt.xml, locate the externalDataSource bean.
2. Specify the following information:
• driverClassName property – The name of the JDBC driver class for your database. Make sure the
driver jar library is available on the classpath. For example, you can place the jar in the lib directory of
your application server or in the <js-webapp>/lib directory.
• url property – The JDBC URL for your database server, including the hostname, port, and database
you want to access.
• username property – The username of your database administrator.
• password property – The password of your database administrator.
The following is an example of the connection information for a MySQL database:
Note that the semantics, order, and number of the columns in each tuple is fixed. Changing the order or number
of the columns requires customization, which is beyond the scope of this manual.
cd <js-install>/buildomatic
js-import.sh --input-key --keystore <path>/mykeystore --storepass password
--keyalias mydbkey --keypass mydbkeypw
The key will be copied to the server's keystore and keep the same properties, including alias and password. You
can also import keys as hexadecimal values if necessary. The following command creates a new key with the
given algorithm, alias, and password:
js-import.sh --input-key "0x59 0xe3 0xd9 0xce 0x7f 0x34 0xab 0x27 0xb8 0xdf 0xc3 0x7e
0x01 0xab 0x4d 0x6c" --keyalg AES --keyalias mydbkey --keypass mydbkeypw
In the case where your external database is new and not yet provisioned with users, it will need a key to
encrypt passwords. In that case, JasperReports Server can generate the key, store it in the keystore, and you can
export it to use in your database. The following commands create a new random key in the keystore and export
the same key for use externally:
For more information about the keystore and exporting keys, see the TIBCO JasperReports Server Security
Guide
Once the key is in the server's keystore, configure the passwordValidator bean in the applicationContext-
externalAuth-db-mt.xml file. Set the bean's property values to match those of the key you have imported. The
following example shows how to configure the bean with the keys imported above:
By default, the JasperReports Server keystore supports AES and DES keys. If your database uses a
different encryption algorithm, you can configure your own password encoder using the Spring
implementations of the PasswordEncoder interface. This is an advanced configuration that is beyond the
scope of this guide.
<property name="organizationRoleMap">
<map>
<!-- Example of mapping customer roles to JRS roles -->
<entry>
<key>
<value>ROLE_ADMIN_EXTERNAL_ORGANIZATION</value>
</key>
<!-- JRS role that the <key> external role is mapped to-->
<value>ROLE_ADMINISTRATOR|*</value>
</entry>
</map>
</property>
<property name="defaultAdminRoles">
<list>
<value>ROLE_USER</value>
<value>ROLE_ADMINISTRATOR</value>
</list>
</property>
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
...
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
<property name="permittedRolesRegex">
<list>
<value>JRS_.*</value>
<value>EXT_.*</value>
</list>
</property>
To allow all roles, use .* or comment out the property. If the property is omitted, all roles in the external
authority are synchronized with roles in JasperReports Server.
Do not allow the following in role names: spaces, periods or |, [ ], `, ", ', ~, !, #, $, %, ^, &, [,], *, +, =, ;, :, ?, <, >,
}, {, ), (, ], [, /, or \. Adding these characters in the permittedExternalRoleNameRegex property may cause
unexpected behavior, such as the inability to delete or edit roles containing those characters.
Organizations are a feature of JasperReports Server commercial editions. Skip this section if you have
JasperReports Server community edition.
jasperadmin user, and/or create additional default users in each new organization created by external
authentication. Optionally, you can encrypt the password in the configuration files. See the TIBCO
JasperReports Server Security Guide for more information on default users in every organization.
For security reasons, you should change the default password of any organization admin. See 2.4.4,
“Initialization of JasperReports Server for External Users,” on page 19 for a process to initialize the
server, including organization admins, before going into production with external authentication.
<property name="externalTenantSetupUsers">
<list>
<bean class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.MTAbstractExternalProcessor.ExternalTenantSetupUser">
<property name="username" value="${new.tenant.user.name.1}"/>
<property name="fullName" value="${new.tenant.user.fullname.1}"/>
<property name="password" value="${new.tenant.user.password.1}"/>
<property name="emailAddress" value="${new.tenant.user.email.1}"/>
<property name="roleSet">
<set>
<value>ROLE_ADMINISTRATOR</value>
<value>ROLE_USER</value>
</set>
</property>
</bean>
</list>
</property>
4. To create additional admin users for each external organization, create a bean of class
ExternalTenantSetupUser for each admin user you want.
<bean class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.MTAbstractExternalProcessor.ExternalTenantSetupUser">
<property name="username" value="${new.tenant.user.name.2}"/>
<property name="fullName" value="${new.tenant.user.fullname.2}"/>
<property name="password" value="${new.tenant.user.password.2}"/>
<property name="emailAddress" value="${new.tenant.user.email.2}"/>
<property name="roleSet">
<set>
<value>ROLE_ADMINISTRATOR</value>
<value>ROLE_USER</value>
</set>
</property>
</bean>
5. The ${...} syntax above references values configured in the following file:
<js-install>\buildomatic\conf_source\iePro\js.config.properties file.
To set these values, open <js-install>\buildomatic\conf_source\iePro\js.config.properties and edit the entries
there.
new.tenant.user.name.1=jasperadmin
new.tenant.user.fullname.1=jasperadmin
new.tenant.user.password.1=mynewpassword
new.tenant.user.email.1=
new.tenant.user.name.2=anotheradmin
new.tenant.user.fullname.2=Another Admin
new.tenant.user.password.2=anotherpassword
new.tenant.user.email.2=
Note: The property names, for example, new.tenant.user.name.1, are arbitrary. You can use any name
for each property as long as the name in the applicationContext-externalAuth-xxx.xml file matches the
name in the js.config.properties file.
6. If you want to obfuscate the default passwords in the js.config.properties files, encrypt them as described in
the TIBCO JasperReports Server Security Guide. Obfuscation must be implemented before you install the
server.
7. If you don't want to obfuscate default passwords, you can eliminate the reference to js.config.properties and
instead configure the values directly in the externalTenantSetupUsers property in the
applicationContext-externalAuth-xxx.xml file. For example:
<property name="organizationMap">
<map>
<entry key="External_Org_1" value="JRS_Org_1" />
<entry key="External_Org_2" value="JRS_Org_2" />
</map>
</property>
The organizationMap property is optional. Any organization in your external authority that is not listed in
organizationMap is mapped to an organization of the same name in JasperReports Server. However, if an
organization in your external authority contains unsupported characters, each sequence of unsupported
characters is replaced with a single underscore. For example, Human Resources maps to Human_Resources.
The tenantIdNotSupportedSymbols property of the configurationBean bean in the applicationContext.xml
file lists the unsupported characters, including spaces and the following characters: |, &, *, ?, <, >, /, \, ~, !, #,
$, %, ^, [, ], or a space. If you want to list additional characters that should be replaced with an underscore, you
can add them in this bean. However, we do not recommend removing any of the pre-defined characters, as
JasperReports Server may not handle them correctly.
Do not specify a null value for the defaultOrganization property. The null organization ID is usually
reserved for special users like the system administrator and allows access to the repository folder of all
other organizations.
Organizations created during external user login have an administrator with the default password. For security
reasons, you should change the default password of any organization admin. See 2.4.4, “Initialization of
JasperReports Server for External Users,” on page 19 for a process to initialize JasperReports Server,
including organization administrators, before going into production with external authentication.
Deployments with multiple organizations in the database always display a line for the organization ID on the
login page.
If you have an application or portal you want to use with JasperReports Server, but no single sign-on
environment, you can use the Jaspersoft token-based authentication and user management framework. To work
with token-based authentication, your application or portal must do the following:
• Authenticate the end user according to the standards of your environment or application.
• Construct and, optionally, encrypt a token based on the authenticated user values within your application
or process. The token values can include username, organization (if multi-tenancy is enabled), roles, and
profile attributes. You can configure the token based on your needs for reporting and analysis within the
JasperReports Server.
• Send the token to the JasperReports Server as part of an HTTP request.
When JasperReports Server receives the token, it will:
• Attempt to decrypt the token (if encrypted) and validate the token format.
• If the token is successfully parsed, use the information in the token to create and update the external user
within JasperReports Server automatically.
The JasperReports Server deployment includes a sample file for token-based authentication in the
<js-install>/samples/externalAuth-sample-config folder: the sample-applicationContext-externalAuth-preauth-
mt.xml file (commercial editions) or sample-applicationContext-externalAuth-preauth.xml (community editions).
When using token-based authentication, it's extremely important that your external system is
configured properly to prevent an attacker from forging the token. Consider taking security measures
like connecting over HTTPS, encrypting the token, and using a time stamp, so the token is not exposed
in the browser cache and cannot be easily reused.
The following diagram shows the general steps involved in logging into JasperReports Server using a token:
The following steps explain the interaction between the user’s browser, JasperReports Server, and a pre-
authenticated user:
1. A user requests any page in JasperReports Server.
2. If the user has not previously accessed JasperReports Server, the server looks for the principalParameter
in the URL or request header. If the token is present and correctly formatted, the user is automatically
authenticated.
In token-based authentication, the JasperReports Server login screen is not displayed to the user and
the user does not log in directly.
After the user has authenticated and a JasperReports Server session has been created, future requests do not
require the principalParameter.
3. JasperReports Server decrypts the token in the URL or request header and creates a principal object to
represent the user’s session in memory. The username, roles, and organization information are extracted from
the token and synchronized with the internal database, where the user account is marked as an external user.
The JasperReports Server environment reflects the user’s roles and organization as defined in the token. For
more information about synchronization, see “Synchronization of External Users” on page 17.
4. As with the default internal authorization, JasperReports Server now sends the requested content to the user,
or if none was specified, the home page appropriate for the user. An application-server user session is
established and the connection between the requesting browser or process is maintained by repeatedly
sending session identification information, usually in the form of an HTTP cookie. The token doesn't need
to be resent until the user logs out or the session is inactive for a period of time.
When comparing these steps with those in 2.3, “Default Internal Authentication,” on page 15, you'll notice
three significant differences:
• Token-based authentication doesn't use a login screen. Instead, it depends on the principalParameter in
the URL or request header. As long as the principalParameter is present, the request is automatically
authenticated.
• The portal or other external authentication mechanism is responsible for passing the correct username, and
any roles, organization, or profile attributes as part of a token in the URL or request header.
• JasperReports Server decrypts the token, extracts the user details, and uploads the data to the internal
database. The internal database is synchronized with any new information in the user’s principal object.
<js-webapp> is the location of the JasperReports Server web application in your application server, or
where you're modifying the configuration files. The rest of this chapter refers to file names alone.
the application context, the Spring Security filter chain processes the authentication via the proxy
definitions instead of the default internal filter. See 6.4, “Configuring the Token,” on page 88 for more
information.
• preAuthenticatedManager — Lists the available authentication providers. In token-based authentication,
there's a single provider, the JSPreAuthenticatedAuthenticationProvider. This bean doesn't have to
be configured
• JSPreAuthenticatedAuthenticationProvider — Custom authentication provider for token-based
authentication. This bean has a constructor argument, preAuthenticatedUserDetailsService, which it
uses to create the user details from the values passed in the token. See 6.4, “Configuring the Token,” on
page 88.
• externalDataSynchronizer — Bean whose class creates a mirror image of the external user in the
internal jasperserver database.
• mtExternalUserSetupProcessor or externalUserSetupProcessor– Bean that creates and configures
the internal user corresponding to a successfully authenticated external user. Configure this bean to specify
the roles given to external users. See 6.5, “User Roles,” on page 92.
• externalTenantSetupProcessor — For multi-tenant deployments, this bean creates and configures the
internal organization for a successfully authenticated external user. See 6.6, “Mapping the User
Organization,” on page 95.
• externalProfileAttributeProcessor — Optional processor that sets up user profile attributes. You
don't need to configure this processor; the mapping is set up in the token configuration. Comment this bean
out if not used.
package com.mycompany;
@Override
public String decrypt(String cipherText) {
...
return plainText;
}
}
Once you've created your implementation of CipherI, you need to incorporate it in a jar file and reference it in
the tokenDecryptor property of proxyPreAuthenticatedProcessingFilter:
6.4.3 preAuthenticatedUserDetailsService
Specify the token format using the preAuthenticatedUserDetailsService constructor argument in the
preAuthenticatedManager bean. An inline bean in preAuthenticatedUserDetailsService lets you
specify the token properties. The following example shows one way you might configure this bean:
If you're passing the token in the URL, you need to encode all equal signs (=, encoded as %3D) and pipe
symbols (|, encoded as %7C) in the token to make the token URL-safe.
• tokenFormatMapping — The mapping between parameters in the token and attributes of the principal
object in JasperReports Server, like roles and profile attributes. Entries in the mapping have the format
<entry key ="JRS" value="keyintoken">, for example, <entry key="username" value="u" />. The key, such
as username, is a fixed value used in the JasperReports Server code. The value is a parameter in the token
mapped to the key in JasperReports Server.
• tokenFormatMapping supports the following JasperReports Server fixed values:
• username — The external user's username.
• roles — The external user's roles.
• orgId — (optional, multi-tenant implementations only) In a multi-organization deployment, the
external user's organization. In a single-tenant deployment, or in a deployment that maps all users to the
same organization using defaultOrganization, you can comment out this property.
• expireTime — The key for the token expiration time. A time formatted as configured in the
tokenExpireTimestampFormat property.
• profile.attribs — (optional) This lets you specify a map of key-value pairs for profile attributes.
Comment this out if you don't want to map profile attributes. You must also comment out the reference
to externalProfileAttributeProcessor in the externalUserProcessors property of the
externalDataSynchronizer.
The user password does not appear as a standard parameter in the token format. Passwords
don’t need to be passed in the token in most cases, because JasperReports Server doesn't store
passwords for externally-defined users. If you want to store passwords, you can pass them in
using profile attributes.
For more information about the valid patterns for this field, refer to:
http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html.
The token has to match the configuration you specify in preAuthenticatedUserDetailsService. With the
configuration shown in Table 6-1, “Sample Code Configuration,” on page 90, you would use the following
token syntax in the page header:
pp=u=user|r=role1,role2,...|o=org1[,org2,...]|pa1=PA11,PA12,...|pa2=PA21,PA22,...|exp=time
In this example, pp (principalParameter) is the name of the header attribute or the URL token parameter
name.
If you're passing the token in the URL, you need to encode all equal signs (=, encoded as %3D) and pipe
symbols (|, encoded as %7C) in the token to make the token URL-safe.
The key-value pairs can appear in the token in any order, but must be delineated by the separator specified in
the tokenPairSeparator property:
• u — Takes a single value that maps to the username in JasperReports Server.
• r — Takes as values a comma separated list of roles, each mapped to a separate role in JasperReports Server.
If you have defined default internal roles, this parameter is optional. See 6.5, “User Roles,” on page 92.
• o — Takes as values a comma separated list that maps to an organization in the JasperReports Server. If
more than one organization is listed, it's interpreted as an organization hierarchy. For example, o=A,B maps
the user to the B suborganization of A.
• exp — Takes a single time value formatted as configured in the tokenExpireTimestampFormat property.
If exp is earlier than current time, authentication is denied. if exp is absent, the token never expires.
• pa1 — Profile attribute that maps to profileAttrib1 in the JasperReports Server repository.
• pa2 — Profile attribute that maps to profileAttrib2 in the JasperReports Server repository.
With this configuration, the following would be a valid token. The user would be placed in the Sales
suborganization of the EMEA organization:
pp=u=Sven|r=Manager|o=EMEA,Sales|pa1=Sweden
If you're passing the token in the URL, you need to encode all equal signs (=) (as %3D) and pipe symbols (|) (as
%7C) in the token to make the token URL-safe:
http://localhost:8080/jasperserver?pp=u%3DSven%7Cr%3DManager%7Co%3DEMEA,Sales%7Cpa1%3DSweden
externalAuth.processors.MTExternalUserSetupProcessor" parent="abstractExternalProcessor">
<property name="organizationRoleMap">
<map>
<!-- Example of mapping customer roles to JRS roles -->
<entry key= ROLE_ADMIN_EXTERNAL_ORGANIZATION value=ROLE_ADMINISTRATOR />
</map>
</property>
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
<property name="permittedRolesRegex">
<list>
<value>JRS_.*</value>
<value>EXT_.*</value>
</list>
</property>
To allow all roles, use .* or comment out the property. If the property is omitted, all roles in the external
authority are synchronized with roles in JasperReports Server.
Do not allow the following in role names: spaces, periods or |, [ ], `, ", ', ~, !, #, $, %, ^, &, [,], *, +, =, ;, :, ?, <, >,
}, {, ), (, ], [, /, or \. Adding these characters in the permittedExternalRoleNameRegex property may cause
unexpected behavior, such as the inability to delete or edit roles containing those characters.
• defaultInternalRoles property — A list of JasperReports Server roles assigned to every user not in the
list of administrators.
The following example shows how to use the mtExternalUserSetupProcessor bean to define static roles.
The configuration for externalUserSetupProcessor is similar:
<property name="defaultAdminRoles">
<list>
<value>ROLE_USER</value>
<value>ROLE_ADMINISTRATOR</value>
</list>
</property>
<property name="defaultInternalRoles">
<list>
<value>ROLE_USER</value>
</list>
</property>
...
authentication. Optionally, you can encrypt the password in the configuration files. See the TIBCO
JasperReports Server Security Guide for more information on default users in every organization.
For security reasons, you should change the default password of any organization admin. See 2.4.4,
“Initialization of JasperReports Server for External Users,” on page 19 for a process to initialize the
server, including organization admins, before going into production with external authentication.
<property name="externalTenantSetupUsers">
<list>
<bean class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.MTAbstractExternalProcessor.ExternalTenantSetupUser">
<property name="username" value="${new.tenant.user.name.1}"/>
<property name="fullName" value="${new.tenant.user.fullname.1}"/>
<property name="password" value="${new.tenant.user.password.1}"/>
<property name="emailAddress" value="${new.tenant.user.email.1}"/>
<property name="roleSet">
<set>
<value>ROLE_ADMINISTRATOR</value>
<value>ROLE_USER</value>
</set>
</property>
</bean>
</list>
</property>
4. To create additional admin users for each external organization, create a bean of class
ExternalTenantSetupUser for each admin user you want.
<bean class="com.jaspersoft.jasperserver.multipleTenancy.security.
externalAuth.processors.MTAbstractExternalProcessor.ExternalTenantSetupUser">
<property name="username" value="${new.tenant.user.name.2}"/>
<property name="fullName" value="${new.tenant.user.fullname.2}"/>
<property name="password" value="${new.tenant.user.password.2}"/>
<property name="emailAddress" value="${new.tenant.user.email.2}"/>
<property name="roleSet">
<set>
<value>ROLE_ADMINISTRATOR</value>
<value>ROLE_USER</value>
</set>
</property>
</bean>
5. The ${...} syntax above references values configured in the following file:
<js-install>\buildomatic\conf_source\iePro\js.config.properties file.
To set these values, open <js-install>\buildomatic\conf_source\iePro\js.config.properties and edit the entries
there.
new.tenant.user.name.1=jasperadmin
new.tenant.user.fullname.1=jasperadmin
new.tenant.user.password.1=mynewpassword
new.tenant.user.email.1=
new.tenant.user.name.2=anotheradmin
new.tenant.user.fullname.2=Another Admin
new.tenant.user.password.2=anotherpassword
new.tenant.user.email.2=
Note: The property names, for example, new.tenant.user.name.1, are arbitrary. You can use any name
for each property as long as the name in the applicationContext-externalAuth-xxx.xml file matches the
name in the js.config.properties file.
6. If you want to obfuscate the default passwords in the js.config.properties files, encrypt them as described in
the TIBCO JasperReports Server Security Guide. Obfuscation must be implemented before you install the
server.
7. If you don't want to obfuscate default passwords, you can eliminate the reference to js.config.properties and
instead configure the values directly in the externalTenantSetupUsers property in the
applicationContext-externalAuth-xxx.xml file. For example:
<property name="organizationMap">
<map>
<entry key="External_Org_1" value="JRS_Org_1" />
<entry key="External_Org_2" value="JRS_Org_2" />
</map>
</property>
The organizationMap property is optional. Any organization in your external authority that is not listed in
organizationMap is mapped to an organization of the same name in JasperReports Server. However, if an
organization in your external authority contains unsupported characters, each sequence of unsupported
characters is replaced with a single underscore. For example, Human Resources maps to Human_Resources.
The tenantIdNotSupportedSymbols property of the configurationBean bean in the applicationContext.xml
file lists the unsupported characters, including spaces and the following characters: |, &, *, ?, <, >, /, \, ~, !, #,
$, %, ^, [, ], or a space. If you want to list additional characters that should be replaced with an underscore, you
can add them in this bean. However, we do not recommend removing any of the pre-defined characters, as
JasperReports Server may not handle them correctly.
Do not specify a null value for the defaultOrganization property. The null organization ID is usually
reserved for special users like the system administrator and allows access to the repository folder of all
other organizations.
Organizations created during external user login have an administrator with the default password. For security
reasons, you should change the default password of any organization admin. See 2.4.4, “Initialization of
JasperReports Server for External Users,” on page 19 for a process to initialize JasperReports Server,
including organization administrators, before going into production with external authentication.
The following figure shows the most important authentication-related beans in the filter chain:
1. authenticationProcessingFilter — Responsible for authenticating the user and creating the principal
object in memory. With default authentication, this filter redirects the user to the login page, then processes
the organization ID, username, and password.
2. authenticationManager — Bean of Spring class ProviderManager that manages default authentication
by invoking a list of providers. JasperReports Server relies on ${bean.daoAuthenticationProvider} for
internal authentication.
3. ${bean.daoAuthenticationProvider} — Bean for performing authentication to the jasperserver
internal database configured in <js-webapp>/WEB-INF/applicationContext-security.xml.
The filter chains for authentication are configured for the following patterns:
• The /xmla pattern represents the XML for Analysis (XML/A) servlet. They are configured with a set of
filters designed to receive client SOAP requests. SOAP is implemented in the sample files for LDAP.
• The /services/** pattern represents the XML for SOAP web services. In this filter chain, the
${bean.basicProcessingFilter} bean initiates internal authentication. SOAP is implemented in the
sample files for LDAP.
• The /rest/login, /rest/**, and rest_v2/** patterns represent the XML for REST web services. In this
filter chain, the restAuthenticationProcessingFilter and ${bean.basicProcessingFilter} beans
initiate internal authentication. REST is implemented in the sample files for LDAP.
• The /** pattern matches anything that wasn’t caught by another pattern. This pattern is designed for people
using web browsers. In this filter chain, the authenticationProcessingFilter bean initiates.
authenticationProcessingFilter and initiates external authentication for the pattern. These proxy beans
inspect the application context for external authentication beans, and use them if they are present. Otherwise,
the default internal authentication beans are used.
The following sample files use JasperReports Server’s external authentication APIs to integrate with custom SSO
servers following a CAS-like protocol:
• sample-applicationContext-externalAuth-sso.xml — Sample file for integrating CAS with a single-
organization JasperReports Server. Included with the community edition of JasperReports Server only.
• sample-applicationContext-externalAuth-sso-mt.xml — Sample file for integrating CAS with a multiple-
organization JasperReports Server. In this example, user details like external roles and organization are
retrieved from an external database. Included with the commercial version of JasperReports Server only.
<bean id="externalDataSynchronizer"
class="com.jaspersoft.jasperserver.api.security.externalAuth.ExternalDataSynchronizerImpl">
<property name="externalUserProcessors">
<list>
<ref local="externalUserSetupProcessor"/>
<ref local="externalUserFolderProcessor"/>
</list>
</property>
</bean>
The following code block shows how you might configure an externalUserFolderProcessor bean in your
applicationContext-externalAuth-xxx.xml configuration file:
<bean id="externalUserFolderProcessor"
class="com.jaspersoft.jasperserver.api.security.externalAuth.processors.
ExternalUserFolderProcessor"
parent="abstractExternalProcessor">
<property name="repositoryService" ref="${bean.unsecureRepositoryService}"/>
</bean>
To write a processor, extend AbstractExternalUserProcessor and overwrite the process method with your
java code. This gives you access to the following services:
• RepositoryService
• UserAuthorityService
• TenantService
• ProfileAttributeService
• ObjectPermissionService
If you extend MTAbstractExternalProcessor, you can access the following multiTenancyService service:
If you're passing information in the HTTP request, as with Siteminder, it's extremely important that your
external system is configured properly to prevent an attacker from forging the HTTP headers.
The JasperReports Server deployment includes a sample file for custom authentication in the
<js-install>/samples/externalAuth-sample-config folder: the sample-applicationContext-externalAuth-template-
mt.xml file (commercial editions) or sample-applicationContext-externalAuth-template.xml (community
editions). This sample takes the IP address from the user’s authentication request, creates a user with the same
name in JasperReports Server, and uses the JasperReports Server API to create a user folder in the JasperReports
Server Repository and set permissions.
5. Set up your processors to work with your users and organizations. You can use the processors for LDAP or
CAS as examples.
6. Copy the modified file to the WEB-INF folder and remove the sample- prefix.
Audit Domains
A Domain that accesses audit data in the repository and lets administrators create Ad Hoc reports of server
activity. There is one Domain for current audit logs and one for archived logs.
Audit Logging
When auditing is enabled, audit logging is the active recording of who used JasperReports Server to do what
when. The system installer can configure what activities to log, the amount of detail gathered, and when to
archive the data. Audit logs are stored in the same private database that JasperReports Server uses to store the
repository, but the data is only accessible through the audit Domains.
Auditing
A feature of JasperReports Server Enterprise edition that records all server activity and allows administrators to
view the data.
Calculated Field
In an Ad Hoc view or a Domain, a field whose value is calculated from a user-defined formula that may include
any number of fields, operators, and constants. For Domains, a calculated field becomes one of the items to
which the Domain's security file and locale bundles can apply. There are more functions available for Ad Hoc
view calculations than for Domains.
CloudFormation (CF)
Amazon Web Services CloudFormation gives developers and systems administrators an easy way to create and
manage a collection of related AWS resources, provisioning, and updating them in an orderly and predictable
fashion.
CRM
Customer Relationship Management. The practice of managing every facet of a company's interactions with its
clientele. CRM applications help businesses track and support their customers.
CrossJoin
An MDX function that combines two or more dimensions into a single axis (column or row).
Cube
The basis of most OLAP applications, a cube is a data structure that contains three or more dimensions that
categorize the cube's quantitative data. When you navigate the data displayed in an OLAP view, you are
exploring a cube.
Custom Field
In the Ad Hoc Editor, a field that is created through menu items as a simple function of one or two available
fields, including other custom fields. When a custom field becomes too complex or needs to be used in many
reports, it is best to define it as a calculated field in a Domain.
Dashboard
A collection of reports, input controls, graphics, labels, and web content displayed in a single, integrated view.
Dashboards often present a high level view of your data, but input controls can parametrize the data to display.
For example, you can narrow down the data to a specific date range. Embedded web content, such as other web-
based applications or maps, make dashboards more interactive and functional.
Dashlet
An element in a dashboard. Dashlets are defined by editable properties that vary depending on the dashlet type.
Types of dashlet include reports, text elements, filters, and external web content.
Data Island
A single join tree or a table without joins in a Domain. A Domain may contain several data islands, but when
creating an Ad Hoc view from a Domain, you can only select one of them to be available in the view.
Data Policy
In JasperReports Server, a setting that determines how the server processes and caches data used by Ad Hoc
reports. Select your data policies by clicking Manage > Server > Settings Ad Hoc Settings. By default, this
setting is only available to the superuser account.
Data Source
Defines the connection properties that JasperReports Server needs to access data. The server transmits queries to
data sources and obtains datasets in return for use in filling reports and previewing Ad Hoc reports.
JasperReports Server supports JDBC, JNDI, and Bean data sources; custom data sources can be defined as well.
Dataset
A collection of data arranged in columns and rows. Datasets are equivalent to relational results sets and the
JRDataSource type in the JasperReports Library.
Datatype
In JasperReports Server, a datatype is used to characterize a value entered through an input control. A datatype
must be of type text, number, date, or date-time. It can include constraints on the value of the input, for example
maximum and minimum values. As such, a datatype in JasperReports Server is more structured than a datatype
in most programming languages.
Denormalize
A process for creating table joins that speeds up data retrieval at the cost of having duplicate row values
between some columns.
Derived Table
In a Domain, a derived table is defined by an additional query whose result becomes another set of items
available in the Domain. For example, with a JDBC data source, you can write an SQL query that includes
complex functions for selecting data. You can use the items in a derived table for other operations on the
Domain, such as joining tables, defining a calculated field, or filtering. The items in a derived table can also be
referenced in the Domain's security file and locale bundles.
Dice
An OLAP operation to select columns.
Dimension
A categorization of the data in a cube. For example, a cube that stores data about sales figures might include
dimensions such as time, product, region, and customer's industry.
Domain
A virtual view of a data source that presents the data in business terms, allows for localization, and provides
data-level security. A Domain is not a view of the database in relational terms, but it implements the same
functionality within JasperReports Server. The design of a Domain specifies tables in the database, join clauses,
calculated fields, display names, and default properties, all of which define items and sets of items for creating
Ad Hoc reports.
Domain Topic
A Topic that is created from a Domain by the Data Chooser. A Domain Topic is based on the data source and
items in a Domain, but it allows further filtering, user input, and selection of items. Unlike a JRXML-based
Topic, a Domain Topic can be edited in JasperReports Server by users with the appropriate permissions.
Drill
To click on an element of an OLAP view to change the data that is displayed:
• Drill down. An OLAP operation that exposes more detailed information down the hierarchy levels by
delving deeper into the hierarchy and updating the contents of the navigation table.
• Drill through. An OLAP operation that displays detailed transactional data for a given aggregate measure.
Click a fact to open a new table beneath the main navigation table; the new table displays the low-level
data that constitutes the data that was clicked.
• Drill up. An OLAP operation for returning the parent hierarchy level to view to summary information.
Eclipse
An open source Integrated Development Environment (IDE) for Java and other programming languages, such as
C/C++.
ETL
Extract, Transform, Load. A process that retrieves data from transactional systems, and filters and aggregates the
data to create a multidimensional database. Generally, ETL prepares the database that your reports will access.
The Jaspersoft ETL product lets you define and schedule ETL processes.
Fact
The specific value or aggregate value of a measure for a particular member of a dimension. Facts are typically
numeric.
Field
A field is equivalent to a column in the relational database model. Fields originate in the structure of the data
source, but you may define calculated fields in a Domain or custom fields in the Ad Hoc Editor. Any type of
field, along with its display name and default formatting properties, is called an item and may be used in the Ad
Hoc Editor.
Frame
In Jaspersoft Studio, a frame is a rectangular element that can contain other elements and optionally draw a
border around them. Elements inside a frame are positioned relative to the frame, not to the band, and when you
move a frame, all the elements contained in the frame move together. A frame automatically stretches to fit its
contents.
Group
In a report, a group is a set of data rows that have an identical value in a designated field.
• In a table, the value appears in a header and footer around the rows of the group, while the other fields
appear as columns.
• In a chart, the field chosen to define the group becomes the independent variable on the X axis, while the
other fields of each group are used to compute the dependent value on the Y axis.
Hierarchy Level
In an OLAP cube, a member of a dimension containing a group of members.
Input Control
A button, check box, drop-down list, text field, or calendar icon that allows users to enter a value when running
a report or viewing a dashboard that accepts input parameters. For JRXML reports, input controls and their
associated datatypes must be defined as repository objects and explicitly associated with the report. For
Domain-based reports that prompt for filter values, the input controls are defined internally. When either type of
report is used in a dashboard, its input controls are available to be added as special content.
Item
When designing a Domain or creating a Topic based on a Domain, an item is the representation of a database
field or a calculated field along with its display name and formatting properties defined in the Domain. Items
can be grouped in sets and are available for use in the creation of Ad Hoc reports.
JasperReport
A combination of a report template and data that produces a complex document for viewing, printing, or
archiving information. In the server, a JasperReport references other resources in the repository:
• The report template (in the form of a JRXML file)
• Information about the data source that supplies data for the report
• Any additional resources, such as images, fonts, and resource bundles referenced by the report template.
The collection of all the resources that are referenced in a JasperReport is sometimes called a report unit. End
users usually see and interact with a JasperReport as a single resource in the repository, but report creators must
define all of the components in the report unit.
JasperReports IO
An HTTP-based reporting service for JasperReports Library that provides a REST API for running, exporting,
and interacting with reports and a JavaScript API for embedding reports and their input controls into your web
pages and web applications.
JasperReports Library
An embeddable, open source, Java API for generating a report, filling it with current data, drawing charts and
tables, and exporting to any standard format (HTML, PDF, Excel, CSV, and others). JasperReports processes
reports defined in JRXML, an open XML format that allows the report to contain expressions and logic to
control report output based on run-time data.
JasperReports Server
A commercial open source, server-based application that calls the JasperReports Library to generate and share
reports securely. JasperReports Server authenticates users and lets them upload, run, view, schedule, and send
reports from a web browser. Commercial versions provide metadata layers, interactive report and dashboard
creation, and enterprise features such as organizations and auditing.
Jaspersoft Studio
A commercial open source tool for graphically designing reports that leverage all features of the JasperReports
Library. Jaspersoft Studio lets you drag and drop fields, charts, and sub-reports onto a canvas, and also define
parameters or expressions for each object to create pixel-perfect reports. You can generate the JRXML of the
report directly in Jaspersoft Studio, or upload it to JasperReports Server. Jaspersoft Studio is implemented in
Eclipse.
Jaspersoft ETL
A graphical tool for designing and implementing your data extraction, transforming, and loading (ETL) tasks. It
provides hundreds of data source connectors to extract data from many relational and non-relational systems.
Then, it schedules and performs data aggregation and integration into data marts or data warehouses that you
use for reporting.
Jaspersoft OLAP
A relational OLAP server integrated into JasperReports Server that performs data analysis with MDX queries.
The product includes query builders and visualization clients that help users explore and make sense of
multidimensional data. Jaspersoft OLAP also supports XML/A connections to remote servers.
Jaspersoft Studio
An open source tool for graphically designing reports that leverage all features of the JasperReports Library.
Jaspersoft Studio lets you drag and drop fields, charts, and sub-reports onto a canvas, and also define parameters
or expressions for each object to create pixel-perfect reports. You can generate the JRXML of the report directly
in Jaspersoft Studio, or upload it to JasperReports Server. Jaspersoft Studio is implemented in Eclipse.
JavaBean
A reusable Java component that can be dropped into an application container to provide standard functionality.
JDBC
Java Database Connectivity. A standard interface that Java applications use to access databases.
JNDI
Java Naming and Directory Interface. A standard interface that Java applications use to access naming and
directory services.
Join Tree
In Domains, a collection of joined tables from the actual data source. A join is the relational operation that
associates the rows of one table with the rows of another table based on a common value in given field of each
table. Only the fields in a same join tree or calculated from the fields in a same join tree may appear together in
a report.
JPivot
An open source graphical user interface for OLAP operations. For more information, visit
http://jpivot.sourceforge.net/.
JRXML
An XML file format for saving and sharing reports created for the JasperReports Library and the applications
that use it, such as Jaspersoft Studio and JasperReports Server. JRXML is an open format that uses the XML
standard to define precisely all the structure and configuration of a report.
Level
Specifies the scope of an aggregate function in an Ad Hoc view. Level values include Current (not available for
PercentOf), ColumnGroup, ColumnTotal, RowGroup, RowTotal, Total.
MDX
Multidimensional Expression Language. A language for querying multidimensional objects, such as OLAP (On
Line Analytical Processing) cubes, and returning cube data for analytical processing. An MDX query is the
query that determines the data displayed in an OLAP view.
Measure
Depending on the context:
• In a report, a formula that calculates the values displayed in a table's columns, a crosstab's data values, or a
chart's dependent variable (such as the slices in a pie).
• In an OLAP view, a formula that calculates the facts that constitute the quantitative data in a cube.
Mondrian
A Java-based, open source multidimensional database application.
Mondrian Connection
An OLAP client connection that consists of an OLAP schema and a data source. OLAP client connections
populate OLAP views.
Mondrian Schema Editor
An open source Eclipse plug-in for creating Mondrian OLAP schemas.
Mondrian XML/A Source
A server-side XML/A source definition of a remote client-side XML/A connection used to populate an OLAP
view using the XML/A standard.
MySQL
An open source relational database management system. For information, visit http://www.mysql.com/.
Navigation Table
The main table in an OLAP view that displays measures and dimensions as columns and rows.
ODBO Connect
Jaspersoft ODBO Connect enables Microsoft Excel 2003 and 2007 Pivot Tables to work with Jaspersoft OLAP
and other OLAP servers that support the XML/A protocol. After setting up the Jaspersoft ODBO data source,
business analysts can use Excel Pivot Tables as a front-end for OLAP analysis.
OLAP
On Line Analytical Processing. Provides multidimensional views of data that help users analyze current and past
performance and model future scenarios.
OLAP Client Connection
A definition for retrieving data to populate an OLAP view. An OLAP client connection is either a direct Java
connection (Mondrian connection) or an XML-based API connection (XML/A connection).
OLAP Schema
A metadata definition of a multidimensional database. In Jaspersoft OLAP, schemas are stored in the repository
as XML file resources.
OLAP View
Also called an analysis view. A view of multidimensional data that is based on an OLAP client connection and
an MDX query. Unlike Ad Hoc views, you can directly edit an OLAP view's MDX query to change the data
and the way they are displayed. An OLAP view is the entry point for advanced analysis users who want to
write their own queries. Compare Ad Hoc View.
Organization
A set of users that share folders and resources in the repository. An organization has its own user accounts, roles,
and root folder in the repository to securely isolate it from other organizations that may be hosted on the same
instance of JasperReports Server.
Organization Admin
Also called the organization administrator. A user in an organization with the privileges to manage the
organization's user accounts and roles, repository permissions, and repository content. An organization admin
can also create suborganizations and mange all of their accounts, roles, and repository objects. The default
organization admin in each organization is the jasperadmin account.
Outlier
A fact that seems incongruous when compared to other member's facts. For example, a very low sales figure or a
very high number of help desk tickets. Such outliers may indicate a problem (or an important achievement) in
your business. The analysis features of Jaspersoft OLAP excel at revealing outliers.
Parameter
Named values that are passed to the engine at report-filling time to control the data returned or the appearance
and formatting of the report. A report parameter is defined by its name and type. In JasperReports Server,
parameters can be mapped to input controls that users can interact with.
Pivot
To rotate a crosstab such that its row groups become column groups and its column groups become rows. In the
• In JasperReports Server, the repository is the tree structure of folders that contain all saved reports,
dashboards, OLAP views, and resources. Users access the repository through the JasperReports Server web
interface or through Jaspersoft Studio. Applications can access the repository through the web service API.
Administrators use the import and export utilities to back up the repository contents.
• In JasperReports IO, the repository is where all the resources needed to create and run reports are stored. The
repository can be stored in a directory on the host computer or in an S3 bucket hosted by Amazon Web
Services. Users access the repository through a file browser on the host machine or through the AWS
console.
Resource
In JasperReports Server, anything residing in the repository, such as an image, file, font, data source, Topic,
Domain, report element, saved report, report output, dashboard, or OLAP view. Resources also include the
folders in the repository. Administrators set user and role-based access permissions on repository resources to
establish a security policy.
Role
A security feature of JasperReports Server. Administrators create named roles, assign them to user accounts, and
then set access permissions to repository objects based on those roles. Certain roles also determine what
functionality and menu options are displayed to users in the JasperReports Server interface.
S3 Bucket
Cloud storage system for Amazon Web Services. JasperReports IO can use an S3 bucket to store files for its
repository.
Schema
A logical model that determines how data is stored. For example, the schema in a relational database is a
description of the relationships between tables, views, and indexes. In Jaspersoft OLAP, an OLAP schema is the
logical model of the data that appears in an OLAP view; they are uploaded to the repository as resources. For
Domains, schemas are represented in XML design files.
Schema Workbench
A graphical tool for easily designing OLAP schemas, data security schemas, and MDX queries. The resulting
cube and query definitions can then be used in Jaspersoft OLAP to perform simple but powerful analysis of
large quantities of multi-dimensional data stored in standard RDBMS systems.
Set
In Domains and Domain Topics, a named collection of items grouped together for ease of use in the Ad Hoc
Editor. A set can be based on the fields in a table or entirely defined by the Domain creator, but all items in a
set must originate in the same join tree. The order of items in a set is preserved.
Slice
An OLAP operation for filtering data rows.
SQL
Structured Query Language. A standard language used to access and manipulate data and schemas in a
relational database.
Stack
A collection of Amazon Web Services resources you create and delete as a single unit.
System Admin
Also called the system administrator. A user who has unlimited access to manage all organizations, users, roles,
repository permissions, and repository objects across the entire JasperReports Server instance. The system admin
can create root-level organizations and manage all server settings. The default system admin is the superuser
account.
Topic
A JRXML file created externally and uploaded to JasperReports Server as a basis for Ad Hoc reports. Topics are
created by business analysts to specify a data source and a list of fields with which business users can create
reports in the Ad Hoc Editor. Topics are stored in the Ad Hoc Components folder of the repository and
displayed when a user launches the Ad Hoc Editor.
Transactional Data
Data that describe measurable aspects of an event, such as a retail transaction, relevant to your business.
Transactional data are often stored in relational databases, with one row for each event and a table column or
field for each measure.
User
Depending on the context:
• A person who interacts with JasperReports Server through the web interface. There are generally three
categories of users: administrators who install and configure JasperReports Server, database experts or
business analysts who create data sources and Domains, and business users who create and view reports and
dashboards.
• A user account that has an ID and password to enforce authentication. Both people and API calls accessing
the server must provide the ID and password of a valid user account. Roles are assigned to user accounts to
determine access to objects in the repository.
View
Several meanings pertain to JasperReports Server:
• An Ad Hoc view. See Ad Hoc View.
• An OLAP view. See OLAP View.
• A database view. See http://en.wikipedia.org/wiki/View_%28database%29.
Virtual Data Source
A virtual data source allows you to combine data residing in multiple JDBC and/or JNDI data sources into a
single data source that can query the combined data. Once you have created a virtual data source, you create
Domains that join tables across the data sources to define the relationships between the data sources.
WCF
Web Component Framework. A low-level GUI component of JPivot. For more information, see
http://jpivot.sourceforge.net/wcf/index.html.
Web Services
A SOAP (Simple Object Access Protocol) API that enables applications to access certain features of
JasperReports Server. The features include repository, scheduling and user administration tasks.
XML
eXtensible Markup language. A standard for defining, transferring, and interpreting data for use across any
number of XML-enabled applications.
XML/A
XML for Analysis. An XML standard that uses Simple Object Access protocol (SOAP) to access remote data
sources. For more information, see http://www.xmla.org/.
XML/A Connection
A type of OLAP client connection that consists of Simple Object Access Protocol (SOAP) definitions used to
access data on a remote server. OLAP client connections populate OLAP views.
A authorization
defined 9
AbstractExternalSetupProcessor class 104
of external users 18
Acegi Security. See Spring Security. 8
administrative user C
mapping statically 38, 62, 77, 94
CAS
with LDAP 37, 46
authentication overview 56
adminUsernames property 38, 62, 77, 94
beans 60
alwaysRequestOrgIdOnLoginForm property 82
certificates 58-59
authentication
hiding Log Out link 67
anonymous 9
login page 57
CAS overview 56
mapping to multiple organizations 66
credentials 9
organizations 65
defined 9
overview 55
deployment procedure 19
retrieving roles from an external data source 63
external, defined 9
setting organizations using a JDBC database 66
internal 15
single sign-on 55, 57
LDAP overview 25
specifying a single organization 67
token-based authentication overview 85
Spring Security customization 56, 59
authentication manager
test server 58
LDAP 28
Ticket Granting Ticket cookie 57
token-based authentication 88
website 58
authentication provider
casJDBCUserDetailsService bean
LDAP 28
authoritiesByUsernameQuery property 63
token-based authentication 88
dataSource property 63
authenticationManager bean
detailsQuery property 66
with internal authentication 102
usersByUsernameQuery property 63
authenticationProcessingFilter bean
casServiceProperties bean
with internal authentication 102
sendRenew property 61
authoritiesByUsernameQuery property 63
service property 61
Central Authentication Service. See CAS. 55
J with CAS 66
ldapExternalUserProcessor bean
Jaspersoft OLAP prerequisites 7
excludeRootDn property 41
JIAuthenticationSynchronizer bean
organizationRDNs property 41
with internal authentication 17
rootOrganizationId property 41
JSBindAuthenticator class
rootOrganizationRolesMap property 37
example 32
Lightweight Directory Access Protocol. See LDAP. 25
userDnPatterns property 32
logging 13
JSDefaultLdapAuthoritiesPopulator class
login page
branch DN value 35
external database 70, 82
example 35
hiding Log Out link for CAS 67
groupRoleAttribute property 35
with CAS 57
groupSearchFilter property 35
with LDAP 26
searchSubtree property 35
logoutUrl property 61
JSPreAuthenticatedAuthenticationProvider bean 88
M
K
Microsoft Active Directory
keytool utility 58
configuring user search 46
L following referrals 47
PartialResultException 47
LDAP
sAMAccountName attribute 46
administrative users 37, 46
with LDAP 46
beans 28
MTAbstractExternalProcessor class 104
bind authentication 31-32
mtExternalUserSetupProcessor 88
login page 26
mtExternalUserSetupProcessor bean
matching RDN patterns 31-32
organizationRoleMap property 37
Microsoft Active Directory 46
mtUserAuthorityServiceTarget bean
organization mapping 41
with LDAP 42
overview 25
roles 35 O
searching for usernames 32-33
organizationRDNs property 41
setting connection parameters 30
organizationRoleMap property 37, 63, 76, 92
single sign-on 25
organizations
static role assignment 38
managing external organizations 23
troubleshooting 47
overview 16
URL 30
specifying a single organization 67
users with same login name 34
with CAS 65
with default internal authentication 46
with LDAP 41
ldapAuthenticationManager bean 28
ldapAuthenticationProvider bean 28, 36 P
ldapContextSource bean 28
PartialResultException
constructor-arg value 30
Microsoft Active Directory 47
example 30
password property 74
ldapExternalTenantProcessor bean
password property (LDAP) 31
defaultOrganization property 42, 44-45, 67, 82, 98
PasswordComparisonAuthenticator class 32
multiple organizations 41
preAuthenticatedManager bean 88