The roles that an external user has in JasperReports Server are imported from the external data source and stored in the internal JasperReports Server database. External roles can be reflected as new external roles in JasperReports Server or they can be mapped to internal roles.

Retrieving Roles from the External Database

To configure the retrieval and mapping for user roles in sample-applicationContext-externalAuth-db-mt.xml file, first make sure you have set up the externalUserTenantDetailsService bean as described in Configuring User Authentication and Authorization via Database Queries. Then configure externalUserSetupProcessor to map the external information to roles in the JasperReports Server as follows:

The following example shows how to configure the organizationRoleMap property:

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:

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.    user.service.impl.UserDetailsServiceImpl">	...  <property name="adminUsernames">    <list>      <value>myorgadmin</value>    </list>  </property>[/code]                    

  <property name="defaultAdminRoles">    <list>      <value>ROLE_USER</value>      <value>ROLE_ADMINISTRATOR</value>    </list>  </property>[/code]                    

  <property name="defaultInternalRoles">    <list>      <value>ROLE_USER</value>    </list>  </property>[/code]

...[/code]                    

Setting Default Roles

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">    <list>      <value>ROLE_USER</value>    </list>  </property>[/code]                    

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.      metadata.user.service.impl.UserDetailsServiceImpl">  <property name="conflictingExternalInternalRoleNameSuffix"        value="_EXTERNAL"/>  <property name="organizationRoleMap">      ...     <!-- Example of mapping customer roles to JRS roles -->      ...  </property>[/code]                    

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">            <list>                <value>JRS_.*</value>                <value>EXT_.*</value>            </list>        </property>[/code]                    

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"  class="com.jaspersoft.jasperserver.api.security.        externalAuth.processors.ExternalUserSetupProcessor"      parent="abstractExternalProcessor"> <property name="userAuthorityService">   <ref bean="${bean.internalUserAuthorityService}"/> </property>  ..... <property name="permittedExternalRoleNameRegex"     value="[A-Za-z0-9_u042F]+"></bean>[/code]                    

Do not allow the following in role names: spaces, periods or |, [ ], `, ", ', ~, !, #, $, %, ^, &, [,], *, +, =, ;, :, ?, <, >, }, {, ), (, ], [, /, or . Adding these characters in the permittedExternalRoleNameRegex property may cause unexpected behavior, such as the inability to delete or edit roles containing those characters.