UTCM Service Principal einrichten¶

Der UTCM Service Principal (Unified Tenant Configuration Management) ist ein von Microsoft bereitgestellter Service Principal, der für die Erfassung von Teams- und Exchange-Konfigurationen benötigt wird.

Was ist der UTCM Service Principal?¶

Microsoft stellt Teams- und Exchange-Konfigurationen nicht über die regulaere Graph API bereit. Stattdessen müssen diese über die UTCM Snapshot Job API erfasst werden. Diese API setzt voraus, dass der offizielle UTCM Service Principal in Ihrem Tenant registriert und mit den entsprechenden Admin-Rollen ausgestattet ist.

So funktioniert UTCM¶

sequenceDiagram
    participant TCM as TCM365
    participant Graph as Microsoft Graph API
    participant UTCM as UTCM API
    participant SP as UTCM Service Principal

    TCM->>Graph: Snapshot Job erstellen<br/>(POST /admin/configurationMonitoring/snapshotJobs)
    Graph->>UTCM: Job an UTCM weiterleiten
    UTCM->>SP: Teams/Exchange-Konfig lesen<br/>(als Teams Admin / Exchange Admin)
    SP-->>UTCM: Konfigurationsdaten
    UTCM-->>Graph: Snapshot Job abgeschlossen
    TCM->>Graph: Ergebnis abrufen<br/>(GET /admin/configurationMonitoring/snapshotJobs/{id})
    Graph-->>TCM: Teams/Exchange-Konfigurationen

TCM365 startet einen Snapshot Job über die Graph API. Microsoft führt diesen Job im Hintergrund aus, wobei der UTCM Service Principal die Teams- und Exchange-Konfigurationen mit den ihm zugewiesenen Admin-Rollen liest.

Schritt 1: UTCM Service Principal registrieren¶

1. Öffnen Sie das Azure Portal unter portal.azure.com
2. Navigieren Sie zu Azure Active Directory > Enterprise Applications (Unternehmensanwendungen)
3. Klicken Sie auf New Application (Neue Anwendung)
4. Wählen Sie Create your own application (Eigene Anwendung erstellen)
5. Geben Sie einen Namen ein, z.B. UTCM Service Principal
6. Wählen Sie Register an application to integrate with Azure AD (App you're developing)
7. Klicken Sie auf Create

Alternativ können Sie den Service Principal per PowerShell registrieren:

# UTCM Service Principal im Tenant registrieren
New-AzureADServicePrincipal -AppId "03b07b79-c5bc-4b5e-9bfa-13acf4a99998"

Oder mit der Microsoft Graph PowerShell:

# Mit Microsoft Graph verbinden
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# UTCM Service Principal erstellen
New-MgServicePrincipal -AppId "03b07b79-c5bc-4b5e-9bfa-13acf4a99998"

Schritt 2: Admin-Rollen zuweisen¶

Der UTCM Service Principal benötigt Admin-Rollen, um die Teams- und Exchange-Konfigurationen lesen zu können:

1. Navigieren Sie zu Azure Active Directory > Roles and administrators
2. Weisen Sie dem UTCM Service Principal folgende Rollen zu:

Rollen per PowerShell zuweisen¶

# Teams Administrator Rolle zuweisen
$teamsAdminRole = Get-AzureADDirectoryRole | Where-Object { $_.DisplayName -eq "Teams Administrator" }
$utcmSP = Get-AzureADServicePrincipal -Filter "AppId eq '03b07b79-c5bc-4b5e-9bfa-13acf4a99998'"
Add-AzureADDirectoryRoleMember -ObjectId $teamsAdminRole.ObjectId -RefObjectId $utcmSP.ObjectId

# Exchange Administrator Rolle zuweisen
$exchangeAdminRole = Get-AzureADDirectoryRole | Where-Object { $_.DisplayName -eq "Exchange Administrator" }
Add-AzureADDirectoryRoleMember -ObjectId $exchangeAdminRole.ObjectId -RefObjectId $utcmSP.ObjectId

Schritt 3: Admin Consent erteilen¶

1. Navigieren Sie zu Enterprise Applications > suchen Sie nach dem UTCM Service Principal
2. Öffnen Sie Permissions
3. Klicken Sie auf Grant admin consent
4. Bestätigen Sie die Zustimmung

UTCM API Limits¶

Die UTCM API unterliegt bestimmten Einschränkungen, die TCM365 automatisch berücksichtigt:

Was passiert ohne UTCM Service Principal?¶

Wenn der UTCM Service Principal nicht eingerichtet ist:

• Teams-Workload: Nicht verfügbar -- Teams-Konfigurationen können nicht erfasst werden
• Exchange-Workload: Nicht verfügbar -- Exchange-Konfigurationen können nicht erfasst werden
• Alle anderen Workloads: Funktionieren normal (Entra ID, Intune, Defender, SharePoint, Purview, Cloud PC)

TCM365 erkennt beim Verbindungstest automatisch, ob der UTCM Service Principal vorhanden ist, und zeigt die verfügbaren Workloads entsprechend an.

Fehlersuche¶

"UTCM Service Principal not found"¶

Der Service Principal ist nicht im Tenant registriert. Führen Sie Schritt 1 erneut durch.

"Insufficient privileges for UTCM snapshot job"¶

Dem Service Principal fehlen die erforderlichen Admin-Rollen. Prüfen Sie, ob Teams Administrator und/oder Exchange Administrator zugewiesen sind (Schritt 2).

"Snapshot job timed out"¶

UTCM Snapshot Jobs können bei grossen Tenants einige Minuten dauern. TCM365 wartet standardmaessig bis zu 10 Minuten. Prüfen Sie die UTCM API Limits.

Nächster Schritt¶

• Workloads & Permissions im Ueberblick
• Tenant in TCM365 verbinden