jasperreports server authentication cookbook

COOKBOOK

AuthenticationCookbook 4.0

JasperReports Server Authentication Cookbook

2

Copyright © 2011 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo, JasperAnalysis, JasperServer, JasperETL, JasperReports, JasperReports Server, and iReport, are trademarks and/or registered trademarks of Jaspersoft Corporation in the United States and in jurisdictions throughout the world. All other company and product names are or may be trade names or trademarks of their respective owners.

This is version 0411-JSP40-4 of the JasperReports Server Authentication Cookbook.

Table of Contents

TABLE OF CONTENTS

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1 JasperReports Server Version Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.2 Overview and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 Spring Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.4 Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.5 Default Internal Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.5.1 Step 1: Receiving a Page Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.5.2 Step 2: Redirecting to the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.5.3 Step 3: Processing Login Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.5.4 Step 4: Sending the Requested Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.6 Structures and Processes of External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.6.1 Multiple Organizations in JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.6.2 External Users in the Internal Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.6.3 Synchronization of External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.6.4 Synchronization of Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.6.5 Initialization of JasperReports Server for External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.6.6 Maintenance of External Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.7 Customization of External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2 LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.1 Overview of External LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2 Configuring JasperReports Server for LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.2.1 Files to Modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2.2 Beans to Configure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2.3 LDAP and Administrative Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.3 Adding the ldapAuthenticationProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.4 Setting the LDAP Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.5 Performing LDAP User Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.5.1 Specifying userDnPatterns Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.5.2 Specifying userSearch Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3


2.5.3 LDAP Search for Multiple Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.5.4 Alternate to Bind Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.6 Mapping the User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.7 Mapping the User Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2.7.1 Mapping to a Single Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.7.2 Mapping to Multiple Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.7.3 Mapping Roles to System Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.8 Restarting JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.9 Authentication with Computer Associates SiteMinder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.10 Authentication with Microsoft Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 3 CAS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.1 CAS Server for Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.2 Overview of External CAS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3 Configuring JasperReports Server for CAS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.3.1 Files to Modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.3.2 Beans to Configure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.4 Configuring Java to Trust the CAS Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.5 Modifying the Spring Security Filter Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.6 Configuring the Filters for CAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.7 Adding the casAuthenticationProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.8 Configuring the CAS Authentication Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.9 Setting the User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.10 Setting the User Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433.11 Restarting JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.12 Detailed Protocol Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4

Introduction

CHAPTER 1 INTRODUCTION

JasperReports Server builds on the JasperReports Library as a comprehensive family of Business Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end BI suite utilizing common metadata and providing shared services, such as security, a repository, and scheduling. JasperReports Server exposes comprehensive public interfaces enabling seamless integration with other applications and the capability to easily add custom functionality.

This cookbook describes the configuration of JasperReports Server to use an external authentication mechanism in place of the built-in authentication of users. This document covers the following authentication mechanisms:

LDAP – Lightweight Directory Access ProtocolCAS – Central Authentication Service

The benefits of having JasperReports Server perform external authentication include:Allowing centralized identity management within your enterprise.Enabling single sign-on capabilities if the authentication mechanism supports it.

For deployments that also include the Jaspersoft OLAP component (formerly known as JasperAnalysis) within JasperReports Server, external authentication applies transparently to Jaspersoft OLAP users.

The procedures in this document assume you are familiar with JasperReports Server installation, deployment, and administration. You must have system administrator privileges within JasperReports Server and its application server, as well as read and write access to their files on the host.

If you want to extend your knowledge of Jaspersoft BI software, our Ultimate Guides document its advanced features and configuration. They also include best practice recommendations and numerous examples. The guides are available as downloadable PDFs. Community project users can purchase individual guides or bundled documentation packs from the Jaspersoft online store. Professional and Enterprise customers can download them from the support portal.

This chapter contains the following sections:JasperReports Server Version SupportedOverview and TerminologySpring SecurityConfiguration FilesDefault Internal AuthenticationStructures and Processes of External AuthenticationCustomization of External Authentication

5

http://www.jaspersoft.com/ultimate-guides

http://support.jaspersoft.com


1.1 JasperReports Server Version SupportedThis document applies to JasperReports Server 4.0.1, the most recent version at publication time. The instructions in this cookbook refer to files that were added or modified in version 4.0.1, and instructions were tested on version 4.0.1. If you have version 4.0.0, you must upgrade to 4.0.1 to use the features and files described in this document.

While the overall architectural for external authentication has not changed since version 3.5.x, there are significant implementation differences. If you are running an earlier version of JasperReports Server, then known as JasperServer, refer to the corresponding version of the External Authentication Cookbook (either 3.5 or 3.7).

This document applies to the community and commercial editions of JasperReports Server. The commercial editions (Professional and Enterprise) have an architecture that supports multiple organizations. Additional instructions are included for the cases of no organizations, a single organization, and multiple organizations.

1.2 Overview and TerminologyAuthentication 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 is a process that ensures that every page is secure, either viewed by a verified user or denied access until valid credentials are provided.

JasperReports Server users are either people who access the web-based interface or applications that access the same content through web services. Authentication for the two types of access is slightly different but operates on the same principles. For simplicity, this document considers users to be people accessing the web-based interface.

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 MySQL 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 they may be on the same database server.

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 is 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 usage 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.

Authentication happens only once at the beginning of the user’s session. After a user is authenticated, 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 the user can access pages throughout the application. The principal object also stores the roles and organization ID of the user, which are required for authorization within JasperReports Server.

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 that 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 that authorization can proceed internally. However, profile attributes cannot be mapped from the external authority and therefore cannot be used when implementing external authentication.

When the session of an external user is established, his current organization and roles are mapped into the principal object. The first time an external user logs in, the synchronization mechanism creates his organization folder, roles and user account in the internal database. The server uses these structures to enforce authorization for the external user in the same manner 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.

6

Introduction

1.3 Spring SecurityJasperReports Server relies on Spring Security to provide the mechanisms that authenticate and authorize users. Spring Security is integrated with the Spring Framework, the open source Java application platform that the server is built upon. JasperReports Server embeds the Spring Security functionality to perform actions such as maintaining user sessions, restricting access to pages, and enforcing role-based permissions. JasperReports Server also extends Spring Security to implement certain features, for example the organization architecture in commercial editions.

Like all of the Spring Framework, Spring Security is configured through Java beans defined in XML files. The default configuration of Spring Security in JasperReports Server performs internal authentication as described in the section 1.5, “Default Internal Authentication,” on page 8.

To implement external authentication, you need to change the configuration of Spring Security in JasperReports Server to use different beans. External authentication with LDAP and CAS are common configurations, and the necessary beans are already included in the JasperReports Server installation. The configuration for each protocol is given in the chapter devoted to that protocol.

This document explains only the mechanisms and beans of Spring Security that relate to internal and external authentication in JasperReports Server. For a more advanced understanding of Spring Security, see the references listed in section 1.7, “Customization of External Authentication,” on page 17.

1.4 Configuration FilesAll Spring Security configuration files are located in the JasperReports Server web application that is deployed in an application server. In general, all of the configuration files for external authentication are located in the <js-webapp>/WEB-INF/ directory. Unless otherwise specified, all file names mentioned in this document are located in this directory.

Depending on your deployment and your needs, there are several ways to work with configuration files, which in turn determine the location of <js-webapp> that you use:

Deployment <js-webapp> File Location

Installed server Once you have installed your server, either through a platform installer or any other deployment, the configuration files are in the deployed web application running 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 files are located in:<js-webapp> = <js-install>/apache-tomcat/webapps/jasperserver[-pro]After modifying the configuration files, restart the application server to use the settings.

WAR file distribution When you download the WAR file distribution, you can customize your deployment of JasperReports Server and possibly install it on several machines. The WAR file distribution also includes the configuration files in the following location:<js-webapp> = <js-install>/jasperserver[-pro].warAfter modifying the WAR file distribution, you need to redeploy it to your application server, as described in the JasperReports Server Installation Guide. But every time you redeploy your modified WAR file, external authentication is pre-configured.

Source code If you work with the JasperReports Server source code, it also 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 configuration files in the source code are located in:<js-webapp> = <js-src>/jasperserver/jasperserver-war/src/main/webappWhen building the source, these files are copied into the WAR file that you must then deploy into a running application server. See the JasperReports Server Source Build Guide for more information.

7


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.

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:

1.5 Default Internal AuthenticationUnderstanding how JasperReports Server performs internal authentication can help you implement external authentication. The following diagram shows the general steps involved in the default internal authentication:

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

Often, when working with the WAR file distribution or source code, you also modify the files in an installed server for testing. But after testing, you copy the changes into your WAR file or source code and redeploy or rebuild your server.

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>

Figure 1-1 General Steps of Internal Authentication

JasperReports ServerPage requestRedirect to login pageLogin credentialsRequested content

Principal object Internal userdatabaseincl. roles

(subj. to authorization)

8

Introduction

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 that are returned are based on the organization ID and roles in the principal object.

The following sections explain the default configuration of the Spring Security beans that are used in each step.

1.5.1 Step 1: Receiving a Page RequestWhen JasperReports Server receives a request, from either a person using the web interface or an application using the web services, it is processed by the Spring Security filter chain. The filter chain is a list of beans, called filters, that are invoked in sequence to determine the security context and allow or deny the request. Different URLs can have different filter chains, but filters are modular and often reused in multiple chains.

The flow of execution for Spring Security starts in the securityFilter bean that is configured in the web.xml file. As with all J2EE servlet filters, the securityFilter is invoked for every HTTP request for paths in this web application, whether the request comes from users or applications.

The securityFilter calls the FilterChainProxy bean that is configured as follows in the applicationContext-security-web.xml file:

The configuration of the filterInvocationDefinitionSource property of the filterChainProxy bean gives a list of URL request patterns, and for each pattern a chain of filters. Before the patterns, there are two directives that determine how URLs are matched: one to make URLs case insensitive, the other to simplify the pattern string. Among the patterns, the first ones take precedence, so the most specific ones are listed before more general ones. The pattern associated with the last expression is usually /** with the Apache Ant pattern type, because it matches anything that wasn’t caught by another pattern.

The /xmla and /services/** patterns represent the XML for Analysis (XML/A) servlet and the web services, respectively. They are configured with a set of filters designed to receive SOAP requests from other servers. All other URLs matched by the

<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy"><property name="filterInvocationDefinitionSource">

<value>

CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISONPATTERN_TYPE_APACHE_ANT

/xmla=httpSessionContextIntegrationFilter,${bean.loggingFilter},${bean.basicProcessingFilter},JIAuthenticationSynchronizer,anonymousProcessingFilter,basicAuthExceptionTranslationFilter,filterInvocationInterceptor

/services/**=httpSessionContextIntegrationFilter,${bean.loggingFilter},${bean.portletAuthenticationProcessingFilter},${bean.basicProcessingFilter},${bean.passwordExpirationProcessingFilter},JIAuthenticationSynchronizer,anonymousProcessingFilter,wsBasicAuthExceptionTranslationFilter,filterInvocationInterceptor

/**=httpSessionContextIntegrationFilter,${bean.loggingFilter},${bean.userPreferencesFilter},${bean.authenticationProcessingFilter},${bean.userPreferencesFilter},${bean.basicProcessingFilter},requestParameterAuthenticationFilter,JIAuthenticationSynchronizer,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor,switchUserProcessingFilter

</value></property>

</bean>

9


final pattern are designed for people using web browsers and have a different set of filters; for example, only people are asked to proceed to the login page.

The ${property} syntax encloses property names that correspond to bean names defined in the js.spring.properties file. JasperReports Server uses this mechanism to provide a layer of abstraction in the applicationContext-security-web.xml file, in particular for filters that have different beans between community and commercial editions. For simplicity, filters are referred to by their abstract name, for example loggingFilter instead of ${bean.loggingFilter} or the actual bean name in js.spring.properties.

1.5.2 Step 2: Redirecting to the Login PageAs the request is being processed, Spring Security within JasperReports Server calls each of the filters in the chain. For completeness, the following list describes all of the standard filter beans in the order they are activated:1. httpSessionContextIntegrationFilter – Stores the SecurityContext in the HttpSession.2. loggingFilter – Sets the audit context for each request (auditing is available in certain commercial editions only).3. userPreferencesFilter – Handles the optional parameters on the login page: locale, time zone, and changing the

password (when enabled).4. 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 entered by the user. See Step 3: Processing Login Credentials below.

5. basicProcessingFilter – Handles HTTP BASIC style authentication, where the username and password are passed as an HTTP header.

6. requestParameterAuthenticationFilter – Collects the user name and password, then runs the Spring authentication chain; redirects to the login failure page in case of authentication failure.

7. JIAuthenticationSynchronizer – A custom filter that synchronizes the information in the user database with the principal object in memory. This filter takes no action during default authentication, but it remains active to enable portlet users and external authentication. For more information, see 1.6.3, “Synchronization of External Users,” on page 12.

8. anonymousProcessingFilter – Marks the user as anonymous if no other authentication occurred.9. exceptionTranslationFilter – Sets a 403 Forbidden HTTP response code if the user is not authenticated to view

the requested page.10. filterInvocationInterceptor – Integrates the filter chain with other Spring components.11. switchUserProcessingFilter – Enables the “Log in as” feature for administrators.

In the case of a user requesting a page, the authenticationProcessingFilter in step 4 detects that the user is not yet authenticated and redirects to the login page.

1.5.3 Step 3: Processing Login CredentialsWhen the user submits credentials from the login page, either directly or after being redirected by the filter chain, the authenticationProcessingFilter processes the login request. To do so, it calls the authenticationManager bean provided with Spring Security. The configuration of the authenticationManager bean in the applicationContext-security.xml file establishes the different methods by which a user can be authenticated.

In the default installation of JasperReports Server, the authenticationManager bean is configured as follows:

<bean id="authenticationManager"class="org.springframework.security.providers.ProviderManager">

<property name="providers">

<list>

<ref bean="${bean.daoAuthenticationProvider}"/>

<ref local="anonymousAuthenticationProvider"/></list>

</property>

</bean>

10

Introduction

The list of authentication providers determines the authentication mechanisms that are invoked:daoAuthenticationProvider – Compares the organization ID, username, and password from the login page to those stored in the internal database. This is the server’s default form of authentication. anonymousAuthenticationProvider – Grants anonymous access to certain pages; by default, it only grants access to the login page.

To configure an external authentication mechanism, start by editing this list to use alternate providers as shown in section 2.3, “Adding the ldapAuthenticationProvider,” on page 22.

1.5.4 Step 4: Sending the Requested ContentWhen the authentication provider has successfully checked the user’s credentials, the authenticationManager returns control to the authenticationProcessingFilter, but now the principal object has been created to establish the user session. The other filters in the chain can detect the user session and usually have no further action to perform.

The JIAuthenticationSynchronizer does perform a significant task for external authentication, as explained in the next section. But in the case of internal authentication, the job of the filter chain is done when the principal object has been created.

The user is now logged in with an active session. The server processes the requested URL, or in the case of a direct login, replies with the home page that is appropriate for the user. In fulfilling any request now, the server knows the identity of the user and generates content based on the user’s organization ID and roles found in the principal object. For example, administrators see a home page with items to manage the server, and users within each organization can only see repository objects in their organization’s folder.

1.6 Structures and Processes of External AuthenticationThe flexibility of Spring Security makes it easy to configure the security system for external authentication. However, the number of settings makes configuration somewhat daunting. This cookbook presents the most common scenarios for implementing external authentication, namely Lightweight Directory Access Protocol (LDAP) and Central Authentication Service (CAS).

External authentication is implemented and configured differently for each external authority, yet there are many concepts that appear in every configuration. The following sections present some of the structures and processes that are common to all forms of external authentication.

1.6.1 Multiple Organizations in JasperReports ServerCommercial editions have an architecture that allows 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, all of which are invisible to other organizations. For information about deploying multiple organizations, see the JasperReports Server Administrator Guide.

When you deploy JasperReports Server, there are three distinct cases with respect to the organization architecture:

When fulfilling any page request after the user is authenticated, the server still processes the entire filter chain in Spring Security. However, in Step 1: Receiving a Page Request, the user session is recognized by its active principal object, no filter is triggered, and the server goes on to generate the content for the request.

Edition and Usage Impact on External Authentication Configuration

Commercial edition with multiple organizations

JasperReports Server provides additional beans to map external users into separate organizations. Therefore, configuring external authentication for multiple organizations requires extra steps. In the chapter for each authentication mechanism, look for the additional section to support mapping the organization IDs from multiple organizations. Also look for information about how organizations are synchronized in section 1.6.3, “Synchronization of External Users,” on page 12. All other configuration for external authentication remains the same.

11


1.6.2 External Users in the Internal DatabaseWhen performing external authentication, JasperReports Server obtains all the information about a user from the external authority. After the authenticationProvider for the external authority has replied and the AuthenticationProcessingFilter is finished, the user session is represented by a principal object in run-time memory. This principal object includes any roles determined during the external authentication, as well as an organization ID, if necessary.

In order to create and enforce permissions, JasperReports Server must store the information about users, roles, and organizations in the internal database. Thus, for each externally-defined user, role, and organization, the server creates a local user account, role definition, and organization folder. This process is called synchronization.

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 the purpose of the JIAuthenticationSynchronizer filter.Permissions in the repository must be initialized manually for the external users, roles, and organizations.Maintenance of the external users is necessary only when creating or deleting roles and when creating new organizations in the external authority.

You must initialize the permissions first, during the deployment of JasperReports Server in a production environment, but you must understand the synchronization process in order to perform the initialization. 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.

1.6.3 Synchronization of External UsersWhen a user is authenticated by an external authority, JasperReports Server has the principal object that contains the username, role names, and organization ID, if necessary, of the external user. The JIAuthenticationSynchronizer filter uses this information to automatically update or create the corresponding structures in the internal database:

Commercial edition with no organizations

A single default organization mimics the behavior of JasperReports Server without organizations. JasperReports Server has the organization architecture, but never more than one organization. This has no impact on external authentication configuration for two reasons:

JasperReports Server provides custom beans for Spring Security to handle the organization architecture, but these are not visible in the configuration files thanks to the ${bean.x} syntax. As a result, the configuration files samples in this document apply regardless of the use of organizations.The default configuration of external authentication maps all external users to the single organization. The instructions for mapping organizations apply only when you explicitly create multiple organizations.

Therefore, you can skip any section that refers to mapping the organization ID, because it is done automatically when there is a single organization.

Community Project JasperReports Server Community Project does not use the organization architecture, and the beans such as filters in Spring Security do not need to take into account any organizations when processing users and roles. However the ${bean.x} syntax hides the different bean names and allows you to configure external authentication with the same files as commercial editions. Therefore, you can use the same instructions presented in this Cookbook, except for the sections dedicated to organizations and mapping organization IDs.

Another name for multiple organizations is multi-tenancy, sometimes abbreviated mt in file and bean names. The mt prefix appears only in the commercial editions.

Edition and Usage Impact on External Authentication Configuration

12

Introduction

The organization ID can include a hierarchy of organizations to specify nested organizations. If there is no organization with the given ID, that organization is created. Any parent organizations that do not exist are created as well. Organizations are created with the templates currently defined in the repository.Role names are compared to existing roles. If an organization ID is specified, only the roles in that organization are checked. If the roles do not exist, they are created as external roles. If an organization ID is specified, they are created within that organization. See section 1.6.4, “Synchronization of Roles,” on page 13 for details about role creation.The user ID is compared to those of existing user accounts in the internal database. If an organization ID is specified, only the user IDs in that organization are checked.

If the user account exists, its list of assigned roles is synchronized as described in section 1.6.4, “Synchronization of Roles,” on page 13. The user ID can match either a previously synchronized external user or an internal user created by an administrator. It is not common to have external authentication for internal users, but it is possible.If the user does not exist, an external user account is created. If an organization ID is specified, the account is created within that organization. Finally, all of the roles in the principal object are assigned to the new user account.

For more information about organizations, roles, and user accounts, see the 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 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 the optional properties of a user, such as the email or profile attributes. The default implementation of external authentication does not populate these properties.

None of the user properties, such a full name and email address, can be modified.The external user account cannot be disabled. Administrators can delete the external user account, but this does not prevent the external user from logging in, which will create a new external user account.

After synchronization, the external user fits in coherently with all the structures and mechanisms of JasperReports Server, in particular those required to verify authorization. However, the external user account is not meant to allow user management by a JasperReports Server administrator. Nor can the external user account be used for logging 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.

1.6.4 Synchronization of RolesRoles have a complex synchronization process because they need to be updated every time an external user logs in. As with the synchronization of users and organizations, there are two phases: ensuring the mapped roles exist, and then assigning them to users.

With respect to external authentication mechanism, there are three types of roles in JasperReports Server:An internal role is a standard role created by a JasperReports Server administrator. When using organizations, the role is created within an organization. Internal roles may be assigned to users, either by administrators or by synchronization, but they can only be removed by administrators. Synchronization does not remove an internal role from a user.An external role is one created by the synchronization process of external authentication. In the administrative pages, external roles are flagged as such because they are not meant to be managed by administrators. Synchronization assigns and removes external roles from users according to the roles mapped from the external authority.A system role is one of the default roles created during the JasperReports Server installation, for example ROLE_DEMO.

In the community edition without organizations, system roles are handled exactly like internal roles above.In the commercial editions with organizations, the special system roles such as ROLE_ADMINISTRATOR are not directly available for synchronization. Unless your LDAP users are mapped to the root organization (with a null organization ID, which is not recommended), you must use the system role mapping property described in

An external authority such as LDAP contains information such as the user’s full name, email address, and profile attributes that can be mapped into the external user account. However, this requires customizing the mapping and synchronization beans. See section 1.7, “Customization of External Authentication,” on page 17.

13


section 2.7.3, “Mapping Roles to System Roles,” on page 31. In this case the mapped system roles are treated like internal roles.

For the purposes of authorization, all types of roles are identical, and the distinction is not visible on the permissions page. The administrator manages the repository by assigning permissions based on roles, regardless of the role type.

In the first phase of synchronization, the principal object has a set of role names that were mapped from role definitions in the external authority. The outcome is to have a role in JasperReports Server for each of the mapped role names. When using organizations, all roles must exist within the organization mapped for the user; roles in parent organizations never match. Here are the possibilities:

The name matches an existing internal role: synchronization uses the internal role.The name matches an existing external role: synchronization uses the external role.The name matches a system role:

In the community edition, synchronization uses the system role as it would any internal role.In commercial editions and a target organization with the null ID, synchronization uses the system role. Caution: mapping users to the null organization ID is not secure because it gives them access to all organizations.In commercial editions and any non-null target organization ID, synchronization creates a new external role in the organization with same name as the system role. Caution: roles with the same name as system roles are confusing.

The name is further mapped to a system role with the rootOrganizationRolesMap property: synchronization uses the system role.The name does not match any role: synchronization creates a new external role to use. In commercial editions, the role is created in the designated organization.

In the second phase of synchronization, the goal is to update the user to reflect the set of roles mapped from the external authority. How the synchronizer assigns and removes roles from an external user account depends on the origin of the role:

All of the roles identified or created in the first phase, internal, external, and system roles alike, are assigned to the external user. If the user account already has a role, it is kept on the account. If the user account does not have the role, it is assigned to the user by the synchronization mechanism.External roles that the user account has but which are not among those mapped and identified in the first phase are removed from the user. With this mechanism, roles that are removed from the external authority are also removed from the user account in JasperReports Server.Internal and system roles that the user account has are never removed, even if they are not among those mapped and identified in the first phase. Internal and system roles may be assigned to the user either manually by the administrator or automatically by the synchronization during a previous login, but they are never removed during synchronization.

Essentially, synchronization manages the external roles on a user account, but not the internal roles. Therefore, in order for synchronization to automatically make all roles reflect those in the external authority, you should not assign internal roles to external users manually, and you should not define internal roles that match the names of roles mapped from the external authority.

1.6.5 Initialization of JasperReports Server for External UsersKnowing how external users are synchronized, the system administrator must initialize JasperReports Server and set the permissions in the repository to provide the desired authorization.

Your deployment procedure must include the following steps:1. Configure the mapping of usernames, roles, and possibly organization IDs from your external authority into

JasperReports Server. The mapping depends on the external authentication mechanism, as described in the chapter for each mechanism.

2. Create test users in the external authority. The test users should be from every organization and have every role that you expect in your production environment.

Synchronization works the same when applied to external user accounts and internal user accounts, even if the latter is an uncommon scenario. The main difference is that internal accounts are more likely to have internal roles that the synchronization mechanism does not manage.

14

Introduction

3. If you are mapping external users to multiple organizations, log into JasperReports Server as the system administrator and prepare your organization templates and possibly themes for the new organizations.

4. Log into JasperReports Server as each of the test users. Doing so validates your configuration of the external authentication and mapping beans. When successful, it also creates the external roles and organizations that you need.

5. Log into JasperReports Server as the system administrator and:a. Ensure that the mapping and synchronization created the external users, roles, and organizations that you expect.b. Change the password of the administrator in every organization that was created automatically.

6. Initialize your repository as follows:a. If you are using multiple organizations, create additional resources in the repository, such as data sources and shared

reports, around the organization folders that were created.b. Define all of your repository permissions using the external roles that were created.

The above procedure is necessary because the external roles must exist in the internal database before you can create permissions for them. If you are using organizations, roles must be defined within organizations, so the organizations must exist as well. Optionally, you can use the administrative pages to create all the organizations that your externally authenticated users need. This allows you some additional control over the creation of the organizations, but you must ensure that their IDs match exactly the values and hierarchies that are determined by the mapping.

Due to the limitations of role synchronization described in section 1.6.4, “Synchronization of Roles,” on page 13, you cannot create internal roles for the roles that will be mapped from the external authority. All roles from the external authority must be created through test users so that they are created as external roles that can be managed automatically by the synchronization.

When your JasperReports Server enters into production, the external user accounts will be populated by the synchronization mechanism as the users log in. When the mapping is correct and consistent, the user population will have the same roles and organizations that exist in your external authority, without having to manually import users or roles into the server. And as role membership is updated in the external authority, external users are automatically synchronized in JasperReports Server.

1.6.6 Maintenance of External UsersThe advantage of an external authority is that it provides a single place to manage user accounts across applications. Due to the mapping and synchronization, you do not need to manage the external users or roles in JasperReports Server, with a few small exceptions documented in the following sections.

1.6.6.1 Managing External Users

The following table describes the impact on JasperReports Server when managing users in the external authority:

Action in ExternalUser Authority Impact on JasperReports Server

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, the user requires no changes in the server. If the user is associated with new roles, see section 1.6.6.2, “Managing External Role Definitions,” on page 16.

Updating a password JasperReports Server does not store the passwords of external users, and is not impacted by changes to user passwords or user password policies on the external authority.

Updating personal information

With the default mapping of external users, only the login name is stored in an external user account. If you configure role mapping based on personal information in the external user entry, you need to take into account 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 cannot modify this attribute in the external authority. Otherwise, the user could inadvertently or maliciously change his or her roles within JasperReports Server.

15


1.6.6.2 Managing External Role Definitions

Roles can be mapped from a variety of structures that depend on the external authority: LDAP authentication maps roles dynamically from groups, and CAS authentication specifies roles statically in configuration files. Because each external authority may have its own mechanism, this document refers to those structures collectively as role definitions.

In practice, you will find that only a subset of the role definitions in your external authority are applicable to JasperReports Server. Of those, some may be used by other applications as well, and others may be created specifically for managing users in JasperReports Server. You should identify the maintenance procedures on your enterprise-wide user authority that impact JasperReports Server and document the additional procedures for keeping JasperReports Server in sync.

The following table describes the impact on JasperReports Server when modifying role definitions in the external authority:

Changing group or role membership

Described in section 1.6.6.2, “Managing External Role Definitions,” on page 16.

Disabling or deleting a user

When the user can no longer authenticate with the external authority, he can’t access JasperReports Server. The external user account synchronized during the last user session remains in the internal database. This user account has no impact on the server; you can safely delete it, if desired.

All users, both internal and external users, are automatically assigned ROLE_USER by default. Therefore, you never need to create or map this role from your external 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 section 1.6.5, “Initialization of JasperReports Server for External Users,” on page 14.The role is not significant to users within JasperReports Server. The 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 membership

Changes in role membership are reflected the next time the role members start a new session in JasperReports Server, as described in section 1.6.3, “Synchronization of External Users,” on page 12. Roles that were previously unknown to the server are treated as new roles as described above, and roles that are no longer assigned to any user are deleted as described below.

Deleting a role If the role definition was mapped to an external role created during synchronization, external users no longer have the role, and it is removed from each external user during synchronization the next time they log in. The external role remains in the internal database, and permissions that reference the role remain in the repository. The defunct role may still be assigned to external users who have not logged in since the role was removed. This unused role has no impact on the server, and you can safely delete it.If the role definition mapped to an internally defined role in JasperReports Server, it is not removed. You must log in as an administrator to remove the role from the external users who should no longer have it. If appropriate, you should also delete the internal role. For more information, see section 1.6.4, “Synchronization of Roles,” on page 13.


16

Introduction

1.6.6.3 Managing External Organizations

The following table describes the impact on JasperReports Server when modifying organizations defined in the external authority:

1.7 Customization of External AuthenticationExternal authentication as presented in this document is a configuration of the default JasperReports Server product. All the Java classes necessary for LDAP and CAS authentication are provided, and they are invoked by adding them to the configuration files. The various options available in the server’s configuration represent the most common use cases, but cannot accommodate the entire variety of security architectures. To implement other behavior during external authentication, you must write custom classes and deploy them with the server. While such programming is beyond the scope of this document, typical customizations are suggested below and in notes throughout the text.

Spring Security and JasperReports Server are complex systems that allow many different opportunities for customization, for example:

Modifying the authentication provider to:Locate external users in different ways.Extract additional user information from the external authority.Implement custom mappings of organizations and roles.

Writing a new authentication provider to implement external authentication for a new protocol.Modifying or replacing filters to perform synchronization differently.Writing additional filters to take further action during the login sequence.

As with any design, you must determine the benefits and drawbacks in the areas of complexity, cost, and maintenance of your implementation to help you decide your preferred approach.


Adding an organization Organizations are not directly mapped to JasperReports Server, rather a new organization ID is mapped when synchronizing the first user in the organization that accesses the server. At that time, the synchronization creates the organization and creates the user within it, along with any roles assigned to the user. Determine which of the following cases applies to you:

Your organization definitions and mappings create the same role names in every organization. You should configure the organization folder templates so that 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 section 1.6.5, “Initialization of JasperReports Server for External Users,” on page 14.

Modifying an organization

Users who are added to an organization are treated as new users as described in section 1.6.6.1, “Managing External Users,” on page 15 above. Users who are removed from an organization are handled as deleted, provided they can no longer authenticate with the external authority. When users are moved to a different organization, this is the equivalent of being removed from one organization and added to another.

Deleting an organization

Because organization definitions are not mapped directly, deleting an 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.

17


For help with customizations, you can browse the JasperReports Server forum and participate in the JasperForge community:http://jasperforge.org/plugins/espforum/browse.php?group_id=112&forumid=102

If you would like the assistance of Jaspersoft’s Professional Services team, see:http://www.jaspersoft.com/jaspersoft-professional-services

If you plan to make extensive customizations, Jaspersoft recommends 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 (http://static.springsource.org/spring-security/site/index.html) and refer to the documentation for Spring Security 2.0.x:

http://static.springsource.org/spring-security/site/docs/2.0.x/reference/springsecurity.htmlhttp://static.springsource.org/spring-security/site/docs/2.0.x/reference/springsecurity.pdf (PDF)

18

http://jasperforge.org/plugins/espforum/browse.php?group_id=112&forumid=102

http://www.jaspersoft.com/jaspersoft-professional-services

http://static.springsource.org/spring-security/site/index.html

http://static.springsource.org/spring-security/site/index.html

http://static.springsource.org/spring-security/site/docs/2.0.x/reference/springsecurity.html

http://static.springsource.org/spring-security/site/docs/2.0.x/reference/springsecurity.pdf

LDAP Authentication

CHAPTER 2 LDAP AUTHENTICATION

Lightweight Directory Access Protocol (LDAP) is one of the most popular architectures for enterprise directories. By centralizing all user management in an LDAP directory, applications across the enterprise can share the same user database, and administrators do not need to duplicate user accounts in every application.

This chapter shows how the default authentication mechanism using Spring Security can be configured to perform external authentication with LDAP. As part of the authentication process, JasperReports Server also synchronizes the user information such as roles and organization ID from the LDAP structure into its own user database.

LDAP authentication does not provide single sign-on (SSO) functionality. You must implement additional mechanisms and configure their use within JasperReports Server to enable SSO with LDAP, the details of which are beyond the scope of this document. For more information, see section 1.7, “Customization of External Authentication,” on page 17.

This chapter assumes you are familiar with LDAP servers and the structure of the data they contain, in particular the format of distinguished names (DNs) and relative distinguished names (RDNs) that create structure and identify entries in LDAP.

This chapter contains the following sections:Overview of External LDAP AuthenticationConfiguring JasperReports Server for LDAP AuthenticationAdding the ldapAuthenticationProviderSetting the LDAP Connection ParametersPerforming LDAP User SearchMapping the User RolesMapping the User OrganizationRestarting JasperReports ServerAuthentication with Computer Associates SiteMinderAuthentication with Microsoft Active Directory

19


2.1 Overview of External LDAP AuthenticationThis section explains how JasperReports Server performs external authentication with an LDAP server, highlighting the differences with section 1.5, “Default Internal Authentication,” on page 8. The following diagram shows the general steps involved in external LDAP authentication:

The following steps explain the interaction between 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 replies with a redirect to the login page.Users log in with the JasperReports Server login page even though the user credentials are not verified internally.

3. The user enters a username and password. Even on a server with multiple organizations, the organization ID must be left blank because it is supplied by the external LDAP authority.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 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 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 section 1.6.3, “Synchronization of External Users,” on page 12.

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.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, 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 section 1.5, “Default Internal Authentication,” on page 8, 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.

Figure 2-1 General Steps of External LDAP Authentication

The beans that perform LDAP authentication do not map information such as the user’s full name, email address, or profile attributes that may exist in the LDAP directory. This requires customizing the mapping and synchronization beans, as described in section 1.7, “Customization of External Authentication,” on page 17.

JasperReports ServerPage requestRedirect to login pageLogin credentialsRequested content(subj. to authorization)

LDAP

Internal userdatabase

Principal objectincl. roles

20

LDAP Authentication

2.2 Configuring JasperReports Server for LDAP AuthenticationThe differences listed in the previous section reflect the changes that need to be made in the Spring Security configuration:

Add LDAP as an authentication provider in the authenticationManager bean and configure it to access your LDAP server and search for users.Configure the LDAP authentication provider to map roles and organizations, if applicable.The synchronization is automatically handled by the existing JIAuthenticationSynchronizer.

Because the response to page requests is the same as with internal authentication, there is no need to change the default filter chain. However, as user requests are processed by the filter chain, it behaves differently:

The authenticationProcessingFilter now calls the LDAP authentication provider.The JIAuthenticationSynchronizer now synchronizes every external user instead of being mostly inactive.

The following sections explain how to make the configuration changes presented above.

2.2.1 Files to ModifyAll configuration changes for external LDAP authentication are made in the following files:

<js-webapp>/WEB-INF/applicationContext-security.xml<js-webapp>/WEB-INF/applicationContext-security-web.xml<js-webapp>/WEB-INF/applicationContext-multiTenancy-security.xml in commercial editions, which have the organization architecture.

Where <js-webapp> is the location of the JasperReports Server web application in your application server, or where you are modifying the configuration files, as explained in section 1.4, “Configuration Files,” on page 7. The rest of this chapter refers to file names alone.

2.2.2 Beans to ConfigureThis section explains the beans involved in external LDAP authentication and their relationships. The beans are listed by file, roughly in the order they are invoked.

applicationContext-security.xml file:authenticationManager – Name of a bean of class ProviderManager that performs authentication; configured with:

ldapAuthenticationProvider – Bean for performing LDAP authentication, configured below.ldapContextSource – Name of a bean of class DefaultSpringSecurityContextSource; configured with the LDAP connection parameters.userSearch – Name of a bean of class FilterBasedLdapUserSearch; configured with user search parameters.ldapAuthenticationProvider – Name of a bean of class LdapAuthenticationProvider; configured with:

BindAuthenticator – Class of an unnamed bean for finding user entries; configured with:ldapContextSource – Required for accessing the LDAP server.User DN patterns and/or userSearch – Required for finding the user entry.

DefaultLdapAuthoritiesPopulator – Class of an unnamed bean; configured with:ldapContextSource – Required for accessing the LDAP server.Role search parameters – Required for finding user roles to map.

applicationContext-multiTenancy-security.xml, in commercial editions:mtUserAuthorityServiceTarget – Name of a bean whose userProcessors property is configured to handle organizations with either of the following beans:

Configuring JasperReports Server for external LDAP authentication is a common customization. As a result, the Spring Security beans to implement it are included in the server, and their configuration is given in the applicationContext-security.xml file as commented code. You must uncomment the code and make modifications according to your LDAP configuration.

21


defaultExternalUserProcessor – Name of a bean of class DefaultExternalUserProcessor used to map the single default organization.

Default organization mapping parameter – Optional for specifying a different organization.rootOrganizationRolesMap parameter – Optional for mapping administrator roles.

ldapExternalUserProcessor – Name of a bean of class LdapExternalUserProcessor used to map multiple organizations:

ldapContextSource – Required for accessing the LDAP server.Organization mapping parameters – Required for finding the user’s organization ID.rootOrganizationRolesMap parameter – Optional for mapping administrator roles.

2.2.3 LDAP and Administrative UsersJasperReports Server 4.0.1 introduces the ability to externally authenticate administrative users. Using this feature, LDAP entries belonging to custom groups can be granted system or organization admin roles in JasperReports Server.

There are two different ways of doing this:In the community edition, which does not have the organization architecture, LDAP user can belong to groups that map exactly to the name ROLE_ADMINISTRATOR. In this case, the user will be an administrator within JasperReports Server.In commercial editions, system and organization admin privileges are determined by the ROLE_SUPERUSER and ROLE_ADMINISTRATOR system roles at the root level, respectively. By using the new rootOrganizationRolesMap property, you can assign these system roles to LDAP entries based on custom group membership. This property can be used in addition to the existing properties that map group names to organization roles. For more information, see section 2.7.3, “Mapping Roles to System Roles,” on page 31.

One practical consequence of external administrator role mapping, is that LDAP authentication can be used exclusively. When properly set up, you can have external users who are system or organization administrators. Then, you do not need to have the superuser and jasperadmin users, and you can remove the default authentication that they use. This can provide extra security because in this case, LDAP is the only authentication mechanism. However, you must ensure that every organization has an LDAP user mapped to the organization with the correct attributes to have organization admin privileges.

2.3 Adding the ldapAuthenticationProviderIn applicationContext-security.xml, locate the authenticationManager bean and uncomment or add the reference to ldapAuthenticationProvider at the top of the list of providers. The ldapAuthenticationProvider bean is provided in the existing Spring Security package.

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, and therefore administrators in a different one cannot be found.

<bean id="authenticationManager"class="org.springframework.security.providers.ProviderManager">

<property name="providers">

<list><ref local="ldapAuthenticationProvider"/>

<ref bean="${bean.daoAuthenticationProvider}"/>

<ref local="anonymousAuthenticationProvider"/>

</list></property>

</bean>

22

LDAP Authentication

As shown in the example above, you can list other authentication providers with LDAP. The authenticationManager 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.

The daoAuthenticationProvider is the default internal authentication using the internal database. You may keep this provider in the list in order to access the jasperadmin and superuser accounts, or any other administrator accounts you have created. Or, if you have configured system role mapping as described in section 2.7.3, “Mapping Roles to System Roles,” on page 31, you can remove the daoAuthenticationProvider from the list.

You must keep the anonymousAuthenticationProvider in the list. Anonymous authentication is necessary to display the JasperReports Server login page; anonymous access to all other pages is disabled by default.

2.4 Setting the LDAP Connection ParametersSeveral beans need to access the LDAP directory and must be configured with the connection parameters for the LDAP server. To do so, configure a helper bean called ldapContextSource that is given to the constructors of the beans that need it.

In applicationContext-security.xml, locate the ldapContextSource bean and uncomment it if necessary. Specify the following information:

constructor-arg value – The URL of your LDAP server, including the base DN.userDn property – The distinguished name (DN) of your LDAP administrator.password property – The password of your LDAP administrator.

The following example shows the syntax of the bean’s constructor and properties:

2.5 Performing LDAP User SearchThe ldapAuthenticationProvider bean must be initialized with a bean of the class BindAuthenticator that encapsulates search parameters for finding users in the LDAP directory. There are two ways of finding users in the directory:

Matching RDN patterns based on the login name provided by the user. Use this method if the login name appears in the DN of your user entries, and your user entries are in a fixed branch of your LDAP directory.Performing a search for the login name provided by the user. Use this method if the login name is the value of an attribute that does not appear in the RDN, or if your user entries are located in a more complex structure. In particular, if you are authenticating users for one or more organizations, it is likely that user entries are in multiple branches of your directory.

In terms of performance, matching patterns is faster because doing so checks for the existence of a DN in the LDAP directory as opposed to performing a search. You can configure both matching and searching by combining the instructions in the following subsections. In this case, the patterns are matched first, and the search is performed only if no match is found.

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 in the case that the LDAP server in unavailable.

If your LDAP server is configured to allow anonymous user lookup, you do not need to specify the userDn and password properties.

<bean id="ldapContextSource"

class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">

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

23


2.5.1 Specifying userDnPatterns ParametersIf you have a fixed structure of user entries and the login name of the user appears in the RDN of your user entries, you can easily configure the BindAuthenticator bean with patterns to match them.

In applicationContext-security.xml, locate the ldapAuthenticationProvider bean and uncomment it if necessary. The unnamed bean of class BindAuthenticator is the first constructor argument.

In the properties that configure BindAuthenticator, the userDnPatterns property contains a list of values that give patterns for matching the RDNs of user entries. For each value in the list, the server substitutes the login name entered by the user for the {0} placeholder, then creates a DN by appending the base DN from the LDAP URL. The LDAP URL is the one specified in section 2.4, “Setting the LDAP Connection Parameters,” on page 23.

JasperReports Server attempts to bind to the LDAP directory with the DN created with each pattern in the order they are given.

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:

When you specify the userDnPatterns property in the BindAuthenticator bean, you only need to uncomment the userSearch bean described in the next section if you want to enable both types of user search.

2.5.2 Specifying userSearch ParametersTo perform a search to locate user entries, configure the helper bean called userSearch and pass it to the BindAuthenticator bean.

In applicationContext-security.xml, locate the userSearch bean and uncomment it if necessary. Specify the following information:

An optional branch RDN where user entries are located. If not specified, the search includes your entire LDAP directory starting from the base DN of the LDAP URL specified in section 2.4, “Setting the LDAP Connection Parameters,” on page 23.An LDAP filter expression to compare any attribute or combination of attributes with the login name. JasperReports Server substitutes the login name entered by the user for the {0} placeholder to perform the search.Whether or not the search should extend to all subtrees beneath the branch DN or, when no branch DN is specified, beneath the base DN.

The purpose of the user search during LDAP authentication is to locate a single user entry that validates the password given during the login process. Also, the LDAP entry located by the user search is later used to map roles and organizations. Regardless of the LDAP entry, the user is assigned the login name given during the login process.

<bean id="ldapAuthenticationProvider"

class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">

<constructor-arg><bean

class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator">

<constructor-arg><ref local="ldapContextSource"/></constructor-arg><property name="userDnPatterns">

<list>

<value>uid={0},ou=users</value></list>

</property>

</bean></constructor-arg>

...

</bean>

24

LDAP Authentication

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.

Finally, in applicationContext-security.xml, locate the ldapAuthenticationProvider bean and uncomment it as well. Specify the userSearch bean in the userSearch property to configure the BindAuthenticator bean in the first constructor argument of the ldapAuthenticationProvider bean.

The following example shows the BindAuthenticator bean configured with userSearch:

2.5.3 LDAP Search for Multiple OrganizationsWhen you are authenticating users for one or more organizations in a commercial edition of JasperReports Server, the search parameters must be able to locate all users for all organizations. There are two reasons for this:

The mapping to organizations in the server from LDAP user entries requires the user entries to be in a hierarchical tree structure that mimics the intended organization hierarchy. You cannot use attribute values or group membership in LDAP to define organizations.External authorization does not allow the user to enter an organization name, therefore, the search must find the username among all organizations.

This has two implications:1. Your choice of pattern matching or search depends on the structure of user entries in LDAP. For example, if you have a

small, fixed number of organizations, you could match them with a pattern for each one, as follows:

But if you have a large number of organizations, or if the number or name of organizations can change, you need to perform a search to find 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 does not have one.

<bean id="userSearch"class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">

<constructor-arg index="0"><value>ou=users</value></constructor-arg>

<constructor-arg index="1"><value>(uid={0})</value></constructor-arg><constructor-arg index="2"><ref local="ldapContextSource" /></constructor-arg>

<property name="searchSubtree"><value>true</value></property>

</bean>

<bean id="ldapAuthenticationProvider"

class="org.springframework.security.providers.ldap.LdapAuthenticationProvider"><constructor-arg>

<bean

class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator"><constructor-arg><ref local="ldapContextSource"/></constructor-arg>

<property name="userSearch" ref="userSearch"/>


...

</bean>

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

25


2. You cannot implement external authentication for 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, and 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 login.Search returns more than one entry. As a result, login fails for both users with the same login name.

2.5.4 Alternate to Bind AuthenticationIn Spring Security, the task of the BindAuthenticator bean is to access the LDAP directory to determine the DN of the user. To do this, it performs a bind authentication on the LDAP directory, which consists of the following steps:1. Using either the pattern matching or the search described above, find a candidate user entry based on the login name.2. Attempt to login to the LDAP server, known as binding, as the candidate with the login password.3. A successful bind indicates that the right user was found.

Bind authentication with the BindAuthenticator bean is the default behavior when configuring Spring Security for LDAP authentication. However, Spring Security provides an alternate authentication method based on password comparison:1. Use the administrator credentials in the ldapContextSource bean to log into the LDAP server.2. Find a candidate user entry.3. Retrieve the candidate’s password attribute and compare it to the login password, or send the login password for

comparison by the LDAP server.

The alternate authentication method is implemented by Spring Security in the PasswordComparisonAuthenticator class. However, configuring Spring Security with this class is beyond the scope of this documentation. For more information, see the Spring Security documentation and Javadoc.

2.6 Mapping the User RolesThe roles that an external user has in JasperReports Server are based on the static groups to which the user belongs in LDAP. The server performs a second search in the LDAP directory to determine any user roles. The mapping defines the location of the group definitions in LDAP, how to find the groups to which the user belongs, and any transformation of the group name for use in the server as a role name. The mapping for user roles is configured in a bean of the class DefaultLdapAuthoritiesPopulator, itself part of the configuration of the ldapAuthenticationProvider bean.

In applicationContext-security.xml, locate the ldapAuthenticationProvider bean that you uncommented when specifying the user pattern or search parameters. In the second constructor argument, specify the following information:

constructor-arg index="1" – An optional branch DN where group entries are located. If not specified, the search covers your entire LDAP directory starting from the base DN.


<constructor-arg index="0"><value></value></constructor-arg>

<constructor-arg index="1"><value>(uid={0})</value></constructor-arg><constructor-arg index="2"><ref local="ldapContextSource" /></constructor-arg>


</bean>

Some LDAP servers support other user-grouping mechanisms, such as nsrole in the Sun Directory Server. These mechanisms can be mapped into JasperReports Server roles through the configuration parameters below, by extending the DefaultLdapAuthoritiesPopulator class, or a combination of both. Such configurations are beyond the scope of this document.

26

LDAP Authentication

groupRoleAttribute property – The attribute whose value is mapped to the name of the JasperReports Server role. Often, this is the cn attribute that gives the name of the role in the RDN of the group entry. However, it could be any attribute, for example a custom attribute named JaspersoftRoleName that is defined by a custom LDAP schema.groupSearchFilter property – A group search filter that locates entries representing groups to which the user belongs. For static groups, this filter should detect entries with the groupofuniquename object class and with a uniqueMember value that matches the DN found by the user search. In this context, the {0} placeholder contains the full DN of the user entry.searchSubtree property – Whether or not the search should extend to all subtrees beneath the branch DN, or beneath the base DN when no branch DN is specified.convertToUpperCase property – Optionally, whether or not the group name should be converted to all upper case when mapped to a role name in JasperReports Server. By default, the name is converted to upper case, so you only need to specify this property when you do not want to convert the name.rolePrefix property – An optional prefix to add to the group name when mapped to a role name in JasperReports Server. By default, the prefix is ROLE_, so you only need to specify this property when you want a different prefix. Specify a blank string (<value></value>) if you do not want a prefix.

The following example shows the syntax of the constructor arguments and properties:

You must 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 does not exist, the search will cause an error, and users will be unable to login. A successful search that returns no results will allow users to login, but without having the intended roles.

After the mapping has determined the role names given to the external user in JasperReports Server, there are two cases:In the community edition that does not have the organization architecture, the roles are synchronized with existing roles and assigned to the user. Synchronization creates the roles internally if they don’t exist, as described in 1.6.4, “Synchronization of Roles,” on page 13. If one of the role names is ROLE_ADMINISTRATOR, the external user will be a JasperReports Server administrator, equivalent to the internal jasperadmin user.

All users, both internal and external users, are automatically assigned ROLE_USER by default. Therefore, you never need to create or map this role in your LDAP directory.

<bean id="ldapAuthenticationProvider"class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">

<constructor-arg> ...

</constructor-arg><constructor-arg>

<bean class="org.springframework.security.ldap.populator.

DefaultLdapAuthoritiesPopulator"><constructor-arg index="0"><ref local="ldapContextSource"/></constructor-arg>



<constructor-arg index="1"><value></value></constructor-arg><property name="groupRoleAttribute"><value>cn</value></property>

<property name="groupSearchFilter"><value>

(&(uniqueMember={0})(objectclass=groupofuniquenames))</value></property><property name="searchSubtree"><value>true</value></property>




</bean>

27


In commercial editions, which have the organization architecture, the external user and roles are assigned to an organization that is either the default single organization or an organization that is mapped from the DN of the LDAP user. Organization mapping is described in the next section.If you intend for one of the mapped roles to indicate administrator privileges, you must explicitly map it to the system roles, as described in section 2.7.3, “Mapping Roles to System Roles,” on page 31. Otherwise, all mapped roles are created in the mapped organization.

2.7 Mapping the User Organization

In an architecture that allows multiple organizations, all users and roles except for system administrators and system roles belong to an organization. In turn, the organization determines the folders that the user may access in the repository. Therefore, the final part of mapping is determining an organization ID for the external user and roles, based on the user’s RDN in the directory.

If your JasperReports Server license does not allow multiple organizations, the default configuration automatically maps all LDAP users to the single default organization. See section 2.7.1, “Mapping to a Single Organization,” on page 28. The rest of this section applies to commercial licenses that allow multiple organizations.

LDAP is well suited to mapping users into organizations, because LDAP itself has a hierarchal structure of user entries that is often used to represent separate organizations, such as the internal departments of a company. The LDAP tree structure is reflected in the elements of the RDN of each user entry, and the server maps this RDN into an organization or hierarchy of organizations for the external user. For example, the users uid=jack,ou=audit,ou=finance,dc=example,dc=com and uid=jill,ou=accounting,ou=finance,dc=example,dc=com could be mapped to the organizations audit and accounting, respectively, both of which are sub-organizations of finance.

In order to ensure consistency, the server must create the organization of any external user if the organization does not already exist. The server also creates any organization that does not exist in the hierarchy of organizations mapped from the user RDN. To avoid “stray” organizations that are outside of your intended hierarchy, test your mapping against all potential user DNs in your LDAP directory. For more information about mapping external users, including strategies to initialize your JasperReports Server instance, see section 1.6.2, “External Users in the Internal Database,” on page 12.

When mapping organizations, the server determines the mapped name and uses it as the name, ID, and description of the organization. You must insure that none of the organization names that are mapped contain the following characters: |, &, *, ?, <, >, /, \, ~, !, #, $, %, ^, [, or ]. Finally, organizations that are 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 that is created. See section 1.6.5, “Initialization of JasperReports Server for External Users,” on page 14 for a process to initialize the server, including organization admins, before going into production with external authentication.

2.7.1 Mapping to a Single OrganizationIn commercial JasperReports Server deployments that do not implement multiple organizations, there is a single default organization. Externally authenticated users must be mapped to this default organization. Or even if you have multiple organizations in JasperReports Server, you may still want all external users to be placed in a single organization.

The settings in the defaultExternalUserProcessor bean in the file applicationContext-multiTenancy-security.xml map all external LDAP users to a single organization by default

defaultOrganizationIfNotDetected – If you have more than one organization but want to map all users to a single organization, specify it here.rootOrganizationRolesMap – See section 2.7.3, “Mapping Roles to System Roles,” on page 31.

Organizations are a feature of JasperReports Server commercial editions. Skip this section if you have JasperReports Server community edition.

The default organization mapping mechanism cannot map an organization structure from user properties or groups. You can create custom organization mappings to do this by extending the class LdapExternalUserProcessor, but this customization is beyond the scope of this document.

28

LDAP Authentication

The following example shows the default configuration of the defaultExternalUserProcessor bean:

You do not need to edit this file if you have only one organization in your JasperReports Server instance. With one organization, it is automatically detected as the default organization, even if it does not have the default organization ID of organization_1. If you have multiple organizations in your server and want to place all external users in a specific one, specify its organization ID as the value of the defaultOrganizationIfNotDetected property.

2.7.2 Mapping to Multiple OrganizationsIn applicationContext-multiTenancy-security.xml, locate the mtUserAuthorityServiceTarget bean and its userProcessors property. In the list of user processors, uncomment the reference to the ldapExternalUserProcessor bean and comment out the reference to the defaultExternalUserProcessor.

Further in the file, locate the ldapExternalUserProcessor bean and uncomment it. Specify the following information to map the RDN of the user to a hierarchy of organizations in JasperReports Server:

excludeRootDn property – Whether the base DN, also called root DN, should be mapped along with the RDN. For example, if you do not exclude the base DN of dc=example,dc=com, it maps to the organization ID example nested inside the organization ID com nested inside the specified root organization. The base DN is part of the LDAP URL specified in section 2.4, “Setting the LDAP Connection Parameters,” on page 23.organizationRDNs property – A list of attribute names that determines which RDN values should be mapped to organization names. The names in this list determine the RDNs that creates a hierarchy of organizations in JasperReports Server. For example, if you specify the value ou, each RDN with ou=<name> creates a level in the hierarchy of mapped organizations. If this list is blank or when none of the attributes match the RDN of the user entry, the excludeRootDn and rootOrganizationId properties alone determines the organization name.

<bean id="mtUserAuthorityServiceTarget"...

<property name="userProcessors">

<list>



<ref bean="defaultExternalUserProcessor"/>

</list></property>

</bean>

<bean id="defaultExternalUserProcessor" class="com.jaspersoft.jasperserver.

multipleTenancy.DefaultExternalUserProcessor">

<property name="multiTenancyService"><ref bean="internalMultiTenancyService"/></property><property name="defaultOrganizationIfNotDetected" value="organization_1"/>

<property name="multiTenancyConfiguration">

<ref bean="multiTenancyConfiguration"/></property><property name="rootOrganizationRolesMap">

<map>

</map>

</property>

</bean>

Do not specify a null value for the defaultOrganizationIfNotDetected property. The null organization ID is usually reserved for special users such as the system administrator and allows access the repository folder of all other organizations.

29

rootOrganizationId property – The ID of an organization under which any mapped organizations are created as sub-organizations. If the root organization ID is blank (""), the server creates the mapped organization at the top level in JasperReports Server.rootOrganizationRolesMap – See section 2.7.3, “Mapping Roles to System Roles,” on page 31.

The following example shows the syntax of the beans and their properties:

For example, given the organization mapping in the example above, the LDAP user uid=jack,ou=audit,ou=finance, dc=example,dc=com is placed in a sub-organization named audit of a top-level organization named finance. This example also illustrates that it is 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 the audit or the finance organization; both are created if you specify ou in the list of organizationRDNs.

If excludeRootDn = true, rootOrganizationId = "", and no organizationRDNs match in the DN of the user, then the user will have a null organization ID. The null organization ID is usually reserved for special users such as the system administrator and allows access the repository folder of all other organizations. To avoid this mapping, specify a value for rootOrganizationId or ensure that every user has one of the organizationRDNs.

<bean id="mtUserAuthorityServiceTarget"

...

<property name="userProcessors"><list>



<ref bean="ldapExternalUserProcessor"/>



</list></property>

</bean>

...<bean id="ldapExternalUserProcessor" class="com.jaspersoft.jasperserver.

multipleTenancy.ldap.LdapExternalUserProcessor">

<property name="ldapContextSource" ref="ldapContextSource" /><property name="multiTenancyService">

<ref bean="internalMultiTenancyService"/></property>

<property name="excludeRootDn" value="true"/>

<property name="organizationRDNs">

<list><value>o</value>

<value>ou</value>

</list></property>

<property name="rootOrganizationId" value=""/>

<property name="multiTenancyConfiguration"><ref bean="multiTenancyConfiguration"/></property>

<property name="rootOrganizationRolesMap">

<map></map>

</property>

</bean>

30

LDAP Authentication

2.7.3 Mapping Roles to System RolesWhen the organization mapping is complete, synchronization will create the external user and roles in that organization. However, JasperReports Server 4.0.1 introduces an additional mapping of roles to system roles so that you can grant administrator privileges to your external users.

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. The rootOrganizationRolesMap property can be added to the defaultExternalUserProcessor bean shown in section 2.7.1, “Mapping to a Single Organization,” on page 28 or to the ldapExternalUserProcessor bean shown in section 2.7.2, “Mapping to Multiple Organizations,” on page 29.

rootOrganizationRolesMap property – A map (list) of key-value pairs where the key contains a role name mapped from LDAP, and the value contains the system role that should be assigned instead. The key should be a role name that your mapping creates, after adding the prefix and capitalization if so configured in DefaultLdapAuthoritiesPopulator.

For example, if your LDAP user belongs to a group named jrsadmin that is mapped to the name ROLE_JRSADMIN, then the following example would assign that user the ROLE_ADMINISTRATOR system role that makes the user an organization admin. The following code example shows how to create this system role mapping in a single-organization configuration:

The code for the property would be identical if inserted in the ldapExternalUserProcessor bean for a multiple organization configuration.

For roles that are not mapped to system roles, they are created and synchronized in the mapped organization, as described in section 1.6.4, “Synchronization of Roles,” on page 13. In particular, if the name ROLE_ADMINISTRATOR or ROLE_SUPERUSER are mapped from the LDAP groups, but not mapped to system roles, they are created as organization roles and assigned to the user. As organization roles, they do not grant any access permissions, which can be very confusing for administrators. Avoid LDAP groups and role mappings that create these names as organization roles.

2.8 Restarting JasperReports ServerWhen you have configured all the beans in the appropriate files, restart JasperReports Server to make the changes take effect.

To test your configuration, navigate to the JasperReports Server login page. If the server and LDAP are configured correctly, you can log into JasperReports Server with credentials that are stored in your LDAP directory. Try several users with different roles or organizations to verify your configuration.

<bean id="defaultExternalUserProcessor" class="com.jaspersoft.jasperserver.

multipleTenancy.DefaultExternalUserProcessor">

<property name="multiTenancyService"><ref bean="internalMultiTenancyService"/></property><property name="defaultOrganizationIfNotDetected" value="organization_1"/>


<map><entry>

<key>

<value>ROLE_JRSADMIN</value></key>

<value>ROLE_ADMINISTRATOR</value>

</entry></map>

</property>

</bean>

31


2.9 Authentication with Computer Associates SiteMinderComputer Associates SiteMinder is an LDAP-based user directory that can be used to authenticate users through the ldapAuthenticationProvider provided by Spring Security. Simply follow the configuration instructions in this chapter and substitute the connection parameters, search parameters, role mappings, and organization mappings that are specific to your SiteMinder directory structure.

2.10 Authentication with Microsoft Active DirectoryMicrosoft Active Directory can also be used to authenticate users through the ldapAuthenticationProvider provided by Spring Security.

For the purposes of basic external authentication, the only difference in configuration between Active Directory and a standard LDAP server is the need to search for the sAMAccountName attribute containing the user’s login name. Because of this requirement, you must use the BindAuthenticator bean, along with the userSearch bean and corresponding property in BindAuthenticator.

The following example shows all the configuration beans in applicationContext-security.xml for LDAP authentication, including the special syntax for Active Directory:

<bean id="authenticationManager"

class="org.springframework.security.providers.ProviderManager">

<property name="providers"><list>

<ref local="ldapAuthenticationProvider"/>

<ref local="daoAuthenticationProvider"/><ref local="anonymousAuthenticationProvider"/>

</list>

</property></bean>

<bean id="ldapContextSource"

class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">

<constructor-arg value="ldap://hostname:389/dc=ADexample,dc=com"/><property name="userDn"><value>cn=Administrator,dc=ADexample,dc=com</value></property>

<property name="password"><value>password</value></property>

</bean>


<constructor-arg index="0"><value>cn=Users</value></constructor-arg><constructor-arg index="1"><value>(sAMAccountName={0})</value></constructor-arg><constructor-arg index="2"><ref local="ldapContextSource"/></constructor-arg>


</bean>

32

LDAP Authentication

In the example above, the role mapping is omitted, as is the organization mapping. You must include a role mapping for any roles you want to import into JasperReports Server, and you must include an organization mapping if you implement multiple organizations in a commercial edition of JasperReports Server. For more information, see section 2.6, “Mapping the User Roles,” on page 26 and section 2.7, “Mapping the User Organization,” on page 28.

<bean id="ldapAuthenticationProvider" class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">

<constructor-arg>

<bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator">

<constructor-arg><ref local="ldapContextSource"/></constructor-arg>

<property name="userSearch"><ref local="userSearch"/></property>


<constructor-arg>

...</constructor-arg>

</bean>

33


34

CAS Authentication

CHAPTER 3 CAS AUTHENTICATION

Central Authentication Service (CAS) is an open source, Java-based authentication server that includes a mechanism for single sign-on (SSO) across web applications, including those running on different application servers. When a user requests a page from a CAS-enabled web application, the application redirects the user to the CAS server login page. Thereafter, logged-in users can navigate between all participating applications without needing to log in again. Each application communicates with the CAS server in the background to verify that the user is valid before providing access to its resources.

With the CAS protocol, the client application (such as JasperReports Server) never receives or transmits the user’s password. As a result, the client application does not need to apply any encryption to protect passwords. However, unlike LDAP, CAS does not provide any user context, such as roles or organizations, that can be mapped to JasperReports Server. Instead, you can configure static roles and organizations that apply to every CAS-authenticated user.

This chapter shows how JasperReports Server’s default authentication mechanism using Spring Security can be configured to perform external authentication with CAS. In order to participate in SSO, the JasperReports Server configuration is more complex than with simple authentication. In particular, you must modify the filter chain, replace certain filter implementations, and add helper beans to the configuration files.

In addition to the beans provided by Spring Security to support CAS, JasperReports Server provides additional helper beans for CAS integration. The implementation of these custom beans is sufficient to enable CAS authentication but may not provide enough functionality in a complex deployment. Further customization of these beans is beyond the scope of this document.

This chapter assumes that you are familiar with security concepts such as certificates, tokens, and cookies. The first section explains how to install a CAS server for testing. All examples refer to the test server and assume you are using the Apache Tomcat application server. When configuring JasperReports Server to use CAS in production, you must take into account any differences between application servers and the contents of certificates.

This chapter contains the following sections:CAS Server for TestingOverview of External CAS AuthenticationConfiguring JasperReports Server for CAS AuthenticationConfiguring Java to Trust the CAS CertificateModifying the Spring Security Filter ChainAdding the casAuthenticationProviderConfiguring the CAS Authentication BehaviorSetting the User RolesConfiguring the Filters for CASSetting the User OrganizationRestarting JasperReports ServerDetailed Protocol Exchange

35


3.1 CAS Server for TestingCAS is maintained and distributed by Jasig, a consortium of educational institutions and commercial affiliates sponsoring open source software projects. Jasig provides a CAS server packaged as a web application that includes a built-in authentication module that can be used for testing. The built-in authentication module accepts any username and password combination where the username and password are the same. You can download the server from the Jasig download page http://www.jasig.org/cas/download.

As described in the next section, the CAS validation service only accepts requests using a secure transport. This means that 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 is that 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 is running the CAS server so that it uses the certificate in the keystore created above. Modify the file $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 Jasig CAS website http://www.jasig.org/cas. In particular, the page https://wiki.jasig.org/display/CASUM/SSL+Troubleshooting+and+Reference+Guide can help you deploy your certificates.

3.2 Overview of External CAS AuthenticationThis section describes how JasperReports Server integrates the Spring Security mechanisms to perform external CAS authentication, including SSO.

The original CAS implementation, now called the CAS 1 architecture, had a centralized CAS server that processes requests according to a protocol. 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.

The newer CAS 2 architecture adds decentralized proxy authentication for the CAS server, but the underlying protocol is conceptually the same from JasperReports Server’s perspective. This chapter does not explain CAS proxies, but it does cover the Spring Security beans that are used to configure JasperReports Server’s response to CAS proxies. Some explanation about how Spring Security beans interact with proxy responses is given in section 3.12, “Detailed Protocol Exchange,” on page 44.

For more information, see http://www.jasig.org/cas/cas1-architecture and http://www.jasig.org/cas/cas2-architecture.

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 is inaccessible to JasperReports Server.Follow the CAS documentation to ensure you create a secure and robust configuration on your CAS server.

36

http://www.jasig.org/cas/download

http://www.jasig.org/cas

https://wiki.jasig.org/display/CASUM/SSL+Troubleshooting+and+Reference+Guide

https://wiki.jasig.org/display/CASUM/SSL+Troubleshooting+and+Reference+Guide

http://www.jasig.org/cas/cas1-architecture

http://www.jasig.org/cas/cas2-architecture

CAS Authentication

The following figure shows the general protocol during external CAS authentication:

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.

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 a parameter that is another URL that tells CAS how it can request service validation from JasperReports Server. For example:

http://host2:8443/cas/login?service=http://host1:8080/jasperserver/j_spring_cas_security_check.

3. The user’s browser requests the CAS login page from the CAS server.4. However, before serving the CAS login page to the user, CAS requests the service validation from JasperReports Server.

It extracts the URL parameter from the redirect URL and sends it a randomly generated number called a ticket, for example: http://host1:8080/jasperserver/j_spring_cas_security_check?ticket=ST-8670-123buTvFFjo980

5. The JasperReports Server filter chain processes the service validation request and invokes the casAuthenticationProvider. It takes the ticket and establishes a secure connection to the CAS server to verify the credentials of the user associated with the ticket, who is only known to the CAS server.Once the service is validated by the handshake over the secure connection, the CAS server attempts to get the user’s credentials. If the CAS server detects its own session cookie on the user’s browser, this indicates the user has logged in successfully before, and the CAS can retrieve the credentials. If there is no cookie, CAS serves its own login page to the user. When the user enters a username and password, CAS verifies them against its own database.

6. In either case, the CAS server replies to JasperReports Server with the validated username.JasperReports Server maps the username to a predefined set of roles and organization ID, if necessary, to create 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 section 1.6.3, “Synchronization of External Users,” on page 12.

Figure 3-1 General Steps of External CAS Authentication

URLs may appear translated when viewed in browsers or in log files. For example, the previous URL can be written http://host2:8443/cas/login?service=http%3A%2F%2Fhost1:8080%2Fjasperserver%2Fj_spring_cas_security_check.

JasperReports Server (on host1)

Page request

Verify CAS client

Requested content(subj. to authorization)

CAS (on host2)Redirect to CAS login page

Ticket

Gather credentialsService validation via HTTPS

Internal userdatabase

Principal objectincl. roles

CAS userdatabase

j_spring_cas_security_check

or user cookie

UsernameSet cookie

37


7. If the user submitted a valid username and password on the login page, the CAS server sets a session cookie on user’s browser to be used for single sign-on with other applications that use the same CAS server.

8. As with the default internal authorization, 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, as determined by the roles of the user in the principal object.

When comparing these steps with those in section 1.5, “Default Internal Authentication,” on page 8, there are several significant differences:

JasperReports Server must redirect to the CAS login page instead of its own.JasperReports Server must receive the ticket as part of the security check.JasperReports Server must process the ticket and respond to the security check over HTTPS.The roles and organization ID in the user’s principal object are mapped from the username in the CAS response.The internal database must be synchronized with any new information in the user’s principal object.

3.3 Configuring JasperReports Server for CAS AuthenticationThe differences listed in the previous section reflect the changes that need to be made in the Spring Security configuration and on the JasperReports Server host. The items in the following list address each of the differences in the list above, in same order:

To perform the redirect upon receiving an unauthenticated request, replace the pre-filter for the authentication ProcessingFilter with one tailored for CAS.To receive the ticket through the security check URL, add a filter chain for that specific URL, and then modify the behavior of the authenticationProcessingFilter in that chain.To process the ticket, add CAS as an authentication provider in the authenticationManager bean and configure it to receive the response from the CAS server or its proxy. To establish the HTTPS connection, configure the JVM on the JasperReports Server host to trust the CAS server certificate.To map roles, configure a helper bean for the CAS authentication provider. The default implementation maps administrator roles to a static list of usernames, and all others have the minimal user roles. To map the organization ID, configure the user processor bean provided. All users are mapped to a single organization, the sample organization by default.To synchronize the internal database, keep the existing configuration of the JIAuthenticationSynchronizer.

The following sections explain how to make the configuration changes presented above.

3.3.1 Files to ModifyThe configuration for external CAS authentication is made in the following files:

$CATALINA_HOME/bin/catalina.sh or .bat, or the equivalent configuration file for your application server.<js-webapp>/WEB-INF/applicationContext-security.xml<js-webapp>/WEB-INF/applicationContext-security-web.xml<js-webapp>/WEB-INF/applicationContext-multiTenancy-security.xml in commercial editions, which have the organization architecture.

Where <js-webapp> is the location of the JasperReports Server web application in your application server, or where you are modifying the configuration files, as explained in section 1.4, “Configuration Files,” on page 7. The rest of this chapter refers to file names alone.

If the user has disabled cookies, the CAS login protocol still works, but the single sign-on mechanism 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.

38

CAS Authentication

3.3.2 Beans to ConfigureThis section explains the beans involved in external CAS authentication and their relationships. Spring Security provides all the beans to configure CAS authentication, except for the UserDetailsServiceImpl and DefaultExternalUserProcessor classes that JasperReports Server provides to configure roles and organizations, respectively.

However, unlike the configuration of JasperReports Server for LDAP, the configuration beans for CAS are not included by default in comments in the configuration files. As a result, you must add the required beans to the configuration file and edit them for your particular settings. In many places, you must find the existing configuration and replace it with a new bean based on the example.

The beans are listed by file, roughly in the order they are invoked.

applicationContext-security-web.xml file:filterChainProxy – Name of a bean of class FilterChainProxy for defining how page requests are processed and the order of filters invoked on them.authenticationProcessingFilter – Name of a bean of class CasProcessingFilter; implements a new authentication processing filter that processes tickets from the CAS server.authenticationProcessingFilterEntryPoint – Name of a bean of class CasProcessingFilterEntryPoint; specifies the URL of the CAS login page for redirection.

applicationContext-security-web.xml file:authenticationManager – Name of a bean of class ProviderManager for performing authentication; configured with:

casAuthenticationProvider – Name of a bean of class CasAuthenticationProvider; configured with:casUserAuthorityService – Name of a helper bean of class UserDetailsServiceImpl; sets the roles for external CAS users.authenticationServiceProperties – Name of a helper bean of class ServiceProperties; specifies the URL to which the CAS server should send the ticket to initiate service validation.Cas20ServiceTicketValidator – Class of an unnamed bean configured with the HTTPS URL on the CAS server for returning service validation requests.ehCacheBasedTicketCache – Class of an unnamed bean that configures where to store tickets:

ticketCache – Name of a helper bean of class EhCacheFactoryBean; configured with:ticketCacheManager – Name of a helper bean of class EhCacheManagerFactoryBean that gives the location of the configuration file for the ticket cache.

applicationContext-multiTenancy-security.xml, in commercial editions:mtUserAuthorityServiceTarget – Name of a bean whose userProcessors property is configured with:

defaultExternalUserProcessor – Name of a bean of class DefaultExternalUserProcessor; sets the organization ID for external CAS users.

The remaining sections in this chapter give the configuration details for these beans.

3.4 Configuring Java to Trust the CAS CertificateThe CAS protocol requires that the response to the service validation be established over HTTPS for security. This connection is established from the Java classes of Spring Security, therefore it is the Java security system that must be configured. Java security must trust the certificate it receives from the CAS server, otherwise it refuses to connect. This trust is based on two factors:1. The host name in the certificate has to match the host name in the URL of the connection. Certain JVMs require

hostnames as opposed to IP addresses, even if the IP addresses match. See section 3.1, “CAS Server for Testing,” on page 36 for instructions to create a certificate in a keystore.

2. You must tell Java to trust the signing certificate:a. Copy the file you used as the keystore for the CAS server to the JasperReports Server host.

39


b. On the JasperReports Server host, edit the file $CATALINA_HOME/bin/catalina.sh or .bat, or the equivalent file for your application server. In the section for setting JAVA_OPTS, add the following option:"-Djavax.net.ssl.trustStore=<keystore-path>"

3.5 Modifying the Spring Security Filter ChainIn applicationContext-security-web.xml, locate the filterChainProxy bean and modify it as follows:1. Add a pattern for matching the URL that the CAS server requests during service validation, for example

/j_spring_cas_security_check. The pattern must match the following properties defined in section 3.6, “Configuring the Filters for CAS,” on page 41:

The service property in the authenticationServiceProperties bean.The filterProcessesUrl in the authenticationProcessingFilter bean.

Set the filter chain for this pattern as shown in this example:

2. In the filter chain for the /** pattern, locate the${bean.authenticationProcessingFilter} and replace it with the authenticationProcessingFilter, as shown in the example above.

<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy">

<property name="filterInvocationDefinitionSource">

<value>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON

PATTERN_TYPE_APACHE_ANT

/xmla=httpSessionContextIntegrationFilter,${bean.loggingFilter},

${bean.basicProcessingFilter},JIAuthenticationSynchronizer,anonymousProcessingFilter,

basicAuthExceptionTranslationFilter,filterInvocationInterceptor

/services/**=httpSessionContextIntegrationFilter,${bean.loggingFilter},

${bean.portletAuthenticationProcessingFilter},${bean.basicProcessingFilter},${bean.passwordExpirationProcessingFilter},JIAuthenticationSynchronizer,

anonymousProcessingFilter,wsBasicAuthExceptionTranslationFilter,

filterInvocationInterceptor

/j_spring_cas_security_check=httpSessionContextIntegrationFilter,authenticationProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor

/**=httpSessionContextIntegrationFilter,${bean.loggingFilter},${bean.userPreferencesFilter},authenticationProcessingFilter,${bean.userPreferencesFilter},${bean.basicProcessingFilter},

requestParameterAuthenticationFilter,JIAuthenticationSynchronizer,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor,

switchUserProcessingFilter

</value></property>

</bean>

40

CAS Authentication

3.6 Configuring the Filters for CASWe need to replace the authenticationProcessingFilter and the authenticationProcessingFilterEntryPoint for CAS. Notice that we keep the same bean names in the id attribute and substitute a different class with its specific properties. Because these beans are referenced by name in the beans that call them, the beans with the new classes are automatically used instead. Alternatively, you could give the new beans new names, but then you would also need to re-configure the beans that call them. Note that the documentation for Spring Security takes the latter approach.

Locate and replace the existing entries in the applicationContext-security-web.xml file with the following beans:

The service property of the authenticationServiceProperties bean specifies the JasperReports Server URL that receives the ticket when the CAS server performs service validation. The loginUrl property of the authenticationProcessingFilterEntryPoint bean specifies the login URL for the CAS server, to which JasperReports Server redirects all users for authentication. The authenticationManager property of the authenticationProcessingFilter bean specifies the authenticationManager bean that is configured in the next section.

3.7 Adding the casAuthenticationProviderIn applicationContext-security.xml, locate the authenticationManager bean and add casAuthenticationProvider to the top of the list of providers. Remove all other providers from the list, except for anonymousAuthenticaionProvider as shown in the following example:

Unlike other forms of external authentication, CAS is not compatible with multiple authentication providers. As a consequence of this configuration, you cannot use the default jasperadmin user account, and you must have users defined in CAS that will be your administrators. See section 3.9, “Setting the User Roles,” on page 43 to designate administrators.

<bean id="authenticationProcessingFilter"class="org.springframework.security.ui.cas.CasProcessingFilter">

<property name="authenticationManager"><ref local="authenticationManager"/></property>

<property name="authenticationFailureUrl"><value>/loginerror.html</value></property><property name="defaultTargetUrl"><value>/loginsuccess.html</value></property>

<property name="filterProcessesUrl"><value>/j_spring_cas_security_check</value>

</property></bean>

...

<bean id="authenticationProcessingFilterEntryPoint"

class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint"><property name="loginUrl"><value>https://host2:8443/cas/login</value></property>

<property name="serviceProperties"><ref local="authenticationServiceProperties"/>

</property></bean>

<bean id="authenticationManager"

class="org.springframework.security.providers.ProviderManager"><property name="providers">

<list>

<ref local="casAuthenticationProvider"/><ref local="anonymousAuthenticationProvider"/>

</list>

</property>

</bean>

41


3.8 Configuring the CAS Authentication BehaviorIn the applicationContext-security.xml file, below the authenticationManager, add the casAuthenticationProvider bean and its helper beans. In particular, the ticketValidator property is configured with an unnamed bean initialized with the HTTPS URL where tickets are validated on the CAS server.

These helper beans for the ticket cache use default settings provided by Spring Security and do not need to be further modified.

<bean id="casAuthenticationProvider"

class="org.springframework.security.providers.cas.CasAuthenticationProvider">

<property name="userDetailsService"><ref local="casUserAuthorityService"/></property>

<property name="serviceProperties"><ref local="authenticationServiceProperties"/></property>

<property name="ticketValidator">

<bean class="org.jasig.cas.client.validation.Cas20ServiceTicketValidator"><constructor-arg index="0" value="https://host2:8443/cas" /></bean></property>

<property name="statelessTicketCache">

<bean class="org.springframework.security.providers.cas.cache.EhCacheBasedTicketCache"><property name="cache"><ref local="ticketCache"/></property></bean></property>

<property name="key"><value>lam_or_lame</value></property>

</bean>

<bean id="authenticationServiceProperties"class="org.springframework.security.ui.cas.ServiceProperties">

<property name="service">

<value>https://host1:8080/jasperserver/j_spring_cas_security_check</value></property><property name="sendRenew"><value>false</value></property>

</bean>

<bean id="ticketCacheManager"

class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"><property name="configLocation"><value>classpath:/ehcache-failsafe.xml</value></property>

</bean>

<bean id="ticketCache" class="org.springframework.cache.ehcache.EhCacheFactoryBean">

<property name="cacheManager"><ref local="ticketCacheManager"/></property><property name="cacheName"><value>casTicketCache</value></property>

</bean>

42

CAS Authentication

3.9 Setting the User RolesAfter the helper beans for the casAuthenticationProvider in the applicationContext-security.xml file, add the casUserAuthorityService bean that defines roles for CAS users:

Unlike LDAP, CAS does not provide a context that can be searched; instead, roles are specified statically in the configuration. This simple implementation of the userDetailsServiceImpl class is configured with the following:

adminUsers property – A list of usernames that are granted administrator privileges in JasperReports Server. The username values must match exactly the usernames authenticated and returned by the CAS server.defaultAdminRoles property – A list of JasperReports Server system roles that are assigned to every user in the list of administrators.defaultInternalRoles property – A list of JasperReports Server role names that are assigned to every user that is not in the list of administrators.

3.10 Setting the User Organization

Built-in support for organizations with CAS is limited to mapping all users authenticated by CAS to a single organization. If you use the single default organization, the default mapping will place all CAS-authenticated users there. If you have multiple organizations, you must choose the one in which users will be placed.

The following example shows the defaultExternalUserProcessor bean in the applicationContext-multiTenancy-security.xml file that performs this function:

<bean id="casUserAuthorityService" class="com.jaspersoft.jasperserver.api.metadata.user.service.impl.UserDetailsServiceImpl">

<property name="adminUsers"><list>

<value>myorgadmin</value></list></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></bean>

Organizations are a feature of JasperReports Server commercial editions. Skip this section if you have JasperReports Server community edition.

<bean id="mtUserAuthorityServiceTarget"

...<property name="userProcessors">

<list>



<ref bean="defaultExternalUserProcessor"/>

</list></property>

</bean>

43

If you have only one organization in your JasperReports Server instance, you do not need to edit this file. All CAS-authenticated users are placed in the single existing organization. With a single organization, it is automatically detected as the default organization, even if it does not have the default organization ID of organization_1.

If you have multiple organizations in JasperReports Server, you must specify the organization ID for CAS-authenticated users in the value of the defaultOrganizationIfNotDetected property. The organization ID can be one that already exists or one that does not, but as a result, all CAS-authenticated users are placed in the single organization you specify. When specifying the defaultOrganizationIfNotDetected value, the organization ID must not contain the following characters: |, &, *, ?, <, >, /, \, ~, !, #, $, %, ^, [, or ].

The rootOrganizationRolesMap property does not apply to CAS authentication because CAS uses the static roles map defined in the defaultAdminRoles property of the casUserAuthorityService bean. Leave its map values commented out.

Finally, organizations that are 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 that is created. See section 1.6.5, “Initialization of JasperReports Server for External Users,” on page 14 for a process to initialize JasperReports Server, including organization admins, before going into production with external authentication.

3.11 Restarting JasperReports ServerWhen you have configured all the beans in the appropriate files, restart JasperReports Server. Because of the modification to the application server configuration in section 3.4, “Configuring Java to Trust the CAS Certificate,” on page 39, you must restart the application server, which also restarts JasperReports Server.

Instead of navigating to the JasperReports Server login page, go directly to another page in JasperReports Server, for example your home page:

http://host1:8080/jasperserver/flow.html?_flowId=homeFlow

If JasperReports Server, CAS, and your certificates are configured correctly, you should be prompted to log into the CAS server, and when you do so, you should be redirected to the JasperReports Server home page for the user you logged in as.

3.12 Detailed Protocol ExchangeThis section gives a more detailed view of the protocol exchange between the Spring Security components of JasperReports Server and the CAS server. It shows which beans respond to the various communications and how they exchange information to authenticate a user.

<bean id="defaultExternalUserProcessor"class="com.jaspersoft.jasperserver.multipleTenancy.DefaultExternalUserProcessor">

<property name="multiTenancyService"><ref bean="internalMultiTenancyService"/></property>

<property name="defaultOrganizationIfNotDetected" value="organization_1"/><property name="multiTenancyConfiguration">

<ref bean="multiTenancyConfiguration"/></property>


<map>

</map>

</property></bean>

Do not specify a null value for the defaultOrganizationIfNotDetected property. The null organization ID is usually reserved for special users such as the system administrator and allows access the repository folder of all other organizations.

44

CAS Authentication

This section is based on the Spring Security documentation. For links to the source, see section 1.7, “Customization of External Authentication,” on page 17.1. The user requests a page that is either secure or that includes secure beans. Spring Security’s

ExceptionTranslationFilter detects an AuthenticationException. Because the user’s Authentication object (or lack thereof) caused an AuthenticationException, the ExceptionTranslationFilter calls the configured AuthenticationEntryPoint. If using CAS, this is the CasProcessingFilterEntryPoint class.

2. The CasProcessingFilterEntry point redirects the browser to the CAS server and specifies a service parameter, which is the callback URL for Spring Security service. For example, the browser could be redirected to http://host2:8443/cas/login?service=https%3A%2F%2Fhost1:8080%2Fjasperserver%2Fj_spring_cas_security_check. Both URLs are configurable.

3. After the browser redirects to CAS, the user is prompted for her username and password, unless she has a session cookie that indicates she has logged in previously. In this case, she is not prompted to login again. CAS uses the PasswordHandler (or AuthenticationHandler if using CAS 3.0) to decide whether the username and password is valid.

4. If login is successful, CAS redirects the browser to the callback URL as requested. It also includes a ticket parameter, which is an opaque string representing the service ticket. For example, the browser might be redirected to:http://host1:8080/jasperserver/j_spring_cas_security_check?ticket=ST-0-ER94xMJmn6pha35CQRoZ

5. In the web application, the CasProcessingFilter always listens for requests to /j_spring_cas_security_check. The processing filter constructs a UsernamePasswordAuthenticationToken representing the service ticket. The principal is equal to CasProcessingFilter.CAS_STATEFUL_IDENTIFIER, and the credentials are the opaque service ticket string. The authentication request is sent to the configured AuthenticationManager.

6. The AuthenticationManager implementation is the ProviderManager, which in turn is configured with the CasAuthenticationProvider. The latter only responds to UsernamePasswordAuthenticationTokens containing the CAS-specific principal (such as CasProcessingFilter.CAS_STATEFUL_IDENTIFIER) and CasAuthenticationTokens.

7. CasAuthenticationProvider validates the service ticket using a TicketValidator implementation. In Spring Security, this is implemented as CasProxyTicketValidator. This implements a ticket validation class included in the CAS client library. The CasProxyTicketValidator sends a service ticket validation HTTPS request to the CAS server. The CasProxyTicketValidator may also include a proxy callback URL. For example: https://host2:8443/cas/proxyValidate?service=https%3A%2F%2Fhost1:8080%2Fjasperserver%2Fj_spring_cas_security_check&ticket=ST-0-ER94xMJmn6pha35CQRoZ&pgtUrl=https://host1:8080/jasperserver/casProxy/receptor

8. When the CAS Server receives the proxy validation request, it checks to see if the service ticket matches the service URL to which it was issued. If they match, CAS returns an affirmative XML response that specifies the username. If any proxy was involved in the authentication, the list of proxies is also included in the XML response.

9. Optionally, when the request sent to the CAS validation service includes the proxy callback URL in the pgtUrl parameter, CAS includes a pgtIou string in the XML response. This string represents a proxy-granting ticket IOU. The CAS server then creates its own HTTPS connection to pgtUrl. This authenticates both the CAS server and the claimed service URL. The systems uses the HTTPS connection to send a proxy-granting ticket to the original web application. For example: https://host1:8080/jasperserver/casProxy/receptor?pgtIou=PGTIOU-0-R0zlgrl4pdAQwBvJWO3vnNpevwqStbSGcq3v&pgtId=PGT-1-si9YkkHLrtACBo64rmsi3v2nf7cpCResXg5MpES. If you require proxy-granting tickets, use CAS’s ProxyTicketReceptor servlet to receive them.

10. The CasProxyTicketValidator parses the XML it received from the CAS server. It returns a TicketResponse to the CasAuthenticationProvider, including the username (mandatory), proxy list (if any were involved), and proxy-granting ticket IOU (if the proxy callback was requested).

11. Next, CasAuthenticationProvider calls a configured CasProxyDecider, which indicates whether the proxy list in the TicketResponse is acceptable. Several implementations are provided with Spring Security: RejectProxyTickets, AcceptAnyCasProxy, and NamedCasProxyDecider. The first two implementations are self-explanatory, while NamedCasProxyDecider can be configured with a list of trusted proxies.

12. CasAuthenticationProvider requests a CasAuthoritiesPopulator to advise the GrantedAuthority objects that apply to the user contained in the TicketResponse. Spring Security includes a DaoCasAuthoritiesPopulator that uses the UserDetailsService infrastructure to find the UserDetails and the associated GrantedAuthority

45


objects. Note that JasperReports Server ignores the password and enabled/disabled status of UserDetails returned by the UserDetailsService, as the CAS server is responsible for authentication decisions. DaoCasAuthoritiesPopulator only retrieves the GrantedAuthority objects.

13. If no problems were encountered, CasAuthenticationProvider constructs a CasAuthenticationToken, including the details contained in the TicketResponse and the GrantedAuthority objects. The token contains the hash of a key, so that the CasAuthenticationProvider knows it created the response.

14. Control is returned to CasProcessingFilter, which places the created CasAuthenticationToken into the HttpSession attribute named HttpSessionIntegrationFilter.SPRINGFRAMEWORK_SECURITY_AUTHENTICATION_KEY.

15. The browser is redirected to the original page that caused the AuthenticationException.16. Since the Authentication object is now in the well-known location, it is handled like any other authentication

approach. Usually the HttpSessionIntegrationFilter is used to associate the Authentication object with the SecurityContextHolder for the duration of each request.

46

Index

INDEX

Symbols${bean.x}

see also xsyntax defined 10

AAcegi Security. See Spring Security.administrative user

with CAS 43with LDAP 22, 23

adminUsers property 43anonymousAuthenticationProvider bean 11anonymousProcessingFilter bean 10applicationContext-multiTenancy-security.xml file

with CAS 43–44with LDAP 28–31

applicationContext-security.xml filefilter chain 9with Active Directory 32with CAS 41–43with LDAP 22–27

applicationContext-security-web.xml filewith CAS 40–41

authenticationanonymous 6CAS overview 36credentials 6customizations 17defined 6deployment procedure 14external, defined 6internal 8–11LDAP overview 20with Active Directory 32with SiteMinder 32

authenticationManager beanwith CAS 39, 41

with internal authentication 10with LDAP 21

authenticationProcessingFilter beanwith CAS 39, 41with internal authentication 10with LDAP 21

authenticationProcessingFilterEntryPoint beandescribed 39example 41loginUrl property 41

authenticationServiceProperties beandescribed 39example 41service property 41

authorizationdefined 6of external users 13

BbasicProcessingFilter bean 10BindAuthenticator class

described 21example 24userDnPatterns property 24

CCAS

administrative users 43applicationContext-multiTenancy-security.xml file 43–44applicationContext-security.xml file 41–43applicationContext-security-web.xml file 40–41authentication overview 36catalina.sh or .bat file 40certificates 36, 39cookies 37–38filter chain modifications 40Jasig website 36login page 37

47


organizations 43overview 35protocol details 44roles 43single sign-on 35, 38Spring Security customization 36test server 36

Cas20ServiceTicketValidator class 39casAuthenticationProvider bean 39–42CasAuthenticationProvider class 39CasProcessingFilter class 39CasProcessingFilterEntryPoint class 39casUserAuthorityService bean

adminUsers property 43defaultAdminRoles property 43defaultInternalRoles property 43described 39example 43

catalina.sh or .bat file 40Central Authentication Service. See CAS.certificates for CAS 36, 39Computer Associates SiteMinder 32convertToUpperCase property 27cookies with CAS 37–38

DdaoAuthenticationProvider bean

with internal authentication 11with LDAP 23

database. See internal database.defaultAdminRoles property 43defaultExternalUserProcessor bean

defaultOrganizationIfNotDetected property 28, 29, 44rootOrganizationRolesMap property 31with CAS 39, 43with LDAP 22, 28, 29

DefaultExternalUserProcessor class 22, 39defaultInternalRoles property 43DefaultLdapAuthoritiesPopulator class

branch DN value 26convertToUpperCase property 27described 21example 26groupRoleAttribute property 27groupSearchFilter property 27rolePrefix property 27searchSubtree property 27

defaultOrganizationIfNotDetected property 28with CAS 44with LDAP 29

DefaultSpringSecurityContextSource class 21deployment 14

EehCacheBasedTicketCache class 39EhCacheFactoryBean class 39EhCacheManagerFactoryBean class 39email address 13exceptionTranslationFilter bean 10excludeRootDn property 29external authentication. See authentication.

Ffiles

applicationContext-multiTenancy-security.xmlwith CAS 43–44with LDAP 28–31

applicationContext-security.xmlfilter chain 9with Active Directory 32with CAS 41–43with LDAP 22–27

applicationContext-security-web.xmlwith CAS 40–41

catalina.sh or .bat 40js.spring.properties 10web.xml 9

filter chaindefined 9in applicationContext-security.xml file 9with CAS 40with internal authentication 10with LDAP 21

FilterBasedLdapUserSearch class 21filterChainProxy bean

filterInvocationDefinitionSource property 9with CAS 39, 40with internal authentication 9

FilterChainProxy classwith CAS 39with internal authentication 9

filterInvocationDefinitionSource property 9filterInvocationInterceptor bean 10

GgroupRoleAttribute property 27groupSearchFilter property 27

HHttpSession object 10httpSessionContextIntegrationFilter bean 10

Iinternal authentication. See authentication.Internal database

synchronization 12internal database

described 6

48

Index

JJIAuthenticationSynchronizer bean

with internal authentication 10, 12with LDAP 21

js.spring.properties file 10

Kkeytool utility 36

LLDAP

administrative users 22, 23applicationContext-multiTenancy-security.xml file 28–31applicationContext-security.xml file 22–27bind authentication 26login page 20matching RDN patterns 23, 24organization mapping 28overview 19roles 26searching for usernames 23, 24single sign-on 19Spring Security customization 21URL 23with default internal authentication 23

ldapAuthenticationProvider bean 21, 24–27LdapAuthenticationProvider class 21ldapContextSource bean

described 21example 23password property 23URL value 23userDn property 23

ldapExternalUserProcessor beandescribed 22excludeRootDn property 29multiple organizations 29organizationRDNs property 29rootOrganizationId property 30rootOrganizationRolesMap property 31

LdapExternalUserProcessor class 22Lightweight Directory Access Protocol. See LDAP.loggingFilter bean 10login page

with CAS 37with internal authentication 10with LDAP 20

loginUrl property 41

MMicrosoft Active Directory 32mtUserAuthorityServiceTarget bean

with CAS 39, 43with LDAP 21, 29–30

OorganizationRDNs property 29

organizationsmanaging external organizations 17overview 11with CAS 43with LDAP 28

Ppassword property (LDAP) 23PasswordComparisonAuthenticator class 26principal objects 6profile attributes 13ProviderManager class

with CAS 39with internal authentication 10, 22with LDAP 21

RrequestParameterAuthenticationFilter bean 10rolePrefix property 27roles

external roles 13internal roles 13managing external roles 16synchronization 13system roles 13with CAS 43with LDAP 26

rootOrganizationId property 30rootOrganizationRolesMap property 31

SsearchSubtree property 27SecurityContext object 10securityFilter bean 9service property 41ServiceProperties class 39sessions 6single sign-on

defined 6with CAS 35, 38with LDAP 19

SiteMinder 32Spring Security 7

with CAS 36with LDAP 21

switchUserProcessingFilter bean 10synchronization

defined 12of roles 13of users 12with CAS 37–38with LDAP 20–21

TticketCache bean 39ticketCacheManager bean 39

49


UUserDetailsServiceImpl class 39userDn property (LDAP) 23userDnPatterns property 24userPreferencesFilter bean 10userProcessors property 29users

defined 6email address 13externally defined 13managing external users 15profile attributes 13

same login name in LDAP 26synchronization 12user sessions 6

userSearch beanbranch RDN value 24described 21example 24LDAP filter value 24search subtrees value 24

userSearch property 25

Wweb.xml file 9

50

jasperreports server authentication cookbook

Documents