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 the anonymous role. The permissions for an action which involves one or more objects are set either manually or via default permissions which can be configured.

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 Grant or Deny type, 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 true or false. Permissions with priority = true override 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.

Role 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 my_scripts directory.

Entity permissions

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

  • RETRIEVE:*:1234: For all “retrieve” actions concerning the entity 1234.

Permission calculation

For each action a user tries to perform, the server tests, in the following order, which rules apply:

  1. Grant rules, without priority.

  2. Deny rules, without priority.

  3. Grant rules, with priority.

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

Administration permissions

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 in the global_entity_permissions.xml config file, and role-based role permissions with the 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.xml file, 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 in the global_entity_permissions.xml, but you can not remove rules by writing to this file. 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.