[#69784] server: document permission system

Author: MaciejWas

documentation/source/api.rst

@@ -96,3 +96,11 @@ Device Authorization API
    :modules: api.v1.auth
    :undoc-static:
    :order: path
+
+Permissions API
+~~~~~~~~~~~~~~~
+
+.. autoflask:: rdfm_mgmt_server:create_docs_app()
+   :modules: api.v1.permissions
+   :undoc-static:
+   :order: path

documentation/source/rdfm_mgmt_server.md

@@ -154,9 +154,16 @@ The authorization server is configured using the following environment variables
 
 For accessing the management API, the RDFM server does not issue any tokens itself.
 This task is delegated to the authorization server that is used in conjunction with RDFM.
+
+### Users' and applications' permissions
+
+The authorization server needs to implement certain applications' scopes and users' permissions for users and applications to access RDFM API.
+
+#### Scopes
+
 The following scopes are used for controlling access to different methods of the RDFM API:
-- `rdfm_admin_ro` - read-only access to the API (fetching devices, groups, packages)
-- `rdfm_admin_rw` - complete administrative access to the API with modification rights
+- `rdfm_admin_ro` - read-only access to the API (fetching devices, groups, packages).
+- `rdfm_admin_rw` - complete administrative access to the API with modification rights.
 
 Additional rules are defined for package uploading route from [Packages API](api.rst#Packages_API).
 - `rdfm_upload_single_file` - allows uploading an artifact of type `single-file`.
@@ -165,6 +172,34 @@ Each package type requires its corresponding scope, or the complete admin access
 
 Refer to the [RDFM Server API Reference chapter](api.rst) for a breakdown of the scopes required for accessing each API method.
 
+#### Permissions
+
+In addition to the above, you can assign specific permissions to users for specific resources (devices, groups, packages).
+There are three types of permissions:
+
+* **`read`** permission – Allows listing devices, groups, and packages, as well as downloading packages.
+* **`update`** permission – Allows changing, adding, and updating groups and packages.
+* **`delete`** permission – Allows deleting groups and packages.
+
+Those permissions are not mutually exclusive and have no hierarchy (none of the above permissions imply or contain the other).
+
+Permissions to a group also apply to the devices and packages within that group.
+For example, if you assign a user an `update` permission to a group, they will also be able to update any resources within that group.
+These propagated permissions are implicit and are not stored in the RDFM Management Server.
+
+You can inspect the current permissions of each user using the [Permissions API](api.rst#Permissions_API).
+
+##### Assigning a Permission
+
+To assign a permission to a user, you must have the `rdfm_admin_rw` scope and you will need the following information:
+* The **ID of the user** you want to assign the permission to, which you can obtain from your OAuth2 provider’s administration panel.
+* The **ID of the resource**, which can be retrieved via:
+  * The [RDFM Manager](rdfm_manager.md) – Use the `rdfm-mgmt {devices,packages,groups} list` command to get a list of resources and their IDs.
+  * The [RDFM Server API](api.rst) – The `/api/{v2,v1}/{devices,packages,groups}` endpoints will return a list of resources and their IDs.
+
+Permissions can be assigned via a POST request to `/api/v1/permissions`.
+For an example of such request, see this [endpoint's documentation](api.rst#post--api-v1-permissions).
+
 ### API authentication using Keycloak
 
 #### Running the services

server/src/api/v1/permissions.py

@@ -37,8 +37,47 @@ def model_to_schema(
 @management_read_only_api
 @wrap_api_exception("permissions fetching failed")
 def fetch_all():
-    """Fetch all permissions
-    """
+    """Fetch all permissions 
+
+    :status 200: no error
+    :status 401: user did not provide authorization data,
+                 or the authorization has expired
+    :status 403: user was authorized, but did not have permission
+                 to read permissions
+
+    :>jsonarr string created: UTC creation date (RFC822)
+    :>jsonarr integer id: permission identifier
+    :>jsonarr str permission: permission type (read/update/delete)
+    :>jsonarr str resource: type of resource (group/device/package)
+    :>jsonarr str user_id: id of the user to whom this permission applies
+    :>jsonarr integer resource_id: id of the resource to which this permission applies
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        GET /api/v1/permissions HTTP/1.1
+        Accept: application/json
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        [
+            { 
+                "created": "Thu, 16 Jan 2025 13:31:53 -0000",
+                "id": 1,
+                "permission": "read",
+                "resource": "group",
+                "resource_id": 2,
+                "user_id": "095e4160-9017-4868-82a5-fe0a0c44d34c"
+            }
+        ]
+    """  # noqa: E501
+
     permissions: List[
         models.permission.
         Permission] = server.instance._permissions_db.fetch_all(
@@ -54,7 +93,46 @@ def fetch_all():
 @deserialize_schema(schema_dataclass=Permission, key="perm")
 def create(perm: Permission):
     """Create a new permission
-    """
+
+    :status 200: no error
+    :status 401: user did not provide authorization data,
+                 or the authorization has expired
+    :status 403: user was authorized, but did not have permission
+                 to create permissions
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        POST /api/v1/permissions HTTP/1.1
+        Content-Type: application/json
+        Accept: application/json
+
+        {
+            "resource": "group",
+            "resource_id": 5,
+            "user_id": "095e4160-9017-4868-82a5-fe0a0c44d34c",
+            "permission": "read"
+        }
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+            "created": "Thu, 23 Jan 2025 13:03:44 -0000",
+            "id": 26,
+            "permission": "read",
+            "resource": "group",
+            "resource_id": 5,
+            "user_id": "095e4160-9017-4868-82a5-fe0a0c44d34c"
+        }
+
+    """  # noqa: E501
+
     permission = models.permission.Permission()
     permission.created = datetime.datetime.utcnow()
     permission.resource = perm.resource
@@ -76,7 +154,37 @@ def create(perm: Permission):
 @wrap_api_exception("permission fetching failed")
 def fetch_one(identifier: int):
     """Fetch permission
-    """
+
+    :status 200: no error
+    :status 401: user did not provide authorization data,
+                 or the authorization has expired
+    :status 403: user was authorized, but did not have permission
+                 to read permissions
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        GET /api/v1/permissions/26 HTTP/1.1
+        Accept: application/json
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+        
+        {
+            "created": "Thu, 23 Jan 2025 13:03:44 -0000",
+            "id": 26,
+            "permission": "read",
+            "resource": "group", 
+            "resource_id": 5,
+            "user_id": "095e4160-9017-4868-82a5-fe0a0c44d34c"
+        }
+    """  # noqa: E501
+
     permission: Optional[
         models.permission.Permission
     ] = server.instance._permissions_db.fetch_one(identifier)
@@ -92,7 +200,29 @@ def fetch_one(identifier: int):
 @wrap_api_exception("permission deletion failed")
 def delete_one(identifier: int):
     """Delete permission
+
+    :status 200: no error
+    :status 401: user did not provide authorization data,
+                 or the authorization has expired
+    :status 403: user was authorized, but did not have permission
+                 to delete permissions
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        DELETE /api/v1/permissions/26 HTTP/1.1
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {}
     """
+
     permission: Optional[
         models.permission.Permission
     ] = server.instance._permissions_db.fetch_one(identifier)