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