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 (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 Permission 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 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.