# Berechtigungskonzept

> **Zielgruppe & Rolle**
>
> **Rolle**: IT-Administrator / Kunden-Admin | **Voraussetzung**: OIDC / Microsoft Entra ID Anbindung eingerichtet


# Berechtigungskonzept

Das Berechtigungskonzept der ConnectCLOUD basiert auf einer mandantenbezogenen Zugriffskontrolle und einer rollenbasierten Berechtigungssteuerung (RBAC).

## Architektur-Übersicht

Das folgende Diagramm illustriert den Autorisierungsprozess:

```mermaid
graph TD
	User[Benutzer] -->|Login| Provider[Microsoft Entra ID / Passkey]
    Provider -->|Anmeldung| HR[HR Service]
    HR -->|Login-Domains| Tenants[Erlaubte Mandanten]
    HR -->|Mitgliedschaften| Roles[Rollen & Berechtigungen]
    Roles -->|New JWT| User
    User -->|API Request| Services[Microservices]
    Services -->|Validate| Principal[Principal Context]
```

## Mandanten-basierte Zugriffskontrolle

Der Zugriff auf einen Mandanten wird über E-Mail-Regex-Regeln gesteuert. Jeder Mandant kann eine Liste von regulären Ausdrücken definieren (`allowedEmailRegex`). Wenn die E-Mail-Adresse eines angemeldeten Benutzers auf einen dieser Ausdrücke passt, erhält der Benutzer Zugriff auf diesen Mandanten.

### Konfiguration
Die Konfiguration erfolgt im Portal unter **Administration > Berechtigungen**.
Hier können pro Zeile reguläre Ausdrücke hinterlegt werden.

* **Beispiel**: `(?i)^.*@mbcom\.de$` erlaubt allen Benutzern mit einer mbcom.de E-Mail-Adresse den Zugriff.

### Login-Domains

Die Anmeldung und die Zuordnung einer E-Mail-Adresse zu einem Mandanten übernimmt der Dienst HR. Jeder Mandant hat eine Anmelderichtlinie und eine Liste von **Login-Domains** (Einstellungen › Anmeldung & Berechtigungen › Anmeldung); die Domain einer E-Mail-Adresse wird exakt und ohne Beachtung der Groß-/Kleinschreibung abgeglichen. Eine Domain gehört zu genau einem Kunden; ein Konflikt wird beim Speichern abgelehnt. Details: `AUTH.md`, Abschnitt 3.

## Rollen und Berechtigungen

Berechtigungen werden in ConnectCLOUD differenziert auf zwei Ebenen gesteuert:
1. **Kunden-Ebene (`CUSTOMER_ADMIN`):** Übergreifende Administration für das gesamte Kundenkonto (Stammdaten, Benachrichtigungseinstellungen, Notfall-Wiederherstellung, Einmalcodes und kundenweite Administrator-Gruppen).
2. **Mandanten-Ebene (`TENANT_*`):** Spezifische Berechtigungen und Zugriffsrollen für einzelne Mandanten.

### Verfügbare Rollen

| Rolle | Ebene | Beschreibung | Wichtigste Berechtigungen |
| :--- | :--- | :--- | :--- |
| **`CUSTOMER_ADMIN`** | Kunde | Kundenweiter Administrator mit Vollzugriff auf übergreifende Einstellungen und Notfallwiederherstellung. | `customer:settings:read`, `customer:settings:write` |
| **`TENANT_ADMIN`** | Mandant | Mandanten-Administrator mit vollem Schreibzugriff auf Mandanten-Einstellungen, Token-Generierung, Rechnungsvergleich sowie administrativer Steuerung von Workflow-Instanzen. | `settings:read`, `settings:write`, `invoice:compare:run`, `invoice:compare:read`, `workflow:admin`, `desk:admin`, `desk:confidential` |
| **`TENANT_ADMIN_VIEWER`** | Mandant | Lesender Zugriff auf Mandanten-Einstellungen. | `settings:read`, `desk:read`, `desk:write` |
| **`TENANT_DATA_VIEWER`** | Mandant | Standardzugriff plus Lesezugriff auf microtech-Daten. | `tenant:access`, `dataview:read` |
| **`TENANT_VIEWER`** | Mandant | Basis-Zugriff auf den Mandanten, die Beleg-/Workflow-Bearbeitung und den Service Desk. | `tenant:access`, `desk:read`, `desk:write` |
| **`PORTAL_ADMIN`** | System | Globaler System-Administrator von MBCOM mit uneingeschränktem Zugriff auf alle Mandanten und Systemeinstellungen. Erhält, wer im Betreiber-Mandanten 10639/MBCOM eine Rolle mit `portal:admin` hat (Rolle *Portal-Administration*); nur dort vergebbar. | `*` (Volle Systemrechte) |

### Wie wird die Rolle `CUSTOMER_ADMIN` ermittelt?

Die Rolle `CUSTOMER_ADMIN` wird dynamisch vom System nach folgenden Kriterien vergeben:

```mermaid
flowchart TD
    Start[Benutzer meldet sich an] --> CheckRecovery{E-Mail ist verifizierter Recovery-Kontakt?}
    CheckRecovery -- Ja --> GrantAdmin[Rolle CUSTOMER_ADMIN vergeben]
    CheckRecovery -- Nein --> CheckGroupMapping{Kundenweite Gruppen-Zuordnung konfiguriert?}
    CheckGroupMapping -- Ja --> CheckUserGroup{Gehört Benutzer zu CUSTOMER_ADMIN-Gruppe?}
    CheckUserGroup -- Ja --> GrantAdmin
    CheckUserGroup -- Nein --> DenyAdmin[Keine CUSTOMER_ADMIN-Berechtigung]
    CheckGroupMapping -- Nein (Fallback) --> CheckTenantAdmin{Besitzt Benutzer TENANT_ADMIN auf einem Mandanten?}
    CheckTenantAdmin -- Ja --> GrantAdmin
    CheckTenantAdmin -- Nein --> DenyAdmin
```

1. **Verifizierter Recovery-Kontakt:** Benutzer, deren E-Mail-Adresse im Reiter **Sicherheit** der [Kunden-Administration](/knowledge/docs/base/customer-administration.md) als bestätigte Notfalladresse hinterlegt ist, erhalten bedingungslos `CUSTOMER_ADMIN`.
2. **Kundenweites Gruppen-Mapping:** Wenn Sicherheitsgruppen der Rolle `CUSTOMER_ADMIN` zugewiesen sind, erhalten alle Gruppenmitglieder die Rolle.
3. **Automatischer Fallback:** Ist keine kundenweite Gruppen-Zuordnung hinterlegt, greift zur Gewährleistung der Abwärtskompatibilität ein automatischer Fallback: Alle Benutzer mit der Rolle `TENANT_ADMIN` auf mindestens einem Mandanten erhalten ebenfalls Zugriff auf die Kunden-Administration.

### Mandantenspezifisches Gruppen-Mapping

In den Mandanten-Einstellungen (**Administration > Berechtigungen**) legen Sie fest, welche OIDC-Gruppe (Object ID aus Entra ID) welcher internen Rolle für den gewählten Mandanten zugeordnet wird. Dies ermöglicht eine flexible Steuerung basierend auf bestehenden Berechtigungsgruppen Ihrer Organisation.

### Mandantenweite Workflow-Administration (`workflow:admin`)

Um betriebliche Prozesse abzusichern und die Vertraulichkeit von Prüfpfaden zu gewährleisten, wird die administrative Steuerung von Workflow-Instanzen über eine dedizierte Berechtigung gesteuert:

* **Exklusive Rollenzuordnung:** Die Berechtigung `workflow:admin` ist **strikt und ausschließlich** der Rolle `TENANT_ADMIN` zugewiesen.
* **Ausschluss für System- und Portal-Administratoren:** Die Rolle `PORTAL_ADMIN` erhält `workflow:admin` standardmäßig **nicht**. Portal-Administratoren können Workflow-Instanzen eines Kunden nur dann einsehen oder verwalten, wenn ihnen explizit die Rolle `TENANT_ADMIN` für den jeweiligen Mandanten zugewiesen wurde. Dadurch bleibt die Trennung zwischen System-Hosting und Mandantendaten gewahrt.
* **Enthaltene Verwaltungsfunktionen:**
  * **Zentraler Instanzenüberblick:** Einsicht in sämtliche aktiven, abgeschlossenen, genehmigten, abgelehnten und abgebrochenen Workflow-Instanzen des Mandanten über den Tab *Alle Workflow-Instanzen* in der Aufgabenübersicht – unabhängig von der persönlichen Entra-Gruppenzugehörigkeit.
  * **Administrativer Workflow-Abbruch:** Berechtigung zur außerordentlichen Beendigung verwaister oder blockierter Workflows (`POST /api/workflow/v1/tasks/:id/cancel`) inklusive automatischer Entsperrung des Vorgangs in microtech ERP und revisionssicherem Audit-Protokoll.

### Service Desk (`desk:*`)

| Berechtigung | Erlaubt | Rollen |
| :--- | :--- | :--- |
| `desk:read` | Tickets in allen für den Mandanten sichtbaren Bereichen lesen (Bereichsrolle *Lesen*) | `TENANT_VIEWER`, `TENANT_ADMIN_VIEWER`, `TENANT_ADMIN`, `PORTAL_ADMIN`, Servicekonten |
| `desk:write` | Tickets anlegen, bearbeiten, Status wechseln, kommentieren, Zeit erfassen (Bereichsrolle *Bearbeiten*) | wie `desk:read` |
| `desk:admin` | Konfiguration: Bereiche, Arten, Abläufe, Felder, Prioritäten, Labels, Teams; *Verwalten* in jedem Bereich | `TENANT_ADMIN` |
| `desk:confidential` | Vertrauliche Tickets (z. B. Sicherheitsvorfälle) sehen | `TENANT_ADMIN` |

Innerhalb des Service Desk verfeinern **Bereichsrollen** den Zugriff: *Lesen* < *Melden* (anlegen und
kommentieren) < *Bearbeiten* < *Verwalten* (Bereich, Labels). Bereiche mit der
Sichtbarkeit „Nur Mitglieder“ sind ausschließlich für ihre Mitglieder sichtbar. Vertrauliche Tickets
sehen zusätzlich ihr Ersteller und die eingetragenen Beteiligten. Wie bei `workflow:admin` erhält
`PORTAL_ADMIN` weder `desk:admin` noch `desk:confidential`.

### Entwicklung (`tenant:forge:*`)

| Berechtigung | Erlaubt | Rollen |
| :--- | :--- | :--- |
| `tenant:forge:read` | Entwicklungsprojekte, ihre Vorgänge, Abschnitte und Kommentare ansehen | `TENANT_VIEWER`, `TENANT_ADMIN_VIEWER`, `TENANT_ADMIN`, `PORTAL_ADMIN` |
| `tenant:forge:write` | Vorgänge anlegen, bearbeiten, kommentieren, verknüpfen, übergeben und umwandeln | `TENANT_VIEWER`, `TENANT_ADMIN`, `PORTAL_ADMIN` |
| `tenant:forge:admin` | Projekte anlegen, Mitglieder, Repositories und Konfiguration jedes Projekts pflegen | `TENANT_ADMIN`, `PORTAL_ADMIN` |
| `tenant:forge:intake` | Übergaben aus dem Service Desk in Projekte, die sie annehmen – ohne weiteren Zugriff | `TENANT_VIEWER`, `TENANT_ADMIN`, `PORTAL_ADMIN` |

In der Entwicklung verfeinern **Projektrollen** den Zugriff: *Meldend* < *Entwicklung* < *Pflege* < *Verwaltung*.
Private Projekte sehen nur ihre Mitglieder und die Administration der Entwicklung. **Vertrauliche Vorgänge** – auch
die aus vertraulichen Tickets übergebenen – sehen nur die Administration der Entwicklung, Mitglieder ab *Pflege*,
die meldende Person und die Zuständigen. Wer ein Ticket an die Entwicklung übergibt, braucht dort selbst eine dieser
Berechtigungen; siehe [Übergabe und Umwandlung](/knowledge/docs/products/portal/user-docs/uebergabe-und-umwandlung.md).

## Mandantenwechsel

Ein Benutzer kann zwischen den Mandanten wechseln, auf die er Zugriff hat.

1. **Mandantenauswahl**: Links oben im Portal befindet sich der Mandantenumschalter.
2. **URL-Parameter**: Über den Query-Parameter `?tenant=<mandantename>` kann ein Wechsel direkt beim Aufruf einer Seite ausgelöst werden.
3. **Session-Aktualisierung**: Beim Wechsel eines Mandanten wird ein neues Session-Token (JWT) ausgestellt, das die spezifischen Rollen und Berechtigungen für den Zielmandanten enthält.

---

> **Nächster Schritt in der Basiskonfiguration**
>
> Nachdem das Berechtigungskonzept definiert ist, richten Sie die Schnittstelle zu microtech büro+ ein:
> [**microtech Basis-Konfiguration**](/knowledge/docs/base/microtech-connection.md)
>
> Zurück zur Übersicht: [**Basiskonfiguration Übersicht**](/knowledge/docs/base.md)
