Restructure Keycloak roles and groups with realm prefixes

- Implemented a consistent naming convention for roles:
  <realm>_<scope>_<service> (e.g., management_service_admin_nextcloud).
- Added roles for each service in management and company realms.
- Created logical groups for user organization (e.g., nextcloud_admins, employees).
- Mapped roles to groups to simplify user permission assignments.
- Improved clarity and scalability for multi-realm setups.

docs/keycloak_naming_convention.md

@@ -0,0 +1,132 @@
+
+# Revised Plan: Role Naming with Realm/Domain Prefix
+
+## 1. Naming Conventions
+
+### Realm Roles
+Realm roles define **permissions** for users. The naming convention will follow:
+```
+<realm>_<scope>_<service>
+```
+
+| **Component**   | **Example**          | **Description**                              |
+|------------------|----------------------|----------------------------------------------|
+| **Realm/Domain** | `management`         | The realm where the role is defined.         |
+| **Scope**        | `service_admin`      | Specifies the level or type of access.       |
+| **Service**      | `nextcloud`          | The specific service or application.         |
+
+**Examples**:
+- `management_service_admin_nextcloud`
+- `analytikdata_service_admin_paperless`
+- `riechsteiner_user_kimai`
+
+### Groups
+Groups are collections of users and do not define permissions themselves. They are used to organize users logically. Examples:
+- `nextcloud_admins`
+- `finance_team`
+- `analytikdata_employees`
+
+---
+
+## 2. Role and Group Usage
+
+### Roles
+- Define specific permissions for services.
+- Assigned to individual users or groups.
+
+### Groups
+- Act as containers for users.
+- Inherit realm roles to apply permissions to all members.
+
+---
+
+## 3. Role and Group Setup Example
+
+### Management Realm
+- **Roles**:
+  - `management_service_admin_nextcloud`
+  - `management_service_admin_paperless`
+  - `management_user_kimai`
+- **Groups**:
+  - `nextcloud_admins` → Assigned `management_service_admin_nextcloud`
+  - `paperless_admins` → Assigned `management_service_admin_paperless`
+
+### AnalytikData Realm
+- **Roles**:
+  - `analytikdata_service_admin_nextcloud`
+  - `analytikdata_user_nextcloud`
+- **Groups**:
+  - `admins` → Assigned `analytikdata_service_admin_nextcloud`
+  - `employees` → Assigned `analytikdata_user_nextcloud`
+
+---
+
+## 4. Updated Naming in Practice
+
+### Updated Keycloak Roles
+| **Realm**       | **Role Name**                          | **Purpose**                                   |
+|------------------|----------------------------------------|-----------------------------------------------|
+| `management`     | `management_service_admin_nextcloud`   | Admin rights for Nextcloud in management realm. |
+| `management`     | `management_service_admin_paperless`   | Admin rights for Paperless in management realm. |
+| `analytikdata`   | `analytikdata_service_admin_nextcloud` | Admin rights for Nextcloud for AnalytikData GmbH. |
+| `analytikdata`   | `analytikdata_user_nextcloud`          | General user access to Nextcloud.             |
+| `riechsteiner`   | `riechsteiner_service_admin_kimai`     | Admin rights for Kimai for Riechsteiner.      |
+
+### Updated Groups
+| **Realm**       | **Group Name**         | **Purpose**                     |
+|------------------|------------------------|----------------------------------|
+| `management`     | `nextcloud_admins`     | Admin group for Nextcloud.       |
+| `management`     | `paperless_admins`     | Admin group for Paperless.       |
+| `analytikdata`   | `employees`            | General employees.               |
+| `riechsteiner`   | `admins`               | Admins for all services.         |
+
+---
+
+## 5. Implementation Steps
+
+### Step 1: Set Up Roles in Keycloak
+1. Go to **Realm Settings > Roles** for each realm.
+2. Add roles based on the new naming convention (e.g., `management_service_admin_nextcloud`).
+3. Map these roles to clients (e.g., Nextcloud, Paperless).
+
+### Step 2: Create Groups
+1. Go to **Groups** in each realm.
+2. Add groups (e.g., `nextcloud_admins`, `employees`).
+3. Assign relevant roles to the groups.
+
+### Step 3: Assign Users to Groups
+1. Go to **Users > Groups**.
+2. Add users to groups to inherit permissions.
+
+---
+
+## 6. Example User Workflow
+
+### User: Jane Doe (AnalytikData)
+- Realm: `analytikdata`
+- Group: `employees`
+- Roles (via group): `analytikdata_user_nextcloud`, `analytikdata_user_paperless`
+- Access:
+  - Can log in to Nextcloud and Paperless as a regular user.
+
+### User: John Smith (Management)
+- Realm: `management`
+- Group: `nextcloud_admins`
+- Roles (via group): `management_service_admin_nextcloud`
+- Access:
+  - Admin access to Nextcloud in the management realm.
+
+---
+
+## 7. Git Commit Message
+
+```
+Restructure Keycloak roles and groups with realm prefixes
+
+- Implemented a consistent naming convention for roles:
+  <realm>_<scope>_<service> (e.g., management_service_admin_nextcloud).
+- Added roles for each service in management and company realms.
+- Created logical groups for user organization (e.g., nextcloud_admins, employees).
+- Mapped roles to groups to simplify user permission assignments.
+- Improved clarity and scalability for multi-realm setups.
+```