Understanding Permissions

A large amount of the functionality of the EHRI backend concerns setting, enforcing, and validating permissions for what a given user or group of users are allowed to do to certain items in the database. Due to certain inescapable requirements, these functionalities ended up being quite complex. This document is intended to explain how and why the permission system works the way it does. First, some terminology:

content type

A type of first-class "thing" within the DB, e.g. a documentary unit, a repository, a vocabulary, etc. For all intents and purposes, a content type is any type of item that can have permissions attached to it. Each content type has a concrete manifestation in the form of a node within the DB.

permission type

Some way in which a user can interact with an item to somehow affect its representation, e.g. "create", "update", "delete", "annotate". The "owner" permission type is a special case that encompasses "create", "update", "delete", and "annotate".

target

Something which can have permissions attached to it, e.g. a content type item, or the content type node, representing all items of that type.

scope

A content type item which defines the limits to which some permision(s) may be applied (see below).

grant

An assertion that a user can perform an action on a target, with an optional scope.

Use Cases

Examples of high-level use cases are:

  • Users of the portal can create annotations for items in the database and links between pairs of items, and only the creator of the annotations and links are allowed to edit them. Making annotations and links public is not by default available to normal users.

  • Employees of a particular archive are the only people allowed to make annotations and links involving the descriptions of their fonds public. This ensures only people with direct access to the original description can allow these annotations.

  • A specific controlled vocabulary is set to only be edited by a group of domain specialists, and only during their involvement in the project.

Different Grant Types

There are five grant types, i.e. types of actions that a user can perform within the permission scope when the user was granted a particular permission granted.

create

the privilege of creating new items of a type within a permission scope

update

the privilege of altering existing items of a type within a permission scope

delete

the privilege of removing existing items of a type within a permission scope

annotate

the privilege of using an existing item as a target in an annotation

owner

a meta-grant that includes create, update, delete and annotate

grant

the privilege to manage permissions of users and groups within a certain permission scope

promote

the privilege of promoting and demoting annotations and links within a certain permission scope

Permission Scopes

There are type-specific behaviours that concern the permission scope, corresponding to how we apply permissions to a given hierarchy. For documentary units the permission scope is the repository at the top level, and the parent doc unit for child items. It does two things:

  • It allows you to say that person X can have permission Y on everything which has (directly or by inheritance) a particular "thing" as its scope.

  • It determines how IDs are generated for hierarchical entities

When a user wants to do something to a particular item, the permission system traverses "up" the hasPermissionScope hierarchy looking for a permission grant which allows them to do that thing.

For doc units, which form a directed graph, the permission scope is always the parent item or (if top level) the repository. For concepts in a vocabulary, the permission scope is always the vocabulary, because they can have multiple "parent" (broader term) items, or none at all.

The permission scope is a generic structure for everything where we want to apply hierarchical permissions. So basically:

  • permission scope = de-facto generic representation of a hierarchy

  • childOf, inAuthoritativeSet, hasBroaderTerm etc = type-specific hierarchy representations