Access Authorization and Permissions

...

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.  

<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. 

<?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.

Adding/Removing Permissions using the System/Admin Endpoints

To streamline the process of defining yuuvis® Momentum role sets, a number of REST endpoints have been 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 location. 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

Summary

Now that you know how you can interact with the permission system, you may want to proceed to creating a permissions file befitting your requirements. Find example permission files in the Permissions via Roles concept article. 

Permission System via Roles

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 is managed separately.

>> Permissions via Roles

User-Role-Mapping

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. Per default, the ORGANIZATION service is used, which can either read the information from a configuration file ("trusted") or request the information from the identity provider Keycloak.

>> Assigning Roles to Users

Define Permissions for Endpoints

The yuuvis® 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.

>> Access Authorization for Endpoints