Merge branch 'dev' into f-timezone

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)

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

src/doc/entity-permission-table.rst

+.. _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

src/doc/permissions.rst

 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>`__.

src/doc/role-permission-table.rst

+.. _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).

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 =