CaosDB has a fine grained role-based permission system. Each interaction with
the server is governed by the current role(s) of the user, by default this is
anonymous role. The permissions for an action which involves one or more
objects are set either manually or via default permissions which can be
Permissions are needed to perform particular elementary actions during any
interaction with the the server. E.g. retrieving an Entity requires the
requesting user to have the
RETRIEVE:ENTITY permission for that entity, and
DELETE:ENTITY to delete the entity.
The permissions of every user are calculated from a set of Permission Rules. These rules have several sources. Some are global defaults, some are defined by administrators or the owners of an entity.
As a side note on the implementation: The server uses Apache Shiro for its permission system.
What is a Permission Rule?
A Permission Rule consists of:
- A type: Permission Rules can be of
Denytype, either granting or denying specific permissions.
- A role (or user): For which users the permission shall be granted or denied.
- A permission action: Which action shall be permitted or forbidden, for example all retrieval, or modifications of a specific entity.
- An optional priority: May be
false. Permissions with priority =
trueoverride those without, see the calculation rules below.
There are two complementing types of permission rules that will be explained below: role permissions and entity permissions.
As the name suggests, role permissions are assigned to a specific role and define whether, in general, a particular role is allowed, e.g., to perform specific transactions, update roles or users, or execute server-side scripts. See the role-permissions table for a full list of role permissions. The most common are
TRANSACTiON:*: Allows to perform any write transaction (in general). Note that this is the necessary but not sufficient condition for deleting/inserting/updating an entity and the corresponding entity permissions are required, too.
SCRIPTING:EXECUTE:?PATH?: Permission to execute a server-side script under the given path. Note that, for utilizing the wild cards feature, you have to use
':'as path separator. E.g.
'SCRIPTING:EXECUTE:my_scripts:*'would be the permission to execute all executables below the
As the name suggests, entity permissions define what a certain user or role is allowed to do with a specific entity. Thus, entity permissions can be used to, e.g., deny everone but administration users to update or delete a specific record types, or to allow everyone to retrieve a specific record. See the entity-permissions table for a full list of possible entity permissions. Typical permissions are:
RETRIEVE:ENTITY: To retrieve the full entity (name, description, data type, …) with all parents and properties (unless prohibited by another rule on the property level).
RETRIEVE:ACL: To retrieve the full and final ACL of this entity.
RETRIEVE:ENTITY:1234: To retrieve the entity
RETRIEVE:*:1234: For all “retrieve” actions concerning the entity
For each action a user tries to perform, the server tests, in the following order, which rules apply:
- Grant rules, without priority.
- Deny rules, without priority.
- Grant rules, with priority.
- Deny rules, with priority.
If at the end the user’s permission is granted, the action may take place. Otherwise (the result is denied or the permission still undefined), the action can not take place. In other words, if you have not been given the permission explicitly at some point, you don’t have it.
There is one special permission rule that grants global administration
permissions to a user or a role:
Grant(*)P, i.e., grant everything with
priority. This promotes a user with this role to administration level, very
similar to the
root user on POSIX systems. As with any other rule, the
effect of this rule can be overriden by Deny rules with priority. The
Grant(*)P permission should really only be used for administration users
and in no other case.
Grant(*)P is a powerful administration permission rule. Be cautious
when assigning administration privileges to users and roles.
How to set permissions
There are multiple ways to set role and entity permissions. The most
common and best tested way currently is to set global default entity permissions
global_entity_permissions.xml config file, and role-based role
permissions with the
caosdb_admin.py utility script
of CaosDB’s Python library which is also used to manage users and
roles. Below you
find a more detailed description of the possible ways of setting permissions.
- Config file: Some default permissions are typically set in the
global_entity_permissions.xmlfile, see also the default file. Here, you can set the default permissions that every entity on the server has. The global default permissions can only be set in this file; all other ways below can only change the permissions of individual entities. Note that you can add more rules but you can never remove rules set in the
global_entity_permissions.xml. Thus, it might not be possible to overrule permissions defined here (see Permission calculation). Note also that, as the name suggests, only entity permissions can be set this way. The role-based role-permissions have to be set with one of the other ways explained below.
- API: Both REST and GRPC API allow to set the permissions. This hasn’t been documented properly yet, but for the GRPC API, the specification may give some insight.
- The Python library: The permissions can also conveniently be set via the Python library. Currently the best documentation is inside various files which use the permission API:
- WebUI: This is currently work in progress. A WebUI ACM module which uses the GRPC interface is under active development.