Microsoft 365 (Graph API)

Kurzüberblick

Der SyncModus Microsoft365 ist der Graph-basierte Kalender-Sync für Exchange Online / Microsoft 365.

Wichtig:

• EWS1, EWS2 und O365 sind weiterhin EWS-basierte Modi gegen eine .asmx-Schnittstelle
• Microsoft365 ist ein eigener Modus mit Microsoft Graph API, Graph-Webhooks und separater CalendarSync-Konfiguration in appsettings.json

EWS-Modi vs Microsoft365

AppOnly vs Delegated

UX-Unterschied für Enduser

AppOnly

• Benutzer sehen keinen Connect-/Disconnect-Button
• es erscheint keine Graph-Consent-Maske beim Login
• nach dem Setzen von SyncModus = Microsoft365 läuft die Provisionierung im Hintergrund
• wenn Mailadresse, Rechte und Worker stimmen, startet der Sync ohne weiteren Benutzer-Schritt

Delegated

• Benutzer sehen im Personenprofil einen Connect-/Disconnect-Status
• beim ersten Login oder nach dem Speichern der Person kann ROOMS den Graph-Consent-Flow automatisch starten
• ohne Consent wird für diese Person keine Graph-Subscription angelegt
• typische Status:
  • None - noch nicht verbunden
  • Pending - Zustimmung wurde angestossen, aber noch nicht abgeschlossen
  • Granted - verbunden, Sync darf laufen
  • Revoked - Verbindung wurde entzogen

Microsoft Entra ID einrichten

Variante A: AppOnly

1. App registrieren

   • Microsoft Entra ID → App-Registrierungen → Neue Registrierung
   • in den meisten Fällen ist Single Tenant die richtige Wahl
   • einen anderen Kontotyp nur wählen, wenn Ihr Entra- / Mandantenmodell das ausdrücklich erfordert
   • Client ID und Tenant ID notieren

2. API-Berechtigungen

   • Microsoft Graph → Application permissions
   • Calendars.ReadWrite
   • User.Read.All
   • Admin Consent für die Organisation erteilen

3. Secret oder Zertifikat

   • entweder Client Secret erstellen
   • oder Zertifikat hinterlegen und Thumbprint notieren

4. Optional: Mailboxzugriff einschränken

   • empfohlen: Exchange Application RBAC
   • ältere Alternative: Application Access Policy

Variante B: Delegated

1. App registrieren

   • Microsoft Entra ID → App-Registrierungen → Neue Registrierung
   • Client ID und Tenant ID notieren

2. Redirect URI

   • Typ Web
   • Redirect URI: https://<idp-host>/signin-graph

3. API-Berechtigungen

   • Microsoft Graph → Delegated permissions
   • Calendars.ReadWrite
   • User.Read

4. Consent-Richtlinie prüfen

   • wenn Benutzer-Consent im Tenant erlaubt ist, kann der Benutzer selbst zustimmen
   • in restriktiven Tenants muss ein Administrator die Zustimmung zentral erteilen oder den Consent-Workflow freigeben

5. Refresh Token zulassen

   • ROOMS fordert im OAuth-Flow zusätzlich offline_access an
   • dadurch kann ROOMS Benutzer-Tokens im Hintergrund erneuern

6. Wichtig für den Consent-Flow

   • der interaktive GraphConsent-Flow verwendet weiterhin ClientSecret
   • für Delegated sollte daher ClientSecret konfiguriert sein, auch wenn Sie Zertifikate für andere Graph-Pfade verwenden

ROOMS konfigurieren

Die Graph-Konfiguration liegt in der appsettings.json des IDP / RoomsPro.Web unter CalendarSync:Graph.

Erforderliche Schlüssel

Hinweise:

• CallbackUrl ist optional
• wenn CallbackUrl leer bleibt, verwendet ROOMS automatisch die IdpRootUrl
• CallbackUrl ist die Basis-URL, ohne /api/webhooks/graph
• AppOnly-Pfad für Subscription- / Management-Operationen unterstützt Client Secret oder Zertifikat
• Delegated benötigt für den interaktiven Consent-Flow weiterhin ClientSecret
• DomainOverrides gelten nur für app-basierte Graph-Zugriffe; der delegierte Personen-Consent bleibt global

Mehrere M365-Tenants nach Mail-Domäne

Mit CalendarSync:Graph:DomainOverrides können app-basierte Graph-Zugriffe abhängig von der primären SMTP-Domäne einer Mailbox andere Tenant- und App-Credentials verwenden. Dies gilt für alle Zugriffe bei AuthMode = AppOnly sowie für Ressourcenpostfächer in einer Delegated-Umgebung.

Beachten Sie dabei:

• der Override-Schlüssel enthält die vollständige Domäne nach dem @, aber nicht das @ selbst
• Gross- und Kleinschreibung werden nicht berücksichtigt; Wildcards und automatische Treffer für Subdomains werden nicht unterstützt
• nicht zugeordnete Domänen verwenden die Standard-Credentials unter CalendarSync:Graph
• jeder Override benötigt eine vollständige TenantId, AppId und entweder ClientSecret oder CertificateThumbprint; einzelne Standardwerte werden nicht geerbt
• TenantId muss eine Verzeichnis-ID im GUID-Format sein und darf keine Tenant-Domäne wie contoso.onmicrosoft.com enthalten
• jede konfigurierte Entra-App benötigt die Graph-Anwendungsberechtigungen und den Admin Consent im jeweiligen Ziel-Tenant
• AuthMode, CallbackUrl, ClientState, delegierter Consent und Refresh Tokens bleiben global
• dieselbe Konfiguration muss für API und Worker bereitgestellt werden

Ein vollständiges JSON-Beispiel und das Schema für Umgebungsvariablen finden Sie unter Konfigurationen.

Zertifikatsauthentisierung: genauer Support-Umfang

Die Codebasis enthält zwei Graph-Pfade:

• ein Graph-Client-/Session-Pfad in der legacy ROOMS-Logik
• die neuere RoomsPro-Graph-Infrastruktur für Subscription-Provisionierung, Renewal und weitere Verwaltungsoperationen

Code-verifiziert gilt:

• die legacy Graph-Client-Erzeugung unterstützt Client Secret oder Zertifikat
• die RoomsPro-Graph-Infrastruktur unterstützt für AppOnly- / Hintergrundoperationen ebenfalls Client Secret oder Zertifikat
• der interaktive Delegated-Consent-Flow verwendet weiterhin ClientSecret

Praktische Folge:

• für AppOnly kann Graph mit Client Secret oder Zertifikat betrieben werden
• für Delegated sollten Sie weiterhin ClientSecret einplanen, weil der Consent-Flow davon abhängt

Ein vollständiges Beispiel für die komplette CalendarSync-Section finden Sie unter Konfigurationen.

Personen und Ressourcen in ROOMS konfigurieren

Personen

• SyncModus: Microsoft365
• E-Mail: primäre SMTP-Adresse
• Sync-URL: nicht relevant
• Sync deaktiviert: darf nicht aktiv sein, wenn automatisch provisioniert werden soll

Delegated-Umgebungen:

• Benutzer verbinden den Kalender einmalig
• der Consent-Status ist im Personenprofil sichtbar
• nach Granted wird die Person-Subscription automatisch provisioniert

AppOnly-Umgebungen:

• kein Benutzer-Consent nötig
• die Person-Subscription wird im Hintergrund angelegt

Ressourcen

• SyncModus: Microsoft365
• E-Mail: primäre SMTP-Adresse der Ressourcenmailbox
• Sync-URL: nicht relevant

Ressourcen werden bei Microsoft365 immer app-basiert verarbeitet.

Webhooks veröffentlichen

Für Microsoft365 müssen folgende Endpunkte erreichbar sein:

• https://<basis-url>/api/webhooks/graph
• https://<basis-url>/api/webhooks/graph/lifecycle

Empfehlungen:

• gültiges öffentliches TLS-Zertifikat
• keine Pre-Authentication vor den Webhooks
• anonyme POST-Requests zulassen
• wenn möglich Zugriff via Reverse Proxy absichern

Hintergrundverarbeitung

Der Graph-Sync nutzt einen separaten Hintergrundverarbeitungsdienst.

Wichtige Jobs:

• GraphSubscriptionProvisioning
• GraphSubscriptionRenewal
• DelegatedTokenRefresh
• MigrateSyncItemIds
• PrepareGraphToEwsBackSync

Es ist keine manuelle StructureMapXml-Aktivierung für Graph-Subscription-Management nötig.

Zur Betriebsprüfung:

• RoomsPro.Worker muss laufen
• Dashboard für Hintergrundjobs unter /tickerq prüfen

Was passiert im Hintergrund?

• für Personen und Ressourcen werden Graph-Subscriptions angelegt
• Graph sendet Änderungen an den Webhook
• Lifecycle-Webhooks lösen Erneuerungen / Re-Authorisierung aus
• bei der ersten Person-Subscription werden bestehende EWS-SyncItemIds in Graph-IDs migriert
• beim Rückwechsel von Microsoft365 auf EWS wird eine Vorbereitung Graph → EWS eingeplant

Hilfreiche Links

• Konfigurationen - vollständiges CalendarSync-Beispiel
• Personen konfigurieren - Profile sauber setzen
• Aktivieren der Services - Hintergrundverarbeitung und legacy Sessions
• Problembehandlung - Fehlersuche im Betrieb

Referenzen

• Graph permissions reference: https://learn.microsoft.com/en-us/graph/permissions-reference
• Change notifications overview: https://learn.microsoft.com/en-us/graph/change-notifications-overview
• Exchange Application RBAC: https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac