--- last_review: "2026-05-07" last_reviewer: "i.nueske" documented_code: [ ] --- ```{tags} explanation, administrator ``` # Permissions LinkAhead has a fine-grained role-based permission system. Each interaction with the server is governed by the current role(s) of the user, or the `anonymous` role if not logged in. The permissions for an action which involves one or more Entities 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 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 a 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. ## 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](./roles) (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)= ### 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 Permission Table](/reference/server/role-permission-table.md) 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 {ref}`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)= ### 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](/reference/server/entity-permission-table.md) 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`. (calculation)= ## Permission calculation For each action a user tries to perform, the server applies available rules in the following order: 1. *Grant* rules without priority. 2. *Deny* rules without priority. 3. *Grant* rules with priority. 4. *Deny* rules with priority. If the user’s permission is *granted* after applying all rules, the action may take place. If the result is *denied* or the permission still undefined, the action can not take place. In other words, the default is *Deny*, which means if you have not explicitly been given the permission at some point, you are not allowed to perform the action. ### 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. :::{warning} `Grant(*)P` is a powerful administration permission rule. Be cautious when assigning administration privileges to users and roles. ::: % TODO: Add a short section with an overview of the different ways to set permissions, linking to % TODO: the respective how-tos, as soon as they are written for the new setup % TODO: ## How to set permissions % TODO: There are multiple ways to set permissions: % TODO: The general permission setup should be configured using the LinkAhead server configuration % TODO: file `global_entity_permissions.xml` (see [Server Docs](...)). Other permissions should be % TODO: set using the graphical user interface (see [UI Docs](...)) % TODO: - **Configuration file:** The general permission setup should be configured using the % TODO: LinkAhead server configuration file `global_entity_permissions.xml` (see % TODO: [Server Docs](...)). This file governs the default permissions of **every Entity**. You % TODO: can find the default settings [here](https://gitlab.com/caosdb/caosdb-server/-/blob/main/conf/core/global_entity_permissions.xml). % TODO: Note that, as the name suggests, only {ref}`entity permissions` can be % TODO: set in this file. % TODO: - **WebUI:** There is an access management component in the LinkAhead WebUI. % TODO: - **The Python library:** The permissions can also be set via the % TODO: Python library. % TODO: - The [set_permissions.py example file](...). % TODO: - The [`linkahead_admin.py` utility script](...).