# Zugriff & Authentifizierung

> **Zielgruppe & Rolle**
>
> **Rolle**: IT-Administrator | **Voraussetzung**: Administrator-Zugriff auf Microsoft Entra ID oder OIDC IdP


# Zugriff & Authentifizierung

ConnectCLOUD setzt auf moderne, standardisierte Single Sign-On (SSO) Authentifizierung über **OpenID Connect (OIDC)**. Damit melden sich Ihre Benutzer mit ihren gewohnten Unternehmenszugangsdaten an, während Sie als Administrator die zentrale Kontrolle über Identitäten, Multi-Faktor-Authentifizierung (MFA) und Gruppenmitgliedschaften in Ihrem eigenen Identity Provider (IdP) behalten.

> **Hinweis: Anmeldung über HR**
>
> Die Anmeldung wird vom Dienst HR bereitgestellt (Microsoft Entra ID, Passkeys und – optional – der Anmeldedienst Ihres Unternehmens, Abschnitt 2). Neue Mandanten legt MBCOM in den Stammdaten an; der Onboarding-Assistent entfällt.


---

## 1. Microsoft Entra ID (Azure AD) einrichten

Für die Anbindung von Microsoft Entra ID erstellen Sie in Ihrem Microsoft Entra Admin Center eine eigene App-Registrierung für ConnectCLOUD.

```mermaid
flowchart LR
    A[Microsoft Entra ID] -->|OIDC Discovery & Token| B[ConnectCLOUD OIDC Broker]
    B -->|Sitzung & Berechtigungen| C[ConnectCLOUD Portal]
```

### Schritt 1: Neue App-Registrierung anlegen
1. Melden Sie sich im [Microsoft Entra Admin Center](https://entra.microsoft.com/) an.
2. Navigieren Sie zu **Identität > Anwendungen > App-Registrierungen** und klicken Sie auf **Neue Registrierung**.
3. Vergeben Sie die folgenden Basisdaten:
   - **Name:** z. B. `ConnectCLOUD (Ihre Organisation)`
   - **Unterstützte Kontotypen:** `Nur Konten in diesem Organisationsverzeichnis (Nur ein Mandant / Single tenant)`
   - **Umleitungs-URI (Redirect URI):**
     - Plattform: **Web**
     - URI: `https://app.mbcom.cloud/api/hr/v1/auth/microsoft/callback`
4. Klicken Sie auf **Registrieren**.

---

### Schritt 2: Redirect URI prüfen
Prüfen Sie nach der Erstellung unter **Verwalten > Authentifizierung**, ob die Redirect-URI exakt wie folgt eingetragen ist:

```text
https://app.mbcom.cloud/api/hr/v1/auth/microsoft/callback
```

> **Exakte Schreibweise erforderlich**
>
> - Plattform muss zwingend **Web** sein (nicht SPA oder Mobile/Desktop).
> - Verwenden Sie das `https://`-Protokoll.
> - Keine zusätzlichen Query-Parameter oder abschließenden Schrägstriche.


---

### Schritt 3: Client Secret (Geheimnis) erstellen
1. Öffnen Sie in der App-Registrierung den Menüpunkt **Verwalten > Zertifikate & Geheimnisse**.
2. Wählen Sie die Registerkarte **Geheime Clientschlüssel** und klicken Sie auf **Neuer geheimer Clientschlüssel**.
3. Geben Sie eine Beschreibung ein (z. B. `ConnectCLOUD SSO`) und wählen Sie eine empfohlene Gültigkeitsdauer (z. B. 12 oder 24 Monate).
4. Klicken Sie auf **Hinzufügen**.

> **Wichtig: Secret Value vs. Secret ID**
>
> Nach dem Speichern werden in der Tabelle zwei Spalten angezeigt: **Wert (Value)** und **Geheimnis-ID (Secret ID)**.
> - Kopieren Sie ausschließlich den **Wert (Value)** — dies ist das eigentliche Geheimnis.
> - Die **Geheimnis-ID** ist eine UUID und wird von ConnectCLOUD **nicht** benötigt.
> - Der Wert wird nach dem Verlassen der Seite nie wieder im Klartext angezeigt.


---

### Schritt 4: Client ID und Tenant ID notieren
Wechseln Sie zur **Übersicht** Ihrer App-Registrierung und notieren Sie:
- **Anwendungs-ID (Client-ID):** z. B. `7e8b61c2-3e21-4d32-bc55-a6a9efc99182`
- **Verzeichnis-ID (Mandanten-ID / Tenant ID):** z. B. `9b1a2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`

Aus der Verzeichnis-ID ergibt sich Ihre **Issuer URL**:
```text
https://login.microsoftonline.com/<Ihre-Verzeichnis-ID>/v2.0
```

---

### Schritt 5: API-Berechtigungen hinzufügen
Damit ConnectCLOUD den Benutzer anmelden und Sicherheitsgruppen auslesen kann, werden Microsoft Graph API-Berechtigungen benötigt:

1. Navigieren Sie zu **Verwalten > API-Berechtigungen** und klicken Sie auf **Berechtigung hinzufügen**.
2. Wählen Sie **Microsoft Graph** und anschließend **Delegierte Berechtigungen**.
3. Fügen Sie die folgenden **fünf** Berechtigungen hinzu:
   - `openid`
   - `profile`
   - `email`
   - `User.Read`
   - `GroupMember.Read.All`
4. Klicken Sie auf **Berechtigungen hinzufügen**.

---

### Schritt 6: Administratorzustimmung (Admin Consent) erteilen
Damit einzelne Mitarbeiter bei der Erstanmeldung nicht jeweils manuell um Zustimmung gebeten werden:

1. Klicken Sie in der Ansicht **API-Berechtigungen** auf die Schaltfläche **Administratorzustimmung für [Ihre Organisation] erteilen**.
2. Bestätigen Sie den Dialog.
3. Der Status aller Berechtigungen wechselt auf einen grünen Haken (**Gewährt für...**).

---

### Schritt 7: Gruppen-Claim für alle Gruppen hinzufügen
Damit Entra die Gruppenmitgliedschaften beim Login an ConnectCLOUD übermittelt:

1. Navigieren Sie in der App-Registrierung zu **Verwalten > Tokenkonfiguration**.
2. Klicken Sie auf **Gruppenanspruch hinzufügen**.
3. Wählen Sie **Alle Gruppen**.
4. Aktivieren Sie für den **ID-Token** die Eigenschaft **Gruppen-ID** und speichern Sie die Konfiguration.

ConnectCLOUD erhält dadurch die unveränderlichen Object IDs im `groups`-Claim. Die Object IDs werden intern für die sichere Rollenzuordnung verwendet. Für die Anzeige im Portal fragt ConnectCLOUD den lesbaren Gruppennamen über Microsoft Graph ab.

> **Ohne Gruppen-Claim sind keine Gruppen sichtbar**
>
> Die API-Berechtigung `GroupMember.Read.All` allein fügt dem ID-Token keinen `groups`-Claim hinzu. Der Gruppenanspruch muss zusätzlich in der Tokenkonfiguration der App aktiviert werden.


Weitere Informationen finden Sie in der [Microsoft-Dokumentation zu Gruppenansprüchen](https://learn.microsoft.com/de-de/entra/identity/hybrid/connect/how-to-connect-fed-group-claims).

---

### Schritt 8: Gruppen und Group Object IDs
Für die Zuordnung von Rollen (kundenweit wie `CUSTOMER_ADMIN` oder mandantenspezifisch wie `TENANT_ADMIN`, `TENANT_ADMIN_VIEWER`, `TENANT_VIEWER`, `TENANT_DATA_VIEWER`) verwendet ConnectCLOUD die Gruppen aus Microsoft Entra ID.

> **Technische Zuordnung über Object IDs**
>
> Microsoft Entra ID übermittelt im ID-Token die **Group Object ID** (z. B. `11111111-2222-3333-4444-555555555555`). ConnectCLOUD löst diese ID für die Anzeige automatisch in den sprechenden Gruppennamen auf, verwendet für Berechtigungen aber weiterhin ausschließlich die Object ID.
> - Navigieren Sie im Entra Admin Center zu **Identität > Gruppen > Alle Gruppen**.
> - Suchen Sie die gewünschte Sicherheitsgruppe (z. B. `ConnectCLOUD-Admins` oder `ConnectCLOUD-Buchhaltung`).
> - Kopieren Sie den Wert aus der Spalte **Objekt-ID**.
> - Teilen Sie diese Object ID MBCOM mit, damit die Gruppenzuordnung des Mandanten gepflegt werden kann.


---

## 2. Anmeldung mit Firmenkonto (Keycloak, Okta, Auth0, Google Workspace, ADFS)

Administratoren mit dem Recht **Identitäten verwalten** (`identity:admin`) richten unter **Einstellungen › Benutzer &
Zugriff › Anmeldung mit Firmenkonto** selbst einen oder mehrere OpenID-Connect-Anmeldedienste ein. Mitarbeitende wählen
auf der Anmeldeseite **Mit Firmenkonto anmelden**, geben ihre E-Mail-Adresse ein und werden zum Dienst ihrer Domain
weitergeleitet.

| Angabe | Beschreibung | Beispiel |
| :--- | :--- | :--- |
| **Issuer** | Basis-URL des Dienstes; ConnectCLOUD liest `/.well-known/openid-configuration` (nur HTTPS, öffentlich erreichbar) | `https://sso.ihrefirma.de/realms/main` |
| **Client ID** | Kennung der Anwendung, die Sie im Dienst für ConnectCLOUD anlegen | `connectcloud` |
| **Client Secret** | Geheimnis eines vertraulichen Clients (wird verschlüsselt gespeichert und nie wieder angezeigt); leer für einen öffentlichen Client mit PKCE | `********` |
| **Domains** | Login-Domains Ihres Mandanten, für die der Dienst anmeldet (eine Domain gehört höchstens zu einem Dienst) | `ihrefirma.de` |
| **Redirect URI** | Im Dienst als erlaubte Rückleitung eintragen | `https://app.mbcom.cloud/api/hr/v1/auth/oidc/callback` |
| **Scopes** | Fordert ConnectCLOUD an | `openid profile email` |

Voraussetzungen im Dienst: Das ID-Token enthält `email` und `email_verified: true`; es ist mit einem asymmetrischen
Verfahren signiert (z. B. RS256 oder ES256). Mit **Verbindung testen** prüfen Sie den Issuer vor dem Speichern.

### Domain bestätigen

Solange eine Domain nicht bestätigt ist, öffnet die Anmeldung über Ihren Dienst nur die Mandanten Ihres eigenen
Unternehmens. Zum Bestätigen legen Sie den angezeigten DNS-Eintrag an:

```text
_connectcloud-verify.ihrefirma.de.  TXT  "connectcloud-verify=…"
```

ConnectCLOUD prüft ausstehende Domains stündlich und bestätigte täglich; **Jetzt prüfen** prüft sofort. Fehlt der
Eintrag drei Prüfungen in Folge, ist die Domain nicht mehr bestätigt. Für bestätigte Domains können Sie
**Nur mit Firmenkonto** einschalten: Die Anmeldung mit Microsoft ist dann für diese Adressen gesperrt, Passkeys
bleiben möglich.

Neue Personen werden bei der ersten Anmeldung nach der Anmelderichtlinie Ihres Mandanten angelegt (wie bei Microsoft).

### Gruppen abgleichen

Unter **Gruppen** ordnen Sie Gruppen Ihres Anmeldedienstes HR-Gruppen zu (Claim-Name, Standard `groups`; bei Bedarf
zusätzliche Scopes wie `groups`). Bei jeder Anmeldung setzt ConnectCLOUD die Mitgliedschaft in den zugeordneten
HR-Gruppen genau auf die gemeldeten Gruppen; nicht zugeordnete HR-Gruppen bleiben unverändert. Sendet der Dienst den
Claim nicht, ändert sich nichts.

### Abmeldung über den Anmeldedienst

Tragen Sie im Dienst die angezeigte **Back-Channel-Logout-URL** ein
(`https://app.mbcom.cloud/api/hr/v1/oauth/backchannel/<ID>`). Meldet sich eine Person dort ab, endet auch ihre
ConnectCLOUD-Sitzung.

## 2a. Anwendungen mit ConnectCLOUD-Anmeldung

Unter **Einstellungen › Anmeldung & Berechtigungen › Apps mit ConnectCLOUD-Anmeldung** registrieren Administratoren eigene
Anwendungen (z. B. Wiki, Grafana), bei denen sich Mitarbeitende mit ihrem ConnectCLOUD-Konto anmelden – ohne
Zustimmungsdialog, für alle aktiven Mitarbeitenden oder nur für ausgewählte Gruppen.

| Angabe für die Anwendung | Wert |
| :--- | :--- |
| **Issuer / Discovery** | `https://app.mbcom.cloud` bzw. `https://app.mbcom.cloud/.well-known/openid-configuration` |
| **Client ID / Secret** | aus der Registrierung (das Secret wird nur einmal angezeigt) |
| **Flow** | Authorization Code mit PKCE (S256, Pflicht) |
| **Scopes** | `openid` (Pflicht), `profile`, `email`, `groups`, `offline_access` (Refresh-Token) |

Das ID-Token enthält eine je Anwendung eigene, dauerhafte Kennung (`sub`), auf Wunsch Name, E-Mail und die Namen der
HR-Gruppen. Mitarbeitende sehen ihre Anmeldungen unter **Anmeldung & Sicherheit** und können sie beenden. Hinterlegt
die Anwendung eine **Back-Channel-Logout-URL**, erhält sie beim Abmelden von ConnectCLOUD ein signiertes Logout-Token.

---

## 3. Checkliste für die Inbetriebnahme

Vor der Einrichtung durch MBCOM sollten Ihnen die folgenden Angaben vorliegen:

- [ ] **Issuer URL** oder **Microsoft Entra Tenant ID**
- [ ] **Client ID** der App-Registrierung
- [ ] **Client Secret Value** (Geheimschlüssel-Wert)
- [ ] **Redirect URI** `https://app.mbcom.cloud/api/hr/v1/auth/microsoft/callback` als Web-Redirect hinterlegt
- [ ] Delegierte Berechtigungen erteilt (`openid`, `profile`, `email`, `User.Read`, `GroupMember.Read.All`)
- [ ] **Administratorzustimmung (Admin Consent)** erfolgreich erteilt
- [ ] Unter **Tokenkonfiguration** den Gruppenanspruch **Alle Gruppen** mit **Gruppen-ID** für den ID-Token hinzugefügt
- [ ] **Group Object IDs** der administrativen und benutzerbezogenen Sicherheitsgruppen notiert

Übergeben Sie die Angaben anschließend an MBCOM.

---

## 4. Fehlerbehebung (Troubleshooting)

### Redirect URI Mismatch (`redirect_uri_mismatch`)
- **Ursache:** Die in Entra ID hinterlegte Redirect-URI stimmt nicht exakt mit dem ConnectCLOUD-Endpunkt überein.
- **Lösung:** Prüfen Sie in der App-Registrierung unter **Authentifizierung**, ob `https://app.mbcom.cloud/api/hr/v1/auth/microsoft/callback` buchstabengetreu hinterlegt ist. Plattform muss **Web** sein.

### Administratorzustimmung erforderlich (`AADSTS65001`)
- **Ursache:** Der Admin Consent für die Microsoft Graph API-Berechtigungen wurde nicht erteilt.
- **Lösung:** Öffnen Sie **API-Berechtigungen** und klicken Sie auf **Administratorzustimmung für [Mandant] erteilen**.

### Ungültiges Client Secret (`AADSTS7000215`)
- **Ursache:** Es wurde versehentlich die **Secret ID** statt des **Secret Value** eingetragen, oder das Secret ist abgelaufen.
- **Lösung:** Erstellen Sie unter **Zertifikate & Geheimnisse** ein neues Client Secret und kopieren Sie sofort den Inhalt der Spalte **Wert**.

### Keine Gruppen im Token / Lockout-Gate sperrt
- **Ursache:** Der Gruppenanspruch fehlt in der Tokenkonfiguration, im Portal wurde der Anzeigename statt der Object ID eingetragen oder die Berechtigung `GroupMember.Read.All` fehlt.
- **Lösung:** Fügen Sie unter **Tokenkonfiguration** den Gruppenanspruch **Alle Gruppen** mit **Gruppen-ID** hinzu und stellen Sie sicher, dass in den Berechtigungseinstellungen die 36-stellige **Objekt-ID** der Entra-Gruppe hinterlegt ist.

### Gruppen werden nur als Object ID angezeigt
- **Ursache:** Microsoft Graph konnte den Anzeigenamen nicht auflösen, beispielsweise weil `GroupMember.Read.All`, der Admin Consent oder der Graph-Scope fehlt.
- **Lösung:** Prüfen Sie die delegierte Graph-Berechtigung und die Administratorzustimmung. Die Anmeldung funktioniert weiterhin; ConnectCLOUD verwendet die Object ID als sicheren Fallback.

---

## 5. Aussperrschutz & Notfall-Wiederherstellung (Self-Service Recovery)

Wenn die OIDC-Anmeldung fehlschlägt (z. B. durch ein abgelaufenes Client Secret, geänderte Entra-Zertifikate oder fehlerhafte Redirect-Konfigurationen) und kein Administrator mehr Zugriff auf das Portal hat:

### Einstiegspunkte
- **Login-Bildschirm:** Klicken Sie direkt unter dem Anmeldeformular auf **„Zugang wiederherstellen“**.
- **Fehlerseite („Anmeldung nicht möglich“):** Schlägt die Identitätsprüfung fehl, führt die angezeigte Fehlerseite direkt zur Wiederherstellung.
- **Portal-Shell:** Im Footer jeder unauthentifizierten Seite finden Sie den Link **„Zugang wiederherstellen“**.
- **Direktlink:** Rufen Sie `{PORTAL_URL}/recovery` auf.

### Die 2 erforderlichen Faktoren
Die Self-Service-Wiederherstellung erfordert zwei Sicherheitsfaktoren:
1. **Faktor 1 (Mailbox-Besitz):** Zugriff auf das Postfach eines im Kundenkonto verifizierten Recovery-Kontakts (Erhalt des einmaligen Recovery-Links).
2. **Faktor 2 (Einmal-Wiederherstellungscode):** Eingabe eines unverbrauchten Einmal-Recovery-Codes (aus dem bei der Ersteinrichtung generierten 8er-Set).

Nach Validierung beider Faktoren öffnet sich der Recovery-Assistent, in dem Sie die OIDC-Zugangsdaten korrigieren, per Testlogin verifizieren und den Zugang sofort wiederherstellen können.

> **Letzter Ausweg (MBCOM Support)**
>
> Sollten alle 8 Recovery-Codes und der Zugriff auf die Postfächer verloren sein, kann der **MBCOM-Support** (`support@mbcom.de`) als dokumentierter letzter Ausweg eine manuelle Notfall-Wiederherstellung anstoßen.


---

> **Nächster Schritt in der Basiskonfiguration**
>
> Nach der Konfiguration des Identity Providers definieren Sie die Zugriffs- und Berechtigungsregeln:
> [**Berechtigungskonzept & Rollenmodell**](/knowledge/docs/base/permission-concept.md)
>
> Zurück zur Übersicht: [**Basiskonfiguration Übersicht**](/knowledge/docs/base.md)
