Token-based Authentication


If you have an application or portal you want to use with JasperReports Server, but do not have an existing single sign-on environment, you can use the Jaspersoft token-based authentication and user management framework. To work with token-based authentication, your application or portal must do the following:

Authenticate the end user according to the standards of your environment or application.
Construct and optionally encrypt a token based on the authenticated user values within your application or process. The token values can include username, tenant (if multi-tenancy is enabled), roles, and profile attributes. You can configure the token based on your needs for reporting and analysis within the JasperReports Server.
Send the token to the JasperReports Server as part of an HTTP request.

When JasperReports Server receives the token, it will:

Attempt to decrypt the token (in the case it was encrypted) and validate the token format.
If the token is successfully parsed, use the information in the token to create and update the external user within JasperReports Server automatically.

The JasperReports Server deployment includes a sample file for token-based authentication in the <js‑install>/samples/ externalAuth-sample-config folder: the sample-applicationContext-externalAuth-preauth-mt.xml file (commercial editions) or sample-applicationContext-externalAuth-preauth.xml (community editions).

When token-based authentication is used, it is extremely important that your external system is configured properly to prevent an attacker from forging the token. Consider taking security measures such as connecting over HTTPS, and encrypting the token, and using a time stamp, so that the token is not exposed in the browser cache and cannot be easily reused.

Overview of Token-based Authentication

This section explains how JasperReports Server performs external authentication using a token, highlighting the differences with Default Internal Authentication.

The following diagram shows the general steps involved in logging into JasperReports Server using a token:

synchronized with the internal database, where the user account is marked as an external user. The JasperReports Server environment reflects the user’s roles and organization as defined in the token. For more information about synchronization, see Synchronization of External Users

General Steps for Token-based Authentication

The following steps explain the interaction between the user’s browser, JasperReports Server, and a pre-authenticated user:

1. A user requests any page in JasperReports Server.
2. If the user has not previously accessed JasperReports Server, the server looks for the presence of the principalParameter in the URL or request header. If the token is present and correctly formatted, the user is automatically authenticated.

In token-based authentication, the JasperReports Server login screen is not displayed to the user and the user does not log in directly.

After the user has authenticated and a JasperReports Server session has been created, future requests do not require the presence of the principalParameter.

3. JasperReports Server decrypts the token in the URL or request header and creates a principal object to represent the user’s session in memory. The username, roles, and organization information are extracted from the token and .
4. As with the default internal authorization, JasperReports Server now sends the requested content to the user, or if none was specified, the home page appropriate for the user. An application-server user session is established and the connection between the requesting browser or process is maintained by repeatedly sending session identification information, usually in the form of a HTTP cookie. The token does not have to be resent while the session is live, usually until there is a log out or the session has not been active for a period of time.

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 Default Internal Authentication, there are three significant differences:

Token-based authentication does not use a login screen. Instead, it depends on the presence of the principalParameter in the URL or request header. As long as the principalParameter is present, the request is automatically authenticated.
The portal or other external authentication mechanism is responsible for passing the correct username, and any roles, organization, or profile attributes as part of a token in the URL or request header.
JasperReports Server decrypts the token, extracts the user details, and uploads the data to the internal database. The internal database is synchronized with any new information in the user’s principal object.

Configuring JasperReports Server for Token-based Authentication

A sample file for configuring JasperReports Server to work with token-based authentication is included in the JasperReports Server distribution. Sample files are located in the <js‑install>/samples/externalAuth-sample-config directory of your JasperReports Server. The file included depends on your version of JasperReports Server:

sample-applicationContext-externalAuth-preauth.xml: Sample file for implementing token-based authentication in a JasperReports Server with a single organization. This file is included in the community edition.
sample-applicationContext-externalAuth-preauth-mt.xml: Sample file for implementing token-based authentication with a JasperReports Server with multiple organizations. This file is included in commercial editions of JasperReports Server. To use external authentication with a commercial version of JasperReports Server with a single organization, you need to specify the organization you want as described in Specifying a Single Organization.

To configure JasperReports Server to work with your authentication method, modify and deploy the sample configuration file as follows:

1. Make a copy of the preauth sample file in the <js-install>/samples/externalAuth-sample-config/ directory and rename it to remove the sample- prefix. For example, rename sample-applicationContext-externalAuth-preauth.xml to applicationContext-externalAuth-preauth.xml.
2. Edit the file you created and configure the beans correctly for your deployment, as described in the following sections.
3. Place the modified file in the <js-webapp>/WEB-INF directory.

<js-webapp> is the location of the JasperReports Server web application in your application server, or where you are modifying the configuration files, as explained in WEB-INF Directory Location. The rest of this chapter refers to file names alone.

Overview of Token-based Authentication Beans

The sample-applicationContext-externalAuth-preauth[-mt].xml file contains the beans needed to enable token-based authentication. This section summarizes the most important beans in this file, including the beans you need to modify to configure JasperReports Server to work with token-based authentication.

proxyPreAuthenticatedProcessingFilter: Bean which enables token-based authentication. This bean extracts and optionally decrypts the token from the request. When this proxy bean definition is present in the application context, the Spring Security filter chain processes the authentication via the proxy definitions instead of the default internal filter. See Configuring the Token for more information.
preAuthenticatedManager — Lists the available authentication providers. In the case of token-based authentication, there is a single provider, the PreAuthenticatedAuthenticationProvider. This bean does not have to be configured
PreAuthenticatedAuthenticationProvider: Custom authentication provider for token-based authentication. This bean has one property, preAuthenticatedUserDetailsService, which it uses to create the user details from the values passed in the token. See Configuring the Token for more information.
externalDataSynchronizer – Bean whose class creates a mirror image of the external user in the internal jasperserver database.
mtExternalUserSetupProcessor or externalUserSetupProcessor– Bean which creates and configures the internal user corresponding to a successfully authenticated external user. Configure this bean to specify the roles given to external users. See User Roles for more information.
externalTenantSetupProcessor ‑ For multi-tenant deployments, bean which creates and configures the internal organization for a successfully authenticated external user. See Mapping Organizations for more information.
externalProfileAttributeProcessor — Optional processor that sets up user profile attributes. You do not need to configure this processor; the mapping is set up in the token configuration. Comment this bean out if not used.

Configuring the Token

To use your authentication provider with JasperReports Server's token-based authentication, you must pass a correctly formatted token in the HTTP header or the URL of the request. A token is a string of key/value pairs separated by a character specified in the configuration file.

Security of the Token

JasperReports Server will accept any properly formatted token; therefore, you need to protect the integrity of the token using measures such as the following:

Connect to JasperReports Server using SSL to protect against token interception.
Encrypt the token to protect against tampering. See Setting Token Decryption for more information.
Configure the token to use a timestamp to protect against replay attacks. Without a timestamp, when you include the token in a web page or REST web service URL, the URL can be copied and used by unauthorized people or systems. Setting the expire time for the token will stop tokens/URLs from being used to authenticate beyond the indicated time. You can set the expiry time depending on your use case. For a user who is logged into the application/portal and is requesting access to JasperReports Server, expiry time of a minute or less from the request time is appropriate. See the descriptions for expireTime and tokenExpireTimestampFormat in preAuthenticatedUserDetailsService property for more information.

proxyPreAuthenticatedProcessingFilter bean

Some token configuration is specified in the proxyPreAuthenticatedProcessingFilter bean, using the following properties:

principalParameter — A fixed string at the start of the token that triggers token-based authentication. The first time the user accesses JasperReports Server, the principalParameter must be present in the request. principalParameter can be any URL-safe string that is different from all other JasperReports Server request parameter names.
tokenInRequestParam — Boolean that specifies the location of principalParameter, as follows:
     true — JasperReports Server looks for principalParameter in the request URL only.
     false — JasperReports Server looks for principalParameter in the request header only.
     absent — JasperReports Server checks the request header first and then the URL.
tokenDecryptor — Specifies the class to use to decrypt the token. For security reasons, you should encrypt the token to keep its payload from being intercepted when the SSL is not enables, or exposed in the browser's cache. If the token is encrypted, you must provide an implementation of Jaspersoft's token decryptor interface CipherI. The default assumes the token is unencrypted and passes the token through as plaintext.

Setting Token Decryption

If you want to encrypt the token, you need to select the encryption mechanism that will be used to encrypt the token in the calling application and decrypt the token within the JasperReports Server. To implement the token decryption algorithm in JasperReports Server, you must write Java code that implements Jaspersoft's CipherIinterface and include it in the Spring configuration for security. CipherI is located in the com.jaspersoft.jasperserver.api.common.crypto package in the jasperserver‑api.common.[version].jar jar file.

CipherI is a stub interface that allows you to define two methods:

encrypt — takes a text string and returns a text string encrypted according to the specified algorithm
decrypt — takes a text string and returns a text string decrypted according to the specified algorithm.

You can implement any encryption method you choose.

package com.mycompany;
public class MyCipher implements CipherI {
	public String encrypt(String plainText) {
		return cipherText;
	public String decrypt(String cipherText) {
		return plainText;

Once you have created your implementation of CipherI, you need to incorporate it in a jar file and reference it in the tokenDecryptor property of proxyPreAuthenticatedProcessingFilter:

<bean id="proxyPreAuthenticatedProcessingFilter"
  <property name="tokenDecryptor">
    <bean class="com.mycompany.MyCipher"/>

preAuthenticatedUserDetailsService property

The token format is specified using the preAuthenticatedUserDetailsService property in the preAuthenticatedManager bean. An inline bean in preAuthenticatedUserDetailsService lets you specify the token properties. The following example shows one way you might configure this bean:

Sample Code Configuration

<bean class="">
  <property name="preAuthenticatedUserDetailsService">
    <bean class="
      <property name="tokenPairSeparator" value="|"/>
        <property name="tokenFormatMapping">
            <entry key="username" value="u" />
            <entry key="roles" value="r" />
            <entry key="orgId" value="o" />
            <entry key="expireTime" value="exp" />
            <entry key="profile.attribs" >
                <entry key="profileAttrib1" value="pa1" />
                <entry key="profileAttrib2" value="pa2" />
      <property name="tokenExpireTimestampFormat" value="yyyyMMddHHmmssZ"/>

The inline bean has the following properties:

tokenPairSeparator — A single character that is used as the separator for key-value pairs in the token, for example, pipe (|) (default). Cannot include comma (,), question mark (?), or equals sign (=), as these are used elsewhere in the token.
tokenFormatMapping — The mapping between parameters in the token and attributes of the principal object in JasperReports Server, such as roles and profile attributes. Entries in the mapping have the format <entry key ="JRS" value="keyintoken">, for example, <entry key="username" value="u" />. The key, such as username, is a fixed value used in the JasperReports Server code. The value is a parameter in the token that is mapped to the key in JasperReports Server.
tokenFormatMapping supports the following JasperReporst Server fixed values:
username — The external user's username.
roles — The external user's roles. .
orgId (optional; multi-tenant implementations only) — In a multi-organization deployment, the external user's organizations. In a single-tenant deployment, or in a deployment that maps all users to the same organization using defaultOrganization, you can comment out this property.
expireTime — The key for the token expiration time. In the token, takes a single value, a time formatted as configured in the tokenExpireTimestampFormat property.
profile.attribs (optional) — This lets you specify a map of key/value pairs for profile attributes. Comment this out if you do not want to map profile attributes. In this case, you must also comment out the reference to externalProfileAttributeProcessor in the externalUserProcessors property of the externalDataSynchronizer.

The user password does not appear as a standard parameter in the token format. Passwords don’t need to be passed in the token in most cases, since JasperReports Server does not store passwords for externally-defined users. If you wish to store passwords for some reason, you can pass them in using profile attributes.

In addition, tokenFormatMapping supports the following property:

tokenExpireTimestampFormat — The format of the token expiration time, expireTime, based on the java.text.SimpleDateFormat. Valid patterns for timestamps can only contain letters, numbers, dashes, underscores, and periods. The default pattern is yyyyMMddHHmm, for example 2001404150601. For more information about the valid patterns for this field, refer to:

The token has to match the configuration you specify in preAuthenticatedUserDetailsService. With the configuration shown in Sample Code Configuration, you would use the following token syntax in the page header:


In this example, pp (principalParameter) is the name of the header attribute or the URL token parameter name.

If you are passing the token in the URL, you need to encode all equal signs (=) in the token to make the token URL-safe.

The key-value pairs can appear in the token in any order, but must be delineated by the separator specified in the tokenPairSeparator property:

u — Takes a single value that maps to the username in JasperReports Server.
r — Takes as values a comma-separated list of roles; each entry in the list is mapped to a separate role in JasperReports Server. If you have defined default internal roles, this parameter is optional. See User Rolesfor more information.
o — Takes as values a comma-separated list that maps to an organization in the JasperReports Server. If more than one organization is listed, it is interpreted as an organization hierarchy. For example, o=A,B maps the user to the B suborganization of A.
exp — Takes a single time value formatted as configured in the tokenExpireTimestampFormat property. If exp is before the current time, user authentication is denied; if it is absent, the token never expires.
pa1 — Profile attribute that maps to profileAttrib1 in the JasperReports Server repository.
pa2 — Profile attribute that maps to profileAttrib2 in the JasperReports Server repository.

With this configuration, the following would be a valid token. The user would be placed in the Sales suborganization of the EMEA organization:


In the URL, you would need to encode all equal signs (=) in the token to make the token URL-safe:


User Roles

User roles are mapped using the externalUserSetupProcessor or mtExternalUserSetupProcessor bean. See the configuration file for your deployment to see which bean applies in your case. For token-based authentication, you can define user roles in the following ways:

Map the user roles received from the token – Define a mapping between roles in the external authority and roles in JasperReports Server. See Mapping User Roles for more information.
Define user roles statically – If you do not have user roles in the token, you can define static roles for administrative and non-administrative users. See Defining User Roles Statically for more information.

Mapping User Roles

If you have user roles in the token, you can map them to roles in JasperReports Server using the organizationRoleMap property of the externalUserSetupProcessor or mtExternalUserSetupProcessor bean.

The organizationRoleMap property contains key/value pairs that map external role names to internal ones. For commercial JasperReports Server deployments, you need to choose the level at which the role is assigned:

To map to an internal role at the organization level, append |* to the name of the internal role, for example, ROLE_USER|*. Roles mapped at the organization level do not have administrative privileges.
To map to an internal role at the system (null) level, do not modify the internal role name, for example, ROLE_ADMINISTRATOR. Roles at the system level are usually reserved for special users such as the system administrator and allow access to the repository folder of all other organizations.

The following example shows how you might configure the externalUserSetupProcessor bean to map roles from the external authority to roles in JasperReports Server:

<bean id="externalUserSetupProcessor" class="com.jaspersoft.jasperserver.api.metadata.
<property name="organizationRoleMap">
    <!-- Example of mapping customer roles to JRS roles -->

Setting Default Roles

In addition to the roles set using the organizationRoleMap property, you can assign roles to all users using the defaultInternalRoles property of externalUserSetupProcessor or mtExternalUserSetupProcessor. The following example shows how to use this property in externalUserSetupProcessor to assign ROLE_USER to all users, in addition to any roles they are assigned during mapping:

  <property name="defaultInternalRoles">

Avoiding Role Collisions

If an external role has the same name as an internal JasperReports Server role at the same organization level, then a suffix, such as _EXT, is appended to the external role name to avoid collisions. For example, a user with the externally defined role ROLE_ADMINISTRATOR is assigned the role ROLE_ADMINISTRATOR_EXT in the JasperReports Server database. This ensures that internal administrator accounts such as jasperadmin and superuser can still login as internal administrators, with the associated permissions.

You can set the extension in the conflictingExternalInternalRoleNameSuffix property in the externalUserSetupProcessor or mtExternalUserSetupProcessor bean. If the property does not appear in the bean, the extension is still implemented but defaults to _EXT. The following example shows how to configure this property:

<bean id="externalUserSetupProcessor" class="com.jaspersoft.jasperserver.api.
  <property name="conflictingExternalInternalRoleNameSuffix"
  <property name="organizationRoleMap">
     <!-- Example of mapping customer roles to JRS roles -->

Restricting the Mapping to Whitelisted Roles

You may not want every available role in your external authority to appear as a role in JasperReports Server. Use the permittedRolesRegex property of the externalUserSetupProcessor bean or mtExternalUserSetupProcessor bean to specify which roles in your external authority become roles in JasperReports Server. You can use regular expressions to specify multiple roles that match the expression.

For example, to restrict the roles you create in JasperReports Server to roles that begin with JRS_ or EXT_ in your external authority, you would configure permittedRolesRegex in a way similar to the following:

        <property name="permittedRolesRegex">

To allow all roles, you can use .* or comment out the property. If the property is omitted, all roles in the external authority are synchronized with roles in JasperReports Server.

Supporting Additional Characters in Role Names

The default mapping from attributes in your external authentication server to roles in JasperReports Server restricts the allowed characters to alphanumeric characters and underscores. If a role in your external authority contains characters which are not supported, each sequence of unsupported characters is replaced with a single underscore. For example, ROLE$-DEMO)EXT maps to ROLE_DEMO_EXT.

You can extend the supported character set by modifying the permittedExternalRoleNameRegex property of the externalUserSetupProcessor bean or mtExternalUserSetupProcessor bean. Check the sample configuration file for your deployment to determine which bean to modify:

The default value of the permittedExternalRoleNameRegex property is the regular expression [A-Za-z0-9_]+. Edit this expression to add supported characters. For example, the following syntax allows alphanumeric characters, underscores, and the Cyrillic letter Я (Unicode 042F):

<bean id="mtExternalUserSetupProcessor"
 <property name="userAuthorityService">
   <ref bean="${bean.internalUserAuthorityService}"/>
 <property name="permittedExternalRoleNameRegex"

Defining User Roles Statically

If you are mapping all your external users to a single organization, you can assign roles to users statically. This lets you specify a list of administrative users and roles, as well as a list of roles for non-administrative users. To define user roles statically, use the externalUserSetupProcessor or mtExternalUserSetupProcessor bean. To set up static roles, locate the version of the bean that is used in your sample file and configure the following properties:

adminUserNames property – A list of usernames that are granted internal administrator privileges in JasperReports Server. The username values must match exactly the usernames authenticated and returned by the LDAP server.
defaultAdminRoles property – A list of JasperReports Server internal roles; these are assigned to every user in the list of administrators.
defaultInternalRoles property – A list of JasperReports Server roles that are assigned to every user not in the list of administrators.

The following example shows how to use the externalUserSetupProcessor bean to define static roles. The configuration for mtExternalUserSetupProcessor is identical:

<bean id=externalUserSetupProcessor" class="com.jaspersoft.jasperserver.api.metadata.
  <property name="adminUsernames">
  <property name="defaultAdminRoles">
  <property name="defaultInternalRoles">

Mapping Organizations

There are two ways to set the user organization:

If you have multiple organizations in your deployment, set up the token to contain organization information as above. If you want organization names in JasperReports Server to be different from the ones in the external authority, use the organizationMap property, as described in Mapping Organization Names.

If your JasperReports Server has multiple organizations, but you want all users to be in the same organization, use the externalTenantSetupProcessor bean to specify the organization, as described in Specifying a Single Organization; in this case you do not need to include organization information in the token.

If your JasperReports Server deployment only supports a single organization (all community deployments and some professional editions), you do not need to set organization information.

Mapping Organization Names

You can use the organizationMap property in the externalTenantSetupProcessor bean to map organization names extracted from your external authority to organization names in JasperReports Server. To do this, create a key/value pair for each organization you want to map, specifying the external organization name as the key and the organization name in JasperReports Server as the value.

The organizationMap property is optional. Any organization in your external authority that is not listed in organizationMapis mapped to an organization of the same name in JasperReports Server.

For example, the following would map users in External_Org_1 in the external authority to JRS_Org_1 in JasperReports Server and users in External_Org_2 in the external authority to JRS_Org_2 in JasperReports Server:

    <property name="organizationMap">
            <entry key="External_Org_1" value="JRS_Org_1" />
            <entry key="External_Org_2" value="JRS_Org_2" />

If a user is in an organization that does not have an entry in organizationMap, then the organization is created. If the map is empty, all external organizations are mapped to internal organizations with the same name.

Specifying a Single Organization

In a multi-tenant deployment, if you do not have organization information in your token, your users are mapped to the NULL organization, which means they will be given root privilege. If your deployment has only one organization, this organization is used by default.

If you have multiple organizations in your deployment, you can use the externalTenantSetupProcessor bean to specify a single organization that is assigned to all external users. To do this, set externalTenantSetupProcessor’s defaultOrganization property to the organization ID of the desired organization. If an organization with that ID already exists, all external users are assigned to that organization; if the organization does not exist, it is created when the first external user authenticates correctly.

When specifying the defaultOrganization value, the organization ID must not contain the following characters: |, &, *, ?, <, >, /, \, ~, !, #, $, %, ^, [, or ].

The following example shows how to configure to assign all users to organization_1:

<bean id="<MadCap:conditionalText data-mc-conditions="AuthSnippetConditions.CASsnippet,AuthSnippetConditions.DBsnippet,AuthSnippetConditions.PreAuthSnippet">externalTenantSetupProcessor</MadCap:conditionalText>" class="com.jaspersoft.jasperserver.multipleTenancy.
    security.externalAuth.processors.<MadCap:conditionalText data-mc-conditions="AuthSnippetConditions.CASsnippet,AuthSnippetConditions.DBsnippet,AuthSnippetConditions.PreAuthSnippet">MTExternalTenantSetupProcessor</MadCap:conditionalText>"     parent="abstractExternalProcessor">
  <property name="multiTenancyService">
    <ref bean="internalMultiTenancyService"/>
  <property name="defaultOrganization" value="organization_1"/>

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

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 Initialization of JasperReports Server for External Users for a process to initialize JasperReports Server, including organization administrators, before going into production with external authentication.

Adding a Custom Processor

To create custom code to run on the server after the user has been authenticated, you can create a custom processor and add it to the processors list for the externalUserProcessors property of the externalDataSynchronizer bean. For example, you can add a processor that calls code to automatically create a user home folder for the authenticated user. See Creating a Custom Processor for more information.

Restarting JasperReports Server

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

To test your configuration, log in to your external authority and request a page from JasperReports Server. If the token and server are configured correctly, you can access JasperReports Server. Try several users with different roles or organizations to verify your configuration.