Authorization

Authorization is performed through roles and permissions as shown in the access control explanations.

This documentation explains in more detail how roles, permissions and role assignments work.

Model

The following class diagram represents the main elements that will allow using permissions for managing authorization, and checking authorization when a user tries to perform a task. We will go through the details of various parts on this diagram to explain role assignments.

Roles

A role is a set of permission assignments. A permission assignment is one permission linked to an entity type.

We can describe a role with triplets of role, permission, entity type. Let's see an example role, consisting of the following permission assignments:

(technician, read, tenant)
(technician, read, device)
(technician, create, device)

This means that anyone with a Technician role can read tenant information, read device information, and create new devices.

Permission assignment restrictions

Not all permissions can be performed on all entities. For example, the permissions Edit metadata or Move folder does not make sense on a tenant, but can be performed on a device.

To keep track of these possibilities, each permission is linked to a set of applicable entity types that make sense for the permission.

Role assignments

Role assignments give users rights to perform actions on the platform.

A Role assignment has three parts: a role, a principal, an identity. The principal is allowed to exercise a role, in the scope of the identity.

Let's take a closer look at principals and identities.

Principal

A principal represents a way to acquire roles. There are two principals in the platform: users and user groups. This way, a role can get assigned either to a single user or to a whole group of users.

Currently, the API only supports role assignments through user groups.

Identity

An identity represents the scope on which the role gets assigned. An identity can represent any instance of an entity in the platform, and can be recognized using its entity ID and type.

Example

Say we have a user Alice and a user group Paris. Alice is part of the Paris group.

There is a tenant Water surveillance. The tenant has two devices WS01, WS02. Each device is in a separate folder that contains the device name.

There are two roles, Client and Technician which can be described with the following permission assignments (role, permission, entity type):

(Client, read, tenant)
(Client, read, device)

(Technician, read, tenant)
(Technician, read, device)
(Technician, read, user)
(Technician, create, device)
(Technician, delete, device)

If we consider the following role assignments as (identity, role, principal):

(Water surveillance, Client, Alice)
(WS01 folder, Technician, Paris)

Alice can:

• read all tenant information and devices of tenant Water surveillance thanks to her personal role assignment as a Client
• read, create, and delete devices in the folder WS01 folder thanks to the role assignment on her group Paris

Alice cannot:

• create or delete devices in WS02 folder
• read users on the tenant Water surveillance

Alice cannot read users on the tenant, since her role containing read, user is assigned to the scope of a folder instead of a tenant.

Users are registered on tenants, and not on folders, therefore any role containing read, user should be assigned on a tenant level scope in order to be used.