Security

The Basics

By default users can do nothing!

If they can do something, it is because they have been granted permission to do that.

Exceptions to the rule are:

• Reading your own user details Meaning: a logged in user can see his name, email, tenants, ...

• Access all security roles Roles define which permissions are granted to users in that role. This in itself is considered 'public' knowlegde.

Permissions are defined in a role, and roles are assigned to users. A user can be assigned multiple roles. A role consists of rules (= permissions). Assigning a role can never take away permissions from a user.*

Definitions and naming

Role

Roles are the main container used to assign permissions to users. A single role can have multiple permissions known as "rules". It is the role that is eventually assigned to the users.

Rule

A Rule is the combination of 3 parts

• A key i.e. "meta.document.rec"

• A grant i.e. "read"

• A condition [optional] limiting the set of records for which the rule applies

Key

Every rule has a key, and the goal is to eventually have one key for each possible action. For instance, there is a key for "adding a tag to a document", a key for "removing a tag from a document", and a key to "see a document". Some actions do not (yet) have a specific key assigned to them. In that case the server will take the nearest key when checking if the action is allowed (see inheritance).

Condition

Conditions are limitations to the permissions granted.

An example: users should be allowed to see some documents in the document warehouse, but not all documents. To do this, we can set a query filter on the 'View documents' rule to makes this access conditional.

Grant: read / write / execute

Permissions can be one of the following "Grant" types:

• Read Read access means a user is allowed to see a certain resource, such as documents, tags, fields, etc. It is not possible to grant a "partial" read to a record, meaning that you can't allow a user to see the name and the tags of a document, but not the fields. It's all or nothing!

• Write Write access means that a user is allowed to create, modify and delete records. So if a user is granted write access on a document, he or she can upload a document, assign tags and fields to it and delete the document again.

• Execute With execute you allow users to "execute" an action, like allowing a user to assign a template to a document. This can be considered a "partial write" to a record.

Inheritance

Inheritance is a concept that applies to keys. And it creates a "parent-child" like relation to keys. Adding a rule on a higher level key makes it so that all child keys are automatically applied.

The user interface has a tree like structure that attempts to show the inheritance structure of the keys. However, keys do not have a single parent, and can actually be a child (/ subset) of multiple parent keys.

A few examples of how inheritance works:

Inheritance can be used to reduce the amount of work to configure a role, but are bound to some limitations:

• Conditions cannot be set on "higher level" keys, meaning they, by definition, allow everything. This is because higher level keys can impact different resources, which is why no generic condition that can be applied.

• It is not possible to exclude sub keys from a higher level key. If a higher level key would grant access to 50 sub keys, and you only want to allow 49 of them, you cannot use the higher level key.

• New features will include new keys. If access was granted on one of the higher level keys it is not possible to prevent users to use the new feature after it was released, as their assigned roles immediately inherit the related sub keys.

Configuring rule conditions

To view or modify a condition, find the rule in the table or tree view, and click on the pencil icon. Note that not all rules allow to set conditions.

When the pencil is clicked the condition is shown:

Reusing conditions

Conditions can be created to define a reusable filter that can be applied in roles and rules. The full list of these conditions can be found in the "Conditions" tab in the Configuration page. Each condition has a unique code, a resource type (i.e. "document"), a name, and the actual filter. The conditions can be nested, although loops are not allowed.

Once a named condition is created, you can add them in a security Rule. To do so, pick the condition from the drop down, and then select "contains" if you want to match all records that match the condition, or "does not contain" if you want to exclude those records instead.

The Default role

One (and only one) role can be marked as the “default role” this role is automatically assigned to users who are created in the systems. This allows administrators to provide a basic set of access right for new users.

The Administrator role

In the user interface, there is a checkbox on the roles editor that allows you to convert a role to an administrator role. When checked, the effect will be that 3 rules are added to the role:

• read on key * without condition

• write on key * without condition

• execute on key * without condition

An administrator role has unlimited access to the tenant's resources and should therefore be reserved for specific users.

Deselecting the Administrator rights checkbox will remove all permissions from that role, so use with care.

Creating a new Role

To create a new role click the “+” button at the top of the role table. Next give the role a Name in the details section, and click the save button. This should create an empty role, which now can be modified.

How to edit/modify a Role

1. Open the configuration

2. Select the “Roles” tab.

3. Select the created role.

4. Make your changes.

5. Save your changes (!)

The permissions granted by a role can be visualized in two ways:

Table view

The table view is the most basic visualization of the two, and only shows the actual rules / permissions of the role. You can see the actual key, and edit the condition if possible by clicking on the pencil icon.

Tree view

The tree view visualization can be used to more easily see all the possible options, and gives the possibility to just click on certain permissions in order to add them to the role. You can switch to show only "active" nodes, and all nodes with the toggle button at the top right of the tree view.

Note that this view is a combination of a "read" and "write" (/execute) tree mixed into a single view. We believe that this is the most informative way to display the options in a still rather condensed manner.

Note that not all the options are visualized in this tree. Some rules are "hidden" and will only be shown in the UI if they are active on the role, such as the UI Read-only rule and the Administrator rights.