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.

Work in progress

Not all actions in a Raptor tenant are protected by permissions yet, making them available to every user. Examples are viewing tags, templates and fields.

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

*Exception: the UI Read-only rule

Normally adding extra roles only can add extra permissions, with one exception: A role that has the UI Read-only rule will prevent the users from modifying documents in the UI.

As the name suggests, this rule only prevents document modification in the Raptor user interface. The users will still be able to make modifications by using the Raptor API.

The rule is only available through a feature flag and is kept for backwards compatibility. For Raptor tenants containing this feature flag, we discourage further use of the rule and refer to the newly available security rules to provide both front- and backend security.

Configuring security in a system requires time and effort. Every customer is different and has to consider what is important and where the balance is between security, usability and maintainability.

Configuring security rules requires technical knowledge about it's internal workings. Do not hesitate to ask a Document Warehouse consultant for guidance on this topic.

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.

Rules are presented in a hierachical manner

A few examples of how inheritance works:

Example "view document"

To view a document, the application will check if the user has read access to the key: meta.document.rec.

This key is a subset of meta.document.* Which in turn is a subset of meta.* Which in turn is a subset of * This means that granting read access to meta.* will allow users to view the documents.

Example "admin role"

See The Administrator role

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.

active permisions in role, condition applies to visible documents

When the pencil is clicked the condition is shown:

Visualized condition after clicking the pencil button

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.

You can not delete a condition if it is used by another condition, or used in a role.

example of reusable conditions

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.

Reusing the 'Recent & complete' condition as a filter

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 role marked as the default role 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.

When you create a new role, it should automatically be selected, and show up at the top of the table. Once you refresh the list of roles it will be displayed in alphabetical order.

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.