diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9cd7cf85fd22ebe459b0d8d614def7bb1449e20e..e9c787f48e794cf1220403f93280b30d530c5767 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Security
+### Documentation
+
+* Extended documentation on role and entity permissions
## [0.8.0] - 2022-07-12
(Timm Fitschen)
diff --git a/README_SETUP.md b/README_SETUP.md
index 6bbbd71167a9243966f88b29c82184600bcaa25a..ad4dc1bfd087d235aa903dee9183b78bc6ff3094 100644
--- a/README_SETUP.md
+++ b/README_SETUP.md
@@ -4,6 +4,9 @@ Here, you find information on requirements, the installation, configuration and
more. Note, that building the CaosDB Server from the sources and maintaining
the server requires the knowledge/skill of an experienced Linux administrator.
+**Note:** If you are looking for a quick and easy way to get startet, check
+out [the docker deployment](https://gitlab.indiscale.com/caosdb/src/caosdb-docker).
+
## Requirements
See [DEPENDENCIES.md](DEPENDENCIES.md).
diff --git a/src/doc/entity-permission-table.rst b/src/doc/entity-permission-table.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1ff75f2138d7ae5382a00ee6fc9a60317fbbed28
--- /dev/null
+++ b/src/doc/entity-permission-table.rst
@@ -0,0 +1,62 @@
+.. _Entity Permissions Table:
+
+Entity Permissions
+==================
+
+Permission to the following actions can be granted or denied in CaosDB:
+
+.. list-table:: Entity permission actions
+ :header-rows: 1
+ :widths: 33 67
+
+ * - Action
+ - Description
+ * - ``RETRIEVE:ENTITY``
+ - Permission 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``
+ - Permission to retrieve the full and final ACL of this entity.
+ * - ``RETRIEVE:HISTORY``
+ - Permission to retrieve the history of this entity.
+ * - ``RETRIEVE:OWNER``
+ - Permission to retrieve the owner(s) of this entity.
+ * - ``RETRIEVE:FILE``
+ - Permission to download the file belonging to this entity.
+ * - ``DELETE``
+ - Permission to delete this entity.
+ * - ``EDIT:ACL``
+ - Permission to change the user-specified part of this entity's ACL. Roles
+ with this Permission are called ``Owners``.
+ * - ``UPDATE:DESCRIPTION``
+ - Permission to change the value of this entity.
+ * - ``UPDATE:VALUE``
+ - Permission to change the value of this entity.
+ * - ``UPDATE:ROLE``
+ - Permission to change the role of this entity.
+ * - ``UPDATE:PARENT:REMOVE``
+ - Permission to remove parents from this entity.
+ * - ``UPDATE:PROPERTY:REMOVE``
+ - Permission to remove properties from this entity.
+ * - ``UPDATE:PROPERTY:ADD``
+ - Permission to add a property to this entity.
+ * - ``UPDATE:NAME``
+ - Permission to change the name of this entity.
+ * - ``UPDATE:DATA_TYPE``
+ - Permission to change the data type of this entity.
+ * - ``UPDATE:FILE:REMOVE``
+ - Permission to delete the file of this entity.
+ * - ``UPDATE:FILE:ADD``
+ - Permission to set a file for this entity.
+ * - ``UPDATE:FILE:MOVE``
+ - Permission to move an existing file to a new location.
+ * - ``USE:AS_REFERENCE``
+ - Permission to refer to this entity via a reference property.
+ * - ``USE:AS_PROPERTY``
+ - Permission to implement this entity as a property.
+ * - ``USE:AS_PARENT``
+ - Permission to use this entity as a super type for other entities.
+ * - ``USE:AS_DATA_TYPE``
+ - Permission to use this entity as a data type for reference properties.
+ * - ``UPDATE:QUERY_TEMPLATE_DEFINITION``
+ - Permission to update the query template definition of this QueryTemplate
diff --git a/src/doc/permissions.rst b/src/doc/permissions.rst
index c0f30a0ee05d6cc8cac237b305e63b2c83ec7dce..6b07f48fa469e81069b2f01559957fb76ef27f5a 100644
--- a/src/doc/permissions.rst
+++ b/src/doc/permissions.rst
@@ -1,24 +1,25 @@
Permissions
===========
-CaosDB has a fine grained role based permission system. Each interaction
-with the server is governed by the current rules 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.
+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.
+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.
+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 <https://shiro.apache.org/documentation.html>`__ for its
-permission system.
+.. note::
+
+ As a side note on the implementation: The server uses `Apache Shiro
+ <https://shiro.apache.org/documentation.html>`__ for its permission system.
What is a Permission Rule?
--------------------------
@@ -35,6 +36,56 @@ A Permission Rule consists of:
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 :ref:`role-permissions table<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 :ref:`entity
+ permissions<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
+:ref:`entity-permissions table<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``.
+
+
+
+
+.. _Calculation:
+
Permission calculation
----------------------
@@ -52,44 +103,66 @@ 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.
-Possible actions
-----------------
+Administration permissions
+**************************
-Until it is completely added to this documentation, a detailed
-description of the actions governed by these permissions can be found
-`in the
-sources <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/src/main/java/org/caosdb/server/permissions/EntityPermission.java#L119>`__.
+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.
-Typical permissions are:
+.. warning::
+
+ ``Grant(*)P`` is a powerful administration permission rule. Be cautious
+ when assigning administration privileges to users and roles.
-- ``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``.
How to set permissions
----------------------
-- Config file :: Some default permissions are typically set in the
- ``global_entity_permissions.xml`` file, see also the `documentation
- for that
- file </manuals/server/conf/global_entity_permissions.xml>`__.
-- API :: The REST API allows to set the permissions. (*to be documented
- here*)
-- 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:
-
- - The `example
- file <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/set_permissions.py>`__
- - The ```caosdb_admin.py`` utility
- script <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/src/caosdb/utils/caosdb_admin.py>`__
- - The `integration
- tests <https://gitlab.com/caosdb/caosdb-pyinttest/-/blob/main/tests/test_permissions.py>`__
- also cover quite a bit of the permission API.
-
-- WebUI :: Not implemented (or documented?) yet.
+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 ``caosdb_admin.py`` `utility script
+<https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/src/caosdb/utils/caosdb_admin.py>`__
+of CaosDB's Python library which is also used to `manage users and
+roles <https://docs.indiscale.com/caosdb-pylib/administration.html>`__. 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
+ <https://gitlab.com/caosdb/caosdb-server/-/blob/main/conf/core/global_entity_permissions.xml>`__. 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 :ref:`Permission
+ calculation<Calculation>`). Note also that, as the name suggests, only
+ :ref:`entity permissions<entity-permissions>` can be set this way. The
+ role-based :ref:`role-permissions<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
+ <https://gitlab.com/caosdb/caosdb-proto/-/blob/main/proto/caosdb/acm/v1alpha1/main.proto>`__
+ 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:
+
+ - The `example file
+ <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/set_permissions.py>`__
+ - The ``caosdb_admin.py`` `utility script
+ <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/src/caosdb/utils/caosdb_admin.py>`__
+ - There is a comprehensive `example <https://docs.indiscale.com/caosdb-pylib/gallery/curator-permissions.html>`_
+ in PyCaosDB's gode gallery.
+ - The `integration tests
+ <https://gitlab.com/caosdb/caosdb-pyinttest/-/blob/main/tests/test_permissions.py>`__
+ also cover quite a bit of the permission API.
+
+- **WebUI:** This is currently work in progress. A WebUI ACM module which uses the
+ GRPC interface is under `active development
+ <https://gitlab.indiscale.com/caosdb/src/caosdb-webui2>`__.
diff --git a/src/doc/role-permission-table.rst b/src/doc/role-permission-table.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2860407fad11d53e7ddefc8adff06c8ae0fde420
--- /dev/null
+++ b/src/doc/role-permission-table.rst
@@ -0,0 +1,89 @@
+.. _Role Permission Table:
+
+Role Permissions
+================
+
+Roles in CaosDB can have the following permissions
+
+.. list-table:: Role permissions
+ :header-rows: 1
+ :widths: 33 67
+
+ * - Permission
+ - Description
+ * - ``ACCESS_SERVER_PROPERTIES``
+ - Permission to read the server properties.
+ * - ``ACM:*``
+ - Permissions to administrate the access controll management system. That
+ includes managing users, roles, and assigning permissions to roles and
+ roles to users.
+ * - ``ACM:ROLE:*``
+ - Permissions to manage roles, i.e. create, retrieve, update and delete
+ roles and assign them to users.
+ * - ``ACM:ROLE:ASSIGN:?ROLE?``
+ - Permission to assign a role (to a user).
+ * - ``ACM:ROLE:DELETE:?ROLE?``
+ - Permission to delete a role.
+ * - ``ACM:ROLE:INSERT``
+ - Permission to create a new role.
+ * - ``ACM:ROLE:RETRIEVE:DESCRIPTION:?ROLE?``
+ - Permission to retrieve the description of a role.
+ * - ``ACM:ROLE:RETRIEVE:PERMISSIONS:?ROLE?``
+ - Permission to read the permissions of a role.
+ * - ``ACM:ROLE:UPDATE:DESCRIPTION:?ROLE?``
+ - Permission to update the description of a role.
+ * - ``ACM:ROLE:UPDATE:PERMISSIONS:?ROLE?``
+ - Permission to set the permissions of a role.
+ * - ``ACM:USER:*``
+ - Permissions to manage users, i.e. create, retrieve, update and delete
+ users.
+ * - ``ACM:USER:DELETE:?REALM?:?USER?``
+ - Permission to delete a user
+ * - ``ACM:USER:INSERT:?REALM?``
+ - Permission to create a user in the given realm
+ * - ``ACM:USER:RETRIEVE:INFO:?REALM?:?USER?``
+ - Permission to retrieve the user info (email, entity, status)
+ * - ``ACM:USER:RETRIEVE:ROLES:?REALM?:?USER?``
+ - Permission to retrieve the roles of a user
+ * - ``ACM:USER:UPDATE:EMAIL:?REALM?:?USER?``
+ - Permission to update the email address of a user.
+ * - ``ACM:USER:UPDATE:ENTITY:?REALM?:?USER?``
+ - Permission to set the entity which is associated with a user.
+ * - ``ACM:USER:UPDATE:ROLES:?REALM?:?USER?``
+ - Permission to change the roles of a user.
+ * - ``ACM:USER:UPDATE:STATUS:?REALM?:?USER?``
+ - Permission to update the status of a user, i.e. marking them as
+ ``ACTIVE`` or ``INACTIVE``.
+ * - ``ACM:USER:UPDATE_PASSWORD:?REALM?:?USER?``
+ - Permission to set the password of a user.
+ * - ``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.
+ * - ``SERVERLOGS:RETRIEVE``
+ - Permission to read the server logs. (DEPRECATED)
+ * - ``STATE:*``
+ - Permissions to manage state models and the states of entities.
+ * - ``STATE:ASSIGN:?STATE_MODEL?``
+ - Permission to assign a state model.
+ * - ``STATE:FORCE:FINAL``
+ - Permission to force to leave a state models specified life-cycle even
+ though the currrent state isn't a final state in the that model.
+ * - ``STATE:TRANSITION:?TRANSITION?``
+ - Permission to initiate a transition.
+ * - ``STATE:UNASSIGN:?STATE_MODEL?``
+ - Permission to unassign a state model.
+ * - ``TRANSACTION:*``
+ - Permission to execute any writable transaction. This permission only
+ allows to execute these transactions in general. The necessary entities
+ permissions are not implied.
+ * - ``TRANSACTION:DELETE:?ENTITY_ROLE?``
+ - Permission to delete entities of a given role (e.g. Record, File,
+ RecordType, or Property).
+ * - ``TRANSACTION:INSERT:?ENTITY_ROLE?``
+ - Permission to insert entities of a given role (e.g. Record, File,
+ RecordType, or Property).
+ * - ``TRANSACTION:UPDATE:?ENTITY_ROLE?``
+ - Permission to update entities of a given role (e.g. Record, File,
+ RecordType, or Property).
diff --git a/src/main/java/org/caosdb/server/permissions/EntityPermission.java b/src/main/java/org/caosdb/server/permissions/EntityPermission.java
index f8f21a354ef68403f852a1f426e28afed857278d..1cfe9901ad2fdf0067d7cd58712c2caa506ac73b 100644
--- a/src/main/java/org/caosdb/server/permissions/EntityPermission.java
+++ b/src/main/java/org/caosdb/server/permissions/EntityPermission.java
@@ -140,6 +140,8 @@ public class EntityPermission extends Permission {
return mapping;
}
+ // Note: Please remember to transfer all changes to the following entity
+ // permissions to src/doc/entity-permission-table.rst.
public static final EntityPermission RETRIEVE_ENTITY =
new EntityPermission(
"RETRIEVE:ENTITY",
@@ -173,7 +175,7 @@ public class EntityPermission extends Permission {
public static final EntityPermission DELETE =
new EntityPermission(
"DELETE",
- "Permission to delete an entity.",
+ "Permission to delete this entity.",
1,
org.caosdb.api.entity.v1.EntityPermission.ENTITY_PERMISSION_DELETE);
public static final EntityPermission EDIT_ACL =