UTCM API-Referenz¶
Microsofts Unified Tenant Configuration Management (UTCM) API ist die Grundlage für TCM365s Microsoft 365-Integration. UTCM bietet eine zentralisierte API-Oberfläche zum Erfassen, Überwachen und Verwalten von Tenant-Konfigurationen über Teams, Exchange, Entra ID und Intune Workloads.
Beta API
UTCM befindet sich derzeit in Public Preview und ist nur über den Microsoft Graph Beta-Endpoint verfügbar. API-Signaturen können sich ohne Vorankuendigung ändern. TCM365 abstrahiert diese Details durch den M365Adapter und UtcmService.
Offizielle Microsoft-Dokumentation¶
| Dokument | URL |
|---|---|
| Konzept-Übersicht | UTCM Concept Overview |
| API-Referenz (Beta) | UTCM API Reference |
| Authentication Setup | UTCM Authentication |
| Teams Resources | UTCM Teams |
| Exchange Resources | UTCM Exchange |
| Entra Resources | UTCM Entra |
| Intune Resources | UTCM Intune |
| Schema Store | JSON Schema |
UTCM-Konzeptuebersicht¶
UTCM ermöglicht Organisationen:
- Erfassen -- Point-in-Time-Snapshots von Tenant-Konfigurationen via Snapshot Jobs
- Überwachen -- Konfigurationen gegen gewünschte Baselines via Configuration Monitors
- Drift erkennen -- Wenn Konfigurationen von der definierten Baseline abweichen
- Beheben -- Durch Anwenden des gewünschten Zustands zurück auf den Tenant
Schluesselterminologie¶
| Begriff | Definition | TCM365-Zuordnung |
|---|---|---|
| Snapshot Job | Asynchroner Job der aktuelle Tenant-Konfiguration extrahiert | UtcmService.createSnapshotJobAndWait() |
| Configuration Monitor | Prüft periodisch Konfiguration gegen Baseline, erkennt Drift | UtcmService.createMonitor() |
| Configuration Baseline | Soll-Zustand-Definition angehaengt an einen Monitor | Blueprint-Feature in TCM365 |
| Configuration Drift | Abweichung vom gewünschten Zustand erkannt durch Monitor | Configuration Drift-Modul |
| UTCM Service Principal | Microsoft First-Party App die Monitor/Snapshot Jobs ausfuehrt | App ID: 03b07b79-c5bc-4b5e-9bfa-13acf4a99998 |
Zwei Capture-Strategien¶
TCM365 verwendet zwei verschiedene Capture-Strategien für Microsoft 365-Konfigurationen, abhängig vom Workload:
Strategie 1: UTCM Snapshot Job API¶
Verwendet für Workloads wo Konfiguration durch UTCM verwaltet wird:
- Microsoft Teams -- Meeting Policies, Messaging Policies, Calling Policies etc.
- Microsoft Exchange -- Transport Rules, Remote Domains, Anti-Phishing Policies etc.
Strategie 2: Direct Microsoft Graph API¶
Verwendet für Workloads wo TCM365 Konfigurationen direkt via Graph API liest:
- Entra ID -- Conditional Access Policies, Named Locations, Authentication Methods
- Microsoft Intune -- Device Compliance Policies, Configuration Profiles
- Microsoft Defender -- Security Policies, Alert Configurations
- SharePoint -- Sharing Settings, Site Configurations
Warum zwei Strategien?
UTCMs Snapshot Job API bietet eine reichhaltigere, vollständigere Erfassung für Teams und Exchange (einschliesslich Einstellungen nicht verfügbar über Standard-Graph-Endpoints). Für andere Workloads bietet die Standard-Graph-API direkten, synchronen Zugriff.
UTCM Service Principal¶
Der UTCM Service Principal ist eine Microsoft First-Party-Anwendung, die Snapshot- und Monitoring-Jobs im Auftrag Ihres Tenants ausfuehrt.
| Eigenschaft | Wert |
|---|---|
| App ID | 03b07b79-c5bc-4b5e-9bfa-13acf4a99998 |
| Name | UTCM Service Principal |
| Zweck | Führt Snapshot Jobs und Monitor-Evaluierungen aus |
| Anforderung | Muss in Ihrem Tenant registriert und berechtigt sein |
Registrierung¶
Der UTCM Service Principal muss in Ihrem Azure AD Tenant registriert werden, bevor Teams/Exchange-Snapshots oder Monitors erstellt werden können:
# UTCM Service Principal registrieren
New-MgServicePrincipal -AppId '03b07b79-c5bc-4b5e-9bfa-13acf4a99998'
Erforderliche Rollen nach Workload¶
| Workload | Lese-Rolle | Schreib-Rolle | Hinweise |
|---|---|---|---|
| Teams | Global Reader | Teams Administrator | Erforderlich für UTCM SP |
| Exchange | Global Reader | Exchange Administrator | Exchange Application Access Policy erforderlich |
| Entra | Global Reader | Variiert je Ressource | Direct Graph API (kein UTCM SP nötig) |
| Intune | Global Reader | Intune Administrator | Direct Graph API (kein UTCM SP nötig) |
Unterstützte Workloads¶
| Workload | Capture-Methode | Resource Types | Beispiel-Ressourcen |
|---|---|---|---|
| Entra ID | Direct Graph | 15+ | Conditional Access, Named Locations, Auth Methods |
| Intune | Direct Graph | 10+ | Compliance Policies, Config Profiles, App Protection |
| Defender | Direct Graph | 5+ | Security Policies, Alert Configurations |
| Teams | UTCM Snapshot | 10+ | Meeting Policy, Messaging Policy, Calling Policy |
| Exchange | UTCM Snapshot | 8+ | Transport Rules, Anti-Phishing, Remote Domains |
| SharePoint | Direct Graph | 3+ | Sharing Settings, Site Configurations |
Resource Type-Format
Microsoft 365 Resource Types verwenden das Vendor-Prefixed-Format: microsoft.{workload}.{resource}. Beispiel: microsoft.entra.conditionalAccess, microsoft.teams.meetingPolicy.
API-Endpoints¶
Basis-URL¶
Alle UTCM API-Aufrufe verwenden den Microsoft Graph Beta-Endpoint:
Snapshot Jobs¶
| Operation | Methode | Pfad |
|---|---|---|
| Snapshot erstellen | POST | /configurationSnapshots/createSnapshot |
| Snapshot Jobs auflisten | GET | /configurationSnapshotJobs |
| Snapshot Job abrufen | GET | /configurationSnapshotJobs/{id} |
| Snapshot Job löschen | DELETE | /configurationSnapshotJobs/{id} |
| Daten herunterladen | GET | {resourceLocation} (aus abgeschlossener Job-Response) |
Job-Status-Werte:
| Status | Beschreibung |
|---|---|
notStarted |
Job erstellt aber noch nicht gestartet |
running |
Job wird ausgeführt |
succeeded |
Alle Ressourcen erfolgreich erfasst |
failed |
Job vollständig fehlgeschlagen |
partiallySuccessful |
Einige Ressourcen erfasst, andere fehlgeschlagen |
Configuration Monitors¶
| Operation | Methode | Pfad |
|---|---|---|
| Monitors auflisten | GET | /configurationMonitors |
| Monitor erstellen | POST | /configurationMonitors |
| Monitor abrufen | GET | /configurationMonitors/{id} |
| Monitor aktualisieren | PATCH | /configurationMonitors/{id} |
| Monitor löschen | DELETE | /configurationMonitors/{id} |
| Ergebnisse abrufen | GET | /configurationMonitors/{id}/results |
API-Limits und Quotas¶
UTCM erzwingt strikte API-Quotas, die TCM365 über die UTCMQuotaUsage-Entity verfolgt:
| Limit-Typ | Wert | Zeitraum | Hinweise |
|---|---|---|---|
| Snapshot Jobs | 10 | 24 Stunden | Pro Tenant |
| Aktive Monitors | 50 | -- | Pro Tenant (gleichzeitig) |
| Ressourcen pro Snapshot | 20 | Pro Job | Resource Type-Auswahl pro Snapshot Job |
| API-Anfragen | Gedrosselt | -- | Standard Graph API-Drosselung gilt |
Quota-Management
TCM365 verfolgt UTCM-Quota-Nutzung in der UTCMQuotaUsage-Entity und zeigt ein SnapshotQuotaBanner in der UI wenn Quotas sich Limits naehern. Der UtcmService verwaltet automatisch das Quota-Tracking während Snapshot- und Monitor-Operationen.
Authentifizierungsarchitektur¶
TCM365 verwendet ein zweistufiges Authentifizierungsmodell für die M365-Integration:
Stufe 1: Ihre App Registration¶
Ihre Azure AD App Registration authentifiziert sich bei der Graph API um Monitors, Snapshots zu verwalten und Konfigurationen direkt zu lesen.
Erforderliche Permissions:
| Permission | Typ | Zweck |
|---|---|---|
ConfigurationMonitoring.ReadWrite.All |
Application | UTCM Monitors und Snapshots verwalten |
Organization.Read.All |
Application | Tenant-Organisationsinfo lesen |
Directory.Read.All |
Application | Entra ID-Konfigurationen lesen |
Policy.Read.All |
Application | CA Policies und Auth Methods lesen |
DeviceManagementConfiguration.Read.All |
Application | Intune-Konfigurationen lesen |
AuditLog.Read.All |
Application | Audit Logs für Change Attribution lesen |
Stufe 2: UTCM Service Principal¶
Microsofts UTCM Service Principal führt Snapshot- und Monitor-Jobs im Hintergrund aus. Er muss separat registriert und berechtigt werden (siehe UTCM Service Principal-Abschnitt oben).
Ihre App Registration UTCM Service Principal
| |
+-- Erstellt Snapshot Job ------------> |
| +-- Führt Snapshot aus
+-- Pollt Job-Status +-- Erfasst Konfiguration
+-- Laedt Ergebnisse herunter <---- Gibt resourceLocation zurück
Fehlerbehebung¶
Häufige Probleme¶
| Problem | Ursache | Lösung |
|---|---|---|
Snapshot Job bleibt notStarted |
UTCM SP nicht im Tenant registriert | New-MgServicePrincipal-Befehl ausführen |
| Snapshot Job schlägt für Teams fehl | UTCM SP fehlt Global Reader Rolle | Global Reader dem UTCM SP zuweisen |
| Exchange Snapshot liefert leere Daten | Exchange Application Access Policy fehlt | Exchange RBAC für UTCM SP konfigurieren |
403 Forbidden bei Monitor-Erstellung |
ConfigurationMonitoring.ReadWrite.All fehlt |
Permission zur App Registration hinzufügen |
| Quota überschritten | Mehr als 10 Snapshot Jobs in 24 Stunden | Auf Quota-Reset warten oder alte Jobs löschen |
TCM365 Setup Wizard¶
Der M365 Setup Wizard (/api/v1/setup/m365/...) automatisiert die Voraussetzungspruefung einschliesslich:
- UTCM Service Principal-Erkennung und Registrierungsanleitung
- Workload-Probing zur Verifizierung des API-Zugriffs pro Workload
- Permission-Validierung für Ihre App Registration
- Global Reader-Rollen-Verifizierung für den UTCM SP
- Read/Write App Registration-Trennung (v2.2.0+)
- Graceful Degradation für Scope-beschraenkte Endpoints (v2.5.0+)