Page Properties | ||||
---|---|---|---|---|
| Status | |||
Status | ||||
colour | Yellow | |||
title | progress | |||
Priority | 2 | Note | ||
Assignee | Inga for review |
Excerpt |
---|
This article explains how changes to the role set files can be made to add or remove permissions to individual users. |
...
| ||||||||||||||||||||||||||
Resources & Remarks Modification History
|
Excerpt |
---|
A yuuvis® Momentum user has to be authorized to the functionality of the system by assigning roles. For the individual roles, permissions can be set to allow actions on objects restricted by defined conditions where appropriate and the usage of specific endpoints can be controlled. |
Section | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Requirements
To work through this tutorial, the following is required:
- Set-up yuuvis® API system (see minikube setup, for example)
Assigning Roles to Individual Users
When a user first logs in at the beginning of a session, he recieves a JSON Web Token in which the users' roles are listed under "authorities".
To assign individual roles to the users of the system, either an organization.xml
file is evaluated in the same Organization service configuration (~/config/organization
) or an external identity provider is used, which takes over the responsibility for role assignment from the organization.xml
, causing that file to no longer be evaluated. In both solutions, individual UUIDs or names of individual users are assigned to roles by their unique names as defined in the roleset.xml
file.
Code Block | ||||
---|---|---|---|---|
| ||||
<user>
<name>Emil</name>
<role>RoleEmail</role>
</user> |
Trusted Mode
If an identification provider is active in your system, the role administration duties can be transferred to the organization service using Trusted mode, which can be activated by running the authentication-service using the value "trusted" in the authentication.provider parameter and the organization service using the profile "trusted". Doing so delegates the role-user-mapping to the config/organization/organization.xml file, which can be modified, like any other file managed by the Configuration service, using the config git repository.
Code Block | ||
---|---|---|
| ||
<?xml version="1.0" encoding="utf-8"?>
<organization xmlns="http://optimal-systems.org/ns/dmscloud/organization/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/organization/ dmsCloud-organization.xsd">
<user>
<name>root</name>
<role>AdminRole</role>
</user>
<user>
<name>Emil</name>
<role>RoleEmail</role>
</user>
<user>
<name>Doris</name>
<role>RoleDocument</role>
</user>
<user>
<name>Eduard</name>
<role>RoleEmail</role>
<role>RoleDocument</role>
</user>
<user>
<name>Edmund</name>
<role>RoleEmailAndDocument</role>
</user>
</organization>
|
Adding/Removing Permissions by Directly Accessing the Config Git Repository
To make changes to the authorization system, such as to give roles new access rights or assign new roles or revoke old ones from individual users, changes must be made to the corresponding configuration files roleset.xml
and organization.xml
in the organization service configuration. Through syntactically correct adjustments to the existing authorization structure, such as adding new role objects in the roleset.xml
or deleting a role of a user in the organization.xml
, the authorization system can be changed to meet the requirements of your system.
Because the configuration files in Kubernetes are in a git repository "system-config", changes are made effective by committing a new configuration version to this git repository. First, the current state of the git repository has to be downloaded into a local directory via git clone http://<Cluster IP>:<Git Port>/system/system-config
, after which the desired changes to the respective configuration files can be made to that state of the configuration files. Then the new state of the files has to be uploaded to the config repository via git add*
→ git commit -m "new config"
→ git push
.
The authorization system works by using the Organization service, which is configured through the roleset.xml
and organization.xml
and provides information about the access rights for individual users. To tell the Organization service to retrieve its new configuration from the Config service, a POST request must be made to the /api/security/refresh
endpoint of the Organization service after each configuration change. If an identity provider is used, meaning that role assignment is carried out not through the organization.xml
but through an external system, and changes are made only to the role assignment inside the identity provider, the Organization service does not need to be refreshed.
...
|
Introduction
The Core API protects documents against access by unauthorized persons through a permission system. Each user has one or more roles in this system, giving them access to various documents for specified actions. The user-role mapping manages the assignment of roles to users. In yuuvis® Momentum, this mapping is managed separately from the authentication process itself and can be configured according to the customers' needs. Furthermore, in the configuration of the yuuvis® AUTHENTICATION service, access conditions can be defined individually for each API endpoint.
Structure of the Permissions System
Anchor | ||||
---|---|---|---|---|
|
Roles and Role Sets
The permissions to access documents or to perform certain actions are assigned to specific roles. Users of the system are assigned to particular roles, and through those role assignments acquire the permissions needed—they become the owner of the roles. In general, roles are reusable groups of various permissions. Each role has a unique name and contains one or more permissions that are granted to its owners.
Note: In the header of each incoming and authenticated API call, the roles of the corresponding user are included among other user-specific information. If you assign too many roles with long names to individual users, you might exceed the overall size limit of 8 KB for the header.
Permissions
Permissions denote access rights to certain objects and are assigned to a role. A permission consists of one or more actions and, optionally, a condition. The condition defines which objects are allowed to be managed by owners of a role with the permission, whereas actions define what procedures are allowed upon meeting the condition. In other words, if a user tries to access an object, the authorization system will go through that user's roles to see if one of the conditions within their permissions is met by the object. If the object meets the condition of one of the user's permissions, the user will be able to work with the object according to the actions defined by that permission.
Actions
The actions of a permission specify access rights for specific purposes, whereby a distinction is currently made between create
access, read
access, delete
access and write
access. The actions can be combined by simply adding multiple actions to the permission.
create (as of 2021 Autumn) | permission to create new objects |
read | permission to know about the existence of objects, to receive them in search results and to call various GET endpoints to a special object |
delete | permission that allows to delete content or metadata of objects for which also read permission is granted |
write | permission to update objects or to move the content of objects for which also read permission is granted |
Conditions
Conditions are statements in the proprietary CMIS-based query language that define the subset of documents in the system affected by a permission. If the condition for a document is met (meaning evaluating the query language expression returns 'true'), the owner of the role gets to access that document. For example, conditions can limit a user's access to a specific type of object or hide documents that are older than a specific date. The conditions are applied to all requests from the role owner and thereby act as filters for the corresponding search results.
Note: In a permission the CONTAINS()
query function cannot be used in a condition. The whole statement would always be evaluated as false
, even if the condition contains other sub-statements that do not use CONTAINS()
and that would individually considered be evaluated as true
.
The condition can also be left out – indicating that the permission applies to all documents in the system.
The following code block explains the definition of permissions with an example of creation permissions assigned to different roles.
Code Block | ||||
---|---|---|---|---|
| ||||
<!-- This role does not grant any permission to create, update or delete any object. -->
<role>
<name>CAN_CREATE_NOTHING</name>
</role>
<!-- This role grants creation permission for any object. No conditions have to be matched. -->
<role>
<name>CAN_CREATE_EVERYTHING</name>
<permission>
<action>create</action>
</permission>
</role>
<!-- This role grants creation permission for objects that match the condition. In this case, only objects of type 'appTable:order' or 'appEmail:email' can be created. -->
<role>
<name>CAN_CREATE_SOMETHING</name>
<permission>
<action>create</action>
<condition>
system:objectTypeId IN ('appTable:order', 'appEmail:email')
</condition>
</permission>
</role> |
As of 2023 Summer, it is possible to specify conditions referencing the abac
(attribute-based access control) section within the internal JWT (JSON Web Token). The following example role grants read permission for objects with at least one entry of the string list property appEmail:mailboxes
contained in the current user's @abac.mailGroups
string list within the JWT.
Code Block | ||||
---|---|---|---|---|
| ||||
<role>
<name>CAN_CREATE_SOMETHING</name>
<permission>
<action>read</action>
<condition>
appEmail:mailboxes IN @abac.mailGroups
</condition>
</permission>
</role> |
Anchor | ||||
---|---|---|---|---|
|
Endpoints for Managing Permissions
The following endpoints are available for setting up and managing your tenant-specific permissions system:
- Retrieve the tenant role set - GET /api/admin/permissions
- Update the tenant role set - POST /api/admin/permissions
- Validate the tenant role set - POST /api/admin/permissions/validate
For system administrators, the following endpoints are available for managing the global permissions system:
- Retrieve the global role set - GET /api/system/permissions
- Update the global role set - POST /api/system/permissions
- Validate the global role set - POST /api/system/permissions/validate
Since version 2.4, yuuvis® Momentum has the ability to further structure the global role set into applications. This goes hand in hand with the usage of application schemata, as the new functionality is meant to exclude any role set entries related to an optional application schema from the main global role set.
- Retrieve a global application role set - GET /api/system/apps/{app}/permissions
- Update a global application role set - POST /api/system/apps/{app}/permissions
- Validate a global application role set - POST /api/system/apps/{app}/permissions/validate
To streamline the process of defining yuuvis® Momentum role sets, a number of REST endpoints have been were made available to retrieve the current role set structures and to to apply modifications. As seen in the permissions concept page, there are three options used to structure the role set, coming from two endpoint categories. The /system/permissions
and /system/apps/{app}/permissions
endpoints are both used to modify the global role set applicable to all users of the system, whereas the /admin/permissions
endpoint serves to change the role set specific to the current tenant.
Complete role set files can be supplied to one of the endpoints via an HTTP POST request, overwriting the previous role set present at that locationposition. Thus, retrieving and extending the previous role set state by using a GET request on the same endpoint is strongly recommended. New role sets can also be validated by posting them to the role set endpoint URLs using the added URL suffix /validate
.
>> Code examples in gitHub
Role Administration
Summary
...
Defining Roles
The roles are defined in role sets. Each role set is stored via the CONFIG service in a file roleset.xml
that should only be changed using the above listed endpoints.
A role has a name and a list of permissions. Each permission can have one or more actions: read
, delete
and write
. Additionally, they can be restricted by a condition.
Example: a read-permission with the condition system:objectTypeId = 'email'
allows to receive all objects of type 'email'
in search results and to call various GET endpoints for this type of objects.
Code Block | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="utf-8"?>
<roleSet xmlns="http://optimal-systems.org/ns/dmscloud/roleset/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/roleset/ dmsCloud-roles.xsd">
<role>
<name>RoleEmail</name>
<permission>
<action>read</action>
<condition>system:objectTypeId = 'email:email'</condition>
</permission>
</role>
<role>
<name>RoleDocument</name>
<permission>
<action>read</action>
<condition>system:objectTypeId = 'document'</condition>
</permission>
</role>
<role>
<name>RoleEmailAndDocument</name>
<permission>
<action>read</action>
<condition>system:objectTypeId in ('email:email', 'document')</condition>
</permission>
</role>
<role>
<name>AdminRole</name>
<permission>
<action>read</action>
<action>delete</action>
</permission>
</role>
</roleSet> |
>> The XSD for role sets: dmsCloud-roleSet.xsd.
Note: For the usage of some Additional Services a fixed role set is required.
>> Defining Roles for a Library-based Client
Anchor | ||||
---|---|---|---|---|
|
User-Role Mapping
When users log in at the beginning of a session and are successfully authenticated by the identity provider, a JSON web token is generated in which the users' roles are listed under authorities
. The GET user.info webhook is responsible for providing the users' roles. By customizing the webhook, it is possible to connect any access management provider delivering the users' roles in a suitable format. Per default, the webhook calls the ORGANIZATION service that is responsible for providing the role information.
To assign individual roles to the users of the system, an external identity provider is used, which takes over the responsibility for role assignment. Per default, the ORGANIZATION service reads the keycloak
profile and thus requests the information from the identity provider Keycloak.
In order to run the ORGANIZATION service in Keycloak mode, the keycloak
profile has to be activated and the following connection parameters in the application-oauth2.yml profile are required:
keycloak.server
keycloak.admin.username
keycloak.admin.password
Note | ||
---|---|---|
| ||
The roles of users control their rights regarding DMS objects but also regarding yuuvis® Momentum administration. In the default configuration, e.g., the YUUVIS_SYSTEM_INTEGRATOR role allows editing of global configuration files like role sets and schemata. Thus, it is highly important to configure your role management software such that only system operators can assign roles that provide themselves and other users with global rights. |
Access Authorization for Endpoints
The AUTHENTICATION service decides for each API request of any user if the access is granted or not. In its configuration, the access conditions can be defined individually for each API endpoint. Thus, permissions in yuuvis® Momentum can be set not only for types of actions and the usage of specific object types, but also directly for API endpoints. It is even possible to allow the usage of an API endpoint for callers without authentication.
Summary
This article explained the role-based structure of the permission system provided by the Core API. The global and the tenant-specific role set can be changed via the corresponding endpoints. The user-role mapping can be managed in Keycloak. The access authentication for individual yuuvis® API endpoints can be configured via the AUTHENTICATION service.
Info | |||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||
More TutorialssectionRead on
|