Synchronization of Roles

Roles 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 the external authentication mechanism, there are three types of roles in JasperReports Server:

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 defined in the external authority.
An internal role is a role created by a JasperReports Server administrator. Internal roles should be mapped from roles in the external authority; they should not be assigned manually by an administrator. If a mapping exists for an internal role, it takes precedence over a manual assignment by an administrator, which means that a manually assigned role can be removed during synchronization.
A system role is one of the roles created during the JasperReports Server installation, such as ROLE_DEMO. System roles are handled exactly like internal roles above.

In the first phase of synchronization, the principal object has a set of role names that are assigned 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 target roles are created within the organization mapped for the user.
If a role with the target name is already defined in JasperReports Server, this role is assigned to the user; otherwise a new external role with this name is created and assigned.
By default, roles are mapped to external roles, even if there is an internal role with the same name. If an external role name conflicts with an existing internal role in the target organization, a suffix, such as _EXT, is added to the role name.
You must explicitly map external roles to internal roles. If you are mapping a role to an internal role, you can specify whether to assign the internal role at the organization level or at the system (root) level. Roles mapped at the organization level do not have administrative privileges. 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. To map to an internal role at the organization level, append |* to the name of the internal role; to map to an internal role at the system level, do not modify the internal role name.

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 does not have the role, it is assigned to the user by the synchronization mechanism.
As of JasperReports Server 5.2, external roles assigned to the user account 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.
As of JasperReports Server 5.2, internal and system roles that were created automatically by the synchronization during a previous login but that are no longer among the roles mapped and identified from the external authority are removed from the user. If an internal role that was assigned or removed by an administrator appears in the mapping configuration, the mapping from the external role takes precedence. This means that a manually assigned role may be added or removed according to the state of the external database. Therefore, in order for synchronization to automatically make all roles reflect those in the external authority, you should not manually assign any internal roles that appear in the mapping from the external database.

In JasperReports Server 5.1 and earlier, once an external role was applied to a user, it could only be removed manually by an administrator. For details, see the edition of this guide that applies to your version of the product.

The following figure shows how internal and external roles can be assigned to external users. This user has three roles: two internal (ROLE_USER and ROLE_ADMINISTRATOR) and one external (ROLE_SUPER). When the user is opened for editing, the administrator can only assign internal roles; external roles are assigned by synchronization.


External User with Internal and External Roles