Defining Roles for a Library-based Client
Set up role sets defining permissions that are specifically designed for a client application based on the developer libraries.
Table of Contents
Introduction
In yuuvis® Momentum, permissions are controlled via roles that can be assigned to users. Business integrators define roles according to specific needs in role sets. Any request to yuuvis® Momentum is enriched with the logged-in user's roles in order to decide whether the corresponding permissions allow the requested action. Before you continue reading through the description of client-specific role sets, please have a look at the general structure of role sets in yuuvis® Momentum.
>> Access Authorization and Permissions
Furthermore, a library-based client can also react to further roles that are not defined in a yuuvis® Momentum role set but only in the identity provider.
This article describes how to configure roles for use in a library-based client.
Notes:
- The easy switching between tenants provided via the default YUUVIS_MULTI_TENANT role cannot be provided via a different role.
- If you want to use yuuvis® architect, all default roles are required.
Role Sets
Roles that directly or indirectly allow for the interaction with the core system need to be defined in a yuuvis® Momentum role set.
Within a role set, any role allowing actions on DMS objects with specific types require a specific structure of conditions: It is necessary to specify the object type by both its system:objectTypeId and its system:secondaryObjectTypeIds. An example condition is provided in lines 12 and 19 in the example client app role set below.
<roleSet xmlns="http://optimal-systems.org/ns/dmscloud/roleset/"
<role>
<name>MINIDOCcrud</name>
<permission>
<action>create</action>
<action>read</action>
<action>write</action>
<action>delete</action>
<condition>system:objectTypeId = 'appClient:minidoc' AND system.secondaryjectTypeIds = 'appClient:minidoc'</condition>
</permission>
</role>
<role>
<name>MINIDOCread</name>
<permission>
<action>read</action>
<condition>system:objectTypeId = 'appClient:minidoc' AND system:secondaryobjectTypeIds = 'appClient:minidoc'</condition>
</permission>
</role>
</roleSet>
It is also possible to specify such conditions with a LIKE operator as shown in the example mytenant tenant role set below.
<roleSet xmlns="http://optimal-systems.org/ns/dmscloud/roleset/">
<role>
<name>QA_MANAGER</name>
<permission>
<action>create</action>
<action>read</action>
<action>write</action>
<action>delete</action>
<condition>system:objectTypeId LIKE 'tenKolibri:qa%' AND system:secondaryobjectTypeIds LIKE 'tenKolibri:qa%'</condition>
</permission>
</role>
</roleSet>
Default Roles
The following global role set is configured per default after the installation of yuuvis® Momentum. The roles are defined via the CONFIGSERVICE as well as in the identity provider.
<roleSet xmlns="http://optimal-systems.org/ns/dmscloud/roleset/">
<role>
<name>YUUVIS_DEFAULT</name>
<permission>
<action>create</action>
<action>read</action>
<action>write</action>
<action>delete</action>
</permission>
</role>
<role>
<name>YUUVIS_TENANT_ADMIN</name>
<permission>
<action>create</action>
<action>read</action>
<action>write</action>
<action>delete</action>
</permission>
</role>
<role>
<name>YUUVIS_SYSTEM_INTEGRATOR</name>
<permission>
<action>create</action>
<action>read</action>
<action>write</action>
<action>delete</action>
</permission>
</role>
</roleSet>
Additionally, the client application roles YUUVIS_MANAGE_SETTINGS and YUUVIS_MULTI_TENANT are defined in the identity provider (here Keycloak). Those roles are not defined in a yuuvis® Momentum role set. Overall, the following roles are available and provide the described permissions.
| Role | Defined in | Permissions in a client | Permissions in yuuvis® architect |
|---|---|---|---|
| YUUVIS_DEFAULT | yuuvis® Momentum role set AND identity provider | Users have full access to all objects. | no impact |
| YUUVIS_SYSTEM_INTEGRATOR | yuuvis® Momentum role set AND identity provider | Administrative object information is provided to users in the metadata form of any object in the system. | Users can modify metadata forms for any object type defined in the global system schema or in an app-specific schema. Users can add or delete users of their own tenant and assign roles to them. Users can customize the language settings for their own tenant. |
| YUUVIS_TENANT_ADMIN | yuuvis® Momentum role set AND identity provider | Administrative object information is provided to users in the metadata form of any object in the system. | Users can modify metadata forms for any object type defined in the tenant-specific schema. Users can add or delete users of their own tenant and assign roles to them. Users can customize the language settings for their own tenant. |
| YUUVIS_MANAGE_SETTINGS | identity provider | Users are allowed to customize the global standard configurations for hit lists and filters in the settings menu. Those standards will be the default settings for (new) users that have not yet saved their own user-specific standard configurations. As of 2022 Summer, in the default configuration, the role enables the retention management view and allows to set or extend the expiration date for individual document objects. | As of 2022 Autumn, users can manage other users of their own tenant but cannot assign the roles YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR to them. Furthermore, users with one of those two roles cannot be edited or deleted. |
| YUUVIS_MULTI_TENANT | identity provider | Users with accounts in multiple tenants can easily switch between their tenants via Switch tenant instead of a conventional logout. | Users with accounts in multiple tenants can easily switch between their tenants via Switch tenant instead of a conventional logout. |
Custom Roles
You can replace the default roles by custom roles according to your needs. Roles allowing access to the yuuvis® Momentum backend functionality have to be defined in a role set AND in the identity provider. Roles that are only used to tune the client application's behavior can be defined only in the identity provider. Those roles can be specified as client-specific administrative roles via the main.json configuration file.
>> Customizing the Main Configuration
Note: Avoid the usage of too many roles and lengthy role names as also mentioned in Access Authorization and Permissions.
Summary
Define roles allowing for the yuuvis® Momentum backend functionality in a role set and in your identity provider. Roles for pure client-side functionality do not have to be defined in a role set. It is enough to define them in the identity provider.