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 extracts roles from an external data source or specifies them statically in the configuration file. Because each external authority may have its own mechanism, this guide 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:

Modifying Role Mappings

Once you have set up external authentication with your JasperReports Server instance, you add new role mappings by editing the applicationContext-externalAuth-*.xml file. You need to restart the server for the changes to take effect.

Care should be taken when modifying or removing role mappings. When a role mapping is removed or changed, synchronization no longer updates the target role in JasperReports Server. This means that users who had the external role prior to the change still have the previous target role in JasperReports Server. You can work around this by creating a mapping from a non-existing role definition in the external authority to the target role you want to remove.

For example, suppose you have an role definition in your external authority, Sales Manager, and you initially map it to ROLE_ADMINISTRATOR in JasperReports Server. A user, Mandy Sales, is a Sales Manager and has logged in to JasperReports Server; she has been assigned ROLE_ADMINISTRATOR. You then create a new role in JasperReports Server, ROLE_SALES_MANAGER, and modify your role mapping so Sales Manager in the external authority is now mapped to ROLE_SALES_MANAGER in JasperReports Server. You then restart the server.

By default, the next time that Mandy Sales logs in, she is assigned ROLE_SALES_MANAGER. However, because ROLE_ADMINISTRATOR no longer appears in your application context file, the synchronization process does not check for it and it is not removed. Mandy Sales now has two roles: ROLE_ADMINISTRATOR and ROLE_SALES_MANAGER.

You can remove ROLE_ADMINISTRATOR from Mandy Sales by creating a dummy mapping with ROLE_ADMINISTRATOR as the target. For example, if no one in your external authority has the role definition No Such Role, you can add a mapping from No Such Role to ROLE_ADMINISTRATOR to your application context file and restart the server. In this case, the next time Mandy Sales logs in, the synchronizer finds that Mandy Sales does not have the No Such Role role definition and removes ROLE_ADMINISTRATOR.