From be81d2486f60e30a94fb337d7eb48702d6c68287 Mon Sep 17 00:00:00 2001
From: Sebastian Blechmann <51322874+SBlechmann@users.noreply.github.com>
Date: Thu, 5 Sep 2024 16:50:11 +0200
Subject: [PATCH] docs: first draft of user and permission model (#196)

* docs: first draft of user and permission model

* docs: fixed typos

* docs: adapted readme according to review
---
 README.md         |  4 +++
 docs/USERMODEL.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 docs/USERMODEL.md

diff --git a/README.md b/README.md
index df072d77..bd40cc52 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,10 @@ provide following settings in your env file.
 
 For a full list of settings see [settings](./docs/SETTINGS.md).
 
+## User and permissions model 
+
+The user and permissions model of _Entirety_ is described in the [user model documentation](./docs/USERMODEL.md).
+
 ## Changelog
 
 See [changelog](./docs/CHANGELOG.md) for detailed overview of changes.
diff --git a/docs/USERMODEL.md b/docs/USERMODEL.md
new file mode 100644
index 00000000..4bfe51a2
--- /dev/null
+++ b/docs/USERMODEL.md
@@ -0,0 +1,74 @@
+# Description of the user model of Entirety
+
+Entirety comes with two different ways to assign permissions to users: Roles and Groups.
+Roles come with a set of permissions that are application-wide while groups grant project-wide permissions.
+Both, roles and groups, follow a hierarchical approach, meaning that a user with a higher role or group can do everything a user with a lower role or group can do.
+In the following, first, the different roles and groups are described, starting with the highest set of permissions.
+Second, the different ways of how to create users and assign roles for both, local authentication and OIDC authentication mode, are described.
+
+# Roles and Groups
+## Roles
+**Reminder:** Roles are application-wide permissions and can be set either in the admin panel of Entirety or the OIDC provider.
+
+### Server Admin
+* Create / edit / delete all projects
+  * Note: Only server admins can edit the _fiware-service_. In a case where Entirety is connected with a FIWARE cluster directly (not through a PEP proxy), this means Server Admins  can see all data within the platform!  
+* Assign / change _project owner_ to projects
+  * Note: By default, the project creator is first assigned as _project owner_.
+
+### Super Admin / Super User
++ Currently without function
+
+### Project Admin
+
+* Eligible to be assigned as _project owner_ to projects
+
+### User
+
+* Access to Entirety
+  * Note: Only relevant for OIDC authentication. In local authentication mode, users are always assigned _user_ role implicitly. 
+* Eligible to be assigned as _project maintainer_, _project user_ or _project viewer_ for projects
+
+## Groups
+**Reminder:** Groups are project-bound permissions and can be set in the project edit page of each project.
+
+### Project Owner
+
+* (Un-)Assign _project maintainer_ to project
+  * Note: Users with _server admin_ role or the current _project owner_ are not eligible.
+* Edit project details, e.g. name, description, etc., except for _fiware-service_.
+
+### Project Maintainer
+
+* (Un-)Assign _project user_ and _project viewer_ to project
+  * Note: Users with _server admin_ role or the current _project owner_ are not eligible.
+
+### Project User
+
+* Access to project data via loaded modules, e.g. entities, devices, semantics, etc.
+* Add / edit / delete entities, devices, notifications, etc.
+
+### Project Viewer
+
+* Read-only access to project data via loaded modules, e.g. entities, devices, semantics, etc.
+
+
+# How to create users and assign roles and groups
+
+There are two ways to create users and assign roles depending on the authentication mode: Local authentication and OIDC authentication.
+The authentication mode can be set in the [Entirety settings file](https://github.com/N5GEH/n5geh.tools.entirety/blob/development/docs/SETTINGS.md#local_auth).
+
+## Local Authentication
+
+In local authentication mode, users are created and managed in the admin panel of Entirety.
+The admin panel is available at `http://<entirety-ip>:<entirety-port>/admin/` and can be accessed by admin users only. By default, the admin user is created during the [first start of Entirety](https://github.com/N5GEH/n5geh.tutorials.entirety_step_by_step?tab=readme-ov-file#add-admin-user-local-auth-only). 
+Further admin users can be assigned the _staff status_ in the user edit page.
+Roles can be assigned to users in the user's edit page.
+
+## OIDC Authentication
+
+In OIDC authentication mode, users are created and managed in the OIDC provider. Only users with the _user_ role assigned are able to login to Entirety.
+Check your OIDC provider documentation for further details. 
+In case you are using keycloak as OIDC provider, we provide a short tutorial with the necessary steps in the [Entirety step-by-step guide](https://github.com/N5GEH/n5geh.tutorials.entirety_step_by_step?tab=readme-ov-file#configure-oidc-provider-oidc-auth-only).
+
+