Schritt-für-Schritt: So erstellen Sie ein Autopilot Deployment Profil direkt mit der Graph API

Die moderne IT-Landschaft verlangt nach Effizienz, Skalierbarkeit und Automatisierung. Eine der größten Herausforderungen für Unternehmen ist die Bereitstellung neuer Geräte, insbesondere in Zeiten von Remote-Arbeit und global verteilten Teams. Hier kommt Windows Autopilot ins Spiel – eine Technologie, die den Prozess der Geräteregistrierung und Konfiguration erheblich vereinfacht. Anstatt jedes Gerät manuell vorzukonfigurieren, ermöglicht Autopilot ein Zero-Touch-Deployment, bei dem Endbenutzer ihre Geräte direkt von der Verpackung aus einrichten können.

Doch selbst die Konfiguration von Autopilot-Profilen im Microsoft Intune-Portal kann bei einer großen Anzahl von Profilen oder sich häufig ändernden Anforderungen zeitaufwendig sein. Hier setzen wir an: In diesem umfassenden Leitfaden erfahren Sie, wie Sie Autopilot Deployment Profile direkt mit der Microsoft Graph API erstellen und verwalten können. Dies eröffnet Ihnen die Möglichkeit zur vollständigen Automatisierung, Integration in CI/CD-Pipelines und einer noch nie dagewesenen Flexibilität in Ihrem Endpoint Management.

### Warum die Graph API für Autopilot Deployment Profile nutzen?

Die direkte Interaktion mit der Microsoft Graph API bietet mehrere überzeugende Vorteile gegenüber der rein portalbasierten Verwaltung:

1. Automatisierung und Skalierbarkeit: Erstellen Sie Hunderte von Profilen mit einem einzigen Skript. Ideal für große Organisationen oder Dienstleister, die eine Vielzahl von Kunden oder Abteilungen betreuen. Änderungen können zentralisiert und automatisiert ausgerollt werden.
2. Konsistenz: Eliminieren Sie menschliche Fehler, die bei manuellen Konfigurationen auftreten können. Skripte sorgen dafür, dass alle Profile exakt denselben Spezifikationen entsprechen.
3. Integration: Binden Sie die Erstellung und Verwaltung von Autopilot-Profilen in Ihre bestehenden Automatisierungs-Workflows, Deployment-Pipelines oder benutzerdefinierte Anwendungen ein.
4. Versionierung: Speichern Sie Ihre Konfigurationen (z.B. als JSON-Dateien) in einem Versionskontrollsystem (wie Git). Dies ermöglicht das Nachvollziehen von Änderungen, Rollbacks und eine kollaborative Arbeitsweise.
5. Flexibilität: Greifen Sie auf Einstellungen zu, die im Intune-Portal möglicherweise nicht direkt verfügbar sind oder eine komplexere Konfiguration erfordern.

Im Folgenden führen wir Sie Schritt für Schritt durch den Prozess, von der Authentifizierung bis zur Zuweisung eines Profils.

### Grundlagen: Was Sie wissen müssen (Voraussetzungen)

Bevor Sie mit der Graph API loslegen können, stellen Sie sicher, dass Sie die folgenden Punkte beachten:

* Grundkenntnisse in Azure AD und Microsoft Intune: Sie sollten wissen, wie Windows Autopilot funktioniert und was ein Deployment-Profil ist.
* Verständnis der Graph API: Grundlegende Kenntnisse über HTTP-Anfragen (GET, POST), JSON-Datenstrukturen und die Funktionsweise von APIs sind hilfreich.
* Berechtigungen: Ihr Benutzerkonto oder die von Ihnen verwendete App-Registrierung benötigt die entsprechenden Graph API-Berechtigungen. Für die Erstellung und Verwaltung von Autopilot-Profilen benötigen Sie in der Regel `DeviceManagementServiceConfig.ReadWrite.All`. Für die Zuweisung zu Gruppen benötigen Sie zusätzlich `Group.Read.All`.
* Tools:
* PowerShell: Empfohlen für Skripterstellung und Automatisierung. Installieren Sie das Modul `Microsoft.Graph`.
* Graph Explorer: Ein webbasiertes Tool von Microsoft zum Testen von Graph API-Aufrufen.
* Postman oder ähnlicher HTTP-Client: Für detaillierte API-Tests und Entwicklung.

### Schritt 1: Authentifizierung bei der Graph API

Der erste Schritt, um mit der Graph API zu interagieren, ist die Authentifizierung. Sie benötigen ein gültiges Zugriffstoken. Es gibt verschiedene Wege, dies zu tun:

1. Interaktive Anmeldung (für Tests und Skripte mit Benutzerkontext):
Die einfachste Methode für PowerShell-Skripte, die manuell ausgeführt werden, ist die interaktive Anmeldung.

„`powershell
Install-Module Microsoft.Graph -Scope CurrentUser # Bei Bedarf installieren
Connect-MgGraph -Scopes „DeviceManagementServiceConfig.ReadWrite.All”, „Group.Read.All”
„`
Nach Ausführung dieses Befehls öffnet sich ein Browserfenster, in dem Sie sich mit Ihrem Azure AD-Konto anmelden und den angeforderten Berechtigungen zustimmen müssen.

2. App-Registrierung (für Automatisierung ohne Benutzerinteraktion):
Für produktive Automatisierung, z.B. in CI/CD-Pipelines oder geplanten Aufgaben, sollten Sie eine Azure AD App-Registrierung verwenden.
* Erstellen Sie eine neue App-Registrierung in Azure AD.
* Geben Sie der App die erforderlichen „Anwendungsberechtigungen” (Application Permissions) für `DeviceManagementServiceConfig.ReadWrite.All` und `Group.Read.All` und erteilen Sie die Admin-Zustimmung.
* Erstellen Sie einen Client-Secret oder laden Sie ein Zertifikat hoch.
* Verwenden Sie dann die Anwendungs-ID (Client ID), Mandanten-ID (Tenant ID) und den Client-Secret/Zertifikat für die Authentifizierung.

Ein Beispiel für die Authentifizierung mit einem Client-Secret in PowerShell:

„`powershell
# Stellen Sie sicher, dass das Modul Microsoft.Graph.Authentication installiert ist
Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

$tenantId = „Ihre_Tenant_ID”
$clientId = „Ihre_Client_ID”
$clientSecret = „Ihr_Client_Secret” # Sicher speichern, z.B. in Azure Key Vault

$scopes = „https://graph.microsoft.com/.default” # „.default” bezieht sich auf alle konfigurierten Anwendungsberechtigungen

Connect-MgGraph -TenantId $tenantId -ClientId $clientId -ClientSecret $clientSecret -Scopes $scopes
„`
Für die Verwendung in Graph Explorer wählen Sie einfach die Option „Anmelden mit Microsoft”.

### Schritt 2: Das Autopilot Deployment Profil verstehen (JSON-Struktur)

Ein Autopilot Deployment Profil wird in der Graph API als eine Ressource vom Typ `windowsAutopilotDeploymentProfile` repräsentiert. Es ist wichtig, die JSON-Struktur und die relevanten Eigenschaften zu verstehen, bevor Sie ein Profil erstellen.

Die wichtigsten Eigenschaften, die Sie konfigurieren können, sind:

* `displayName`: Der Name des Profils im Intune-Portal.
* `description`: Eine optionale Beschreibung.
* `outOfBoxExperienceSetting`: Hier werden die Kern-Autopilot-Einstellungen definiert.
* `OobeUserType`: Definiert den Benutzertyp (Administrator, Standard).
* `OobeMode`: Der Autopilot-Modus (UserDriven, SelfDeploying, WhiteGlove).
* `hidePrivacySettings`: Blendet die Datenschutzeinstellungen aus.
* `hideEula`: Blendet die EULA (End User License Agreement) aus.
* `hideCortana`: Blendet Cortana während der OOBE aus.
* `hideSetupFromOOBE`: Verbirgt die Installationsoptionen für Benutzer während der Out-of-Box-Experience.
* `skipExpressSettings`: Überspringt Express-Einstellungen.
* `skipKeyboardSelectionPage`: Überspringt die Tastaturauswahl.
* `skipRegionPage`: Überspringt die Regionsauswahl.
* `keyboardSetting`: Konfiguriert die Tastatur (z.B. `keyboardLocale` für DE-DE).
* `enableWhiteGlove`: Aktiviert den White-Glove-Modus.
* `disableAccountSetupPage`: Blendet die Kontoeinrichtungsseite für Benutzer aus.
* `enrollmentStatusPageSettings`: Konfiguriert die Seite für den Registrierungsstatus (Enrollment Status Page, ESP).
* `allowLogCollectionOnInstallFailure`: Ermöglicht das Sammeln von Protokollen bei Installationsfehlern.
* `blockDeviceSetupOnInstallFailure`: Blockiert die Geräteeinrichtung bei Fehlern.
* `blockUserSetupOnInstallFailure`: Blockiert die Benutzer-Einrichtung bei Fehlern.
* `installProgressPageMode`: Konfiguriert, wann die ESP angezeigt wird (Default, Don’tShow, Show).
* `allowDeviceRestartOnInstallFailure`: Ermöglicht einen Geräteneustart bei Installationsfehlern.
* `deviceType`: Gibt an, ob das ESP für Geräte gilt (oder nicht).
* `installProgressPageTimeoutInMinutes`: Zeitlimit für die ESP.
* `customMessage`: Eine benutzerdefinierte Nachricht.
* `allowNewUserProfileCreation`: Ermöglicht die Erstellung neuer Benutzerprofile.

Ein Beispiel für eine grundlegende JSON-Struktur für ein Autopilot Deployment Profil (User-Driven, Standard-Benutzer, einige Einstellungen übersprungen):

„`json
{
„@odata.type”: „#microsoft.graph.windowsAutopilotDeploymentProfile”,
„displayName”: „Mein Automatisiertes Autopilot Profil”,
„description”: „Ein Profil, erstellt über die Graph API für Standardbenutzer.”,
„enrollmentStatusPageSettings”: {
„@odata.type”: „#microsoft.graph.windowsEnrollmentStatusPageSettings”,
„allowLogCollectionOnInstallFailure”: true,
„allowDeviceRestartOnInstallFailure”: true,
„installProgressPageMode”: „default”,
„blockDeviceSetupOnInstallFailure”: true,
„blockUserSetupOnInstallFailure”: false,
„installProgressPageTimeoutInMinutes”: 60,
„customMessage”: null
},
„outOfBoxExperienceSetting”: {
„@odata.type”: „#microsoft.graph.outOfBoxExperienceSetting”,
„OobeMode”: „userDriven”,
„OobeUserType”: „standard”,
„hidePrivacySettings”: true,
„hideEula”: true,
„hideCortana”: true,
„hideSetupFromOOBE”: true,
„skipExpressSettings”: true,
„skipKeyboardSelectionPage”: false,
„skipRegionPage”: false,
„keyboardSetting”: {
„@odata.type”: „#microsoft.graph.keyboardSetting”,
„keyboardLocale”: „de-DE”
},
„enableWhiteGlove”: false,
„disableAccountSetupPage”: false
},
„managementDeveloper”: „microsoft”,
„deviceType”: „windowsEnrolled”,
„hybridAzureADJoinSkipAppsCheck”: true,
„productType”: „none”,
„version”: 1
}
„`
**Tipp:** Wenn Sie sich unsicher sind, wie ein bestimmtes Setting im JSON-Format aussieht, erstellen Sie ein Profil mit den gewünschten Einstellungen im Intune-Portal und lesen Sie es dann mit der Graph API (GET-Anfrage auf `/deviceManagement/windowsAutopilotDeploymentProfiles`) aus. Dies gibt Ihnen die exakte JSON-Struktur zurück.

### Schritt 3: Erstellen des Deployment Profils (POST-Anfrage)

Um das Profil zu erstellen, senden Sie eine HTTP POST-Anfrage an den Endpunkt `/deviceManagement/windowsAutopilotDeploymentProfiles`. Der Anfragetext muss das JSON-Objekt enthalten, das Ihr Profil beschreibt.

„`powershell
# Nachdem Sie sich authentifiziert haben (Schritt 1)

$uri = „https://graph.microsoft.com/v1.0/deviceManagement/windowsAutopilotDeploymentProfiles”

# Erstellen Sie Ihr JSON-Objekt. Dies kann auch aus einer Datei geladen werden.
$profileJson = @{
„@odata.type” = „#microsoft.graph.windowsAutopilotDeploymentProfile”
displayName = „Automated Autopilot Profile – Marketing”
description = „Für Marketing-Geräte, User-Driven, Standard-Benutzer.”
enrollmentStatusPageSettings = @{
„@odata.type” = „#microsoft.graph.windowsEnrollmentStatusPageSettings”
allowLogCollectionOnInstallFailure = $true
allowDeviceRestartOnInstallFailure = $true
installProgressPageMode = „default”
blockDeviceSetupOnInstallFailure = $true
blockUserSetupOnInstallFailure = $false
installProgressPageTimeoutInMinutes = 60
customMessage = „Ihr Gerät wird konfiguriert. Bitte warten Sie.”
}
outOfBoxExperienceSetting = @{
„@odata.type” = „#microsoft.graph.outOfBoxExperienceSetting”
OobeMode = „userDriven”
OobeUserType = „standard”
hidePrivacySettings = $true
hideEula = $true
hideCortana = $true
hideSetupFromOOBE = $true
skipExpressSettings = $true
skipKeyboardSelectionPage = $false
skipRegionPage = $false
keyboardSetting = @{
„@odata.type” = „#microsoft.graph.keyboardSetting”
keyboardLocale = „de-DE”
}
enableWhiteGlove = $false
disableAccountSetupPage = $false
}
managementDeveloper = „microsoft”
deviceType = „windowsEnrolled”
hybridAzureADJoinSkipAppsCheck = $true
productType = „none”
version = 1
} | ConvertTo-Json # Wandelt das PowerShell Hashtable in ein JSON-String um

Write-Host „Sende Anfrage zum Erstellen des Autopilot Profils…”
try {
$newProfile = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $profileJson -ContentType „application/json”
Write-Host „Autopilot Profil erfolgreich erstellt: $($newProfile.displayName)”
Write-Host „Profil ID: $($newProfile.id)”
$profileId = $newProfile.id
}
catch {
Write-Error „Fehler beim Erstellen des Profils: $($_.Exception.Message)”
}
„`
Die Antwort auf diese Anfrage enthält das neu erstellte Profil, einschließlich seiner einzigartigen `id`. Speichern Sie diese `id`, da Sie sie für spätere Vorgänge, wie die Zuweisung des Profils, benötigen.

### Schritt 4: Das Profil Gruppen zuweisen (Optional, aber wichtig)

Ein Autopilot Deployment Profil ist erst dann wirksam, wenn es Geräten zugewiesen wird. Dies geschieht in der Regel durch die Zuweisung des Profils zu einer oder mehreren Azure AD-Gruppen, die die jeweiligen Autopilot-Geräte enthalten.

Sie benötigen die `id` des soeben erstellten Profils und die `id` der Azure AD-Gruppe, der Sie das Profil zuweisen möchten.

„`powershell
# Stellen Sie sicher, dass $profileId von Schritt 3 verfügbar ist
# Erhalten Sie die ID Ihrer Azure AD-Gruppe. Beispiel:
$groupName = „Autopilot – Marketing Devices”
try {
$group = Get-MgGroup -Filter „displayName eq ‘$groupName'”
if ($group) {
$groupId = $group.Id
Write-Host „Gefundene Gruppe ‘$groupName’ mit ID: $groupId”
} else {
Write-Error „Gruppe ‘$groupName’ nicht gefunden.”
exit
}
}
catch {
Write-Error „Fehler beim Abrufen der Gruppe: $($_.Exception.Message)”
exit
}

$assignmentUri = „https://graph.microsoft.com/v1.0/deviceManagement/windowsAutopilotDeploymentProfiles/$profileId/assignments”

$assignmentBody = @{
„@odata.type” = „#microsoft.graph.windowsAutopilotDeploymentProfileAssignment”
target = @{
„@odata.type” = „#microsoft.graph.groupAssignmentTarget”
groupId = $groupId
}
} | ConvertTo-Json

Write-Host „Weise Autopilot Profil ‘$($newProfile.displayName)’ der Gruppe ‘$groupName’ zu…”
try {
Invoke-MgGraphRequest -Method POST -Uri $assignmentUri -Body $assignmentBody -ContentType „application/json”
Write-Host „Profil erfolgreich der Gruppe zugewiesen.”
}
catch {
Write-Error „Fehler beim Zuweisen des Profils: $($_.Exception.Message)”
}
„`

### Schritt 5: Überprüfung und Fehlerbehebung

Nachdem Sie die Schritte ausgeführt haben, ist es wichtig zu überprüfen, ob alles wie erwartet funktioniert hat.

* Intune-Portal: Navigieren Sie im Microsoft Intune Admin Center zu „Geräte” > „Windows” > „Windows-Registrierung” > „Bereitstellungsprofile”. Ihr neu erstelltes Profil sollte dort sichtbar sein, zusammen mit der zugewiesenen Gruppe.
* Graph API (GET-Anfragen):
* Überprüfen Sie das Profil: `Invoke-MgGraphRequest -Method GET -Uri „https://graph.microsoft.com/v1.0/deviceManagement/windowsAutopilotDeploymentProfiles/$profileId”`
* Überprüfen Sie die Zuweisung: `Invoke-MgGraphRequest -Method GET -Uri „https://graph.microsoft.com/v1.0/deviceManagement/windowsAutopilotDeploymentProfiles/$profileId/assignments”`

Häufige Fehler und deren Behebung:

* 401 Unauthorized / 403 Forbidden: Dies deutet auf Authentifizierungs- oder Berechtigungsprobleme hin. Stellen Sie sicher, dass Ihr Token gültig ist und die App-Registrierung oder Ihr Benutzerkonto die erforderlichen Berechtigungen (`DeviceManagementServiceConfig.ReadWrite.All`, `Group.Read.All`) besitzt und Admin-Zustimmung erteilt wurde.
* 400 Bad Request: Dies tritt meistens auf, wenn das gesendete JSON-Objekt fehlerhaft ist (z.B. Tippfehler in Eigenschaftsnamen, falsche Datentypen). Überprüfen Sie das JSON sorgfältig gegen die Graph API-Dokumentation. Nutzen Sie den Graph Explorer, um Ihr JSON schrittweise aufzubauen und zu testen.
* Keine Reaktion / Timeout: Überprüfen Sie Ihre Internetverbindung und stellen Sie sicher, dass der Graph API-Dienst erreichbar ist.

### Best Practices und weiterführende Überlegungen

* Parameterisierung: Machen Sie Ihre Skripte flexibel, indem Sie Profilnamen, Beschreibungen und Gruppen-IDs als Parameter definieren, anstatt sie fest zu codieren.
* Idempotenz: Schreiben Sie Ihre Skripte so, dass sie wiederholt ausgeführt werden können, ohne unerwünschte Nebenwirkungen zu erzeugen. Prüfen Sie zum Beispiel vor dem Erstellen eines Profils, ob ein Profil mit dem gleichen `displayName` bereits existiert.
* Fehlerbehandlung und Protokollierung: Implementieren Sie robuste `try-catch`-Blöcke in Ihren PowerShell-Skripten, um Fehler abzufangen und aussagekräftige Meldungen auszugeben. Protokollieren Sie wichtige Schritte und Ergebnisse.
* Sichere Verwaltung von Secrets: Client-Secrets oder Zertifikate für App-Registrierungen sollten niemals direkt in Skripten gespeichert werden. Verwenden Sie sichere Lösungen wie Azure Key Vault, um diese zu speichern und abzurufen.
* Versionskontrolle: Speichern Sie Ihre PowerShell-Skripte und JSON-Templates in einem Versionskontrollsystem wie Git.
* Modulare Skripte: Teilen Sie komplexe Automatisierungsaufgaben in kleinere, wiederverwendbare Funktionen auf (z.B. eine Funktion zum Authentifizieren, eine zum Erstellen des Profils, eine zum Zuweisen).
* Hybrid Azure AD Join: Wenn Sie Hybrid Azure AD Join Autopilot-Profile erstellen, denken Sie daran, die entsprechenden Konfigurationen im JSON vorzunehmen und sicherzustellen, dass Ihr Doman-Join-Profil korrekt konfiguriert und zugewiesen ist.

### Fazit

Die Microsoft Graph API ist ein mächtiges Werkzeug für die Automatisierung und das Management Ihrer Microsoft Intune– und Windows Autopilot-Bereitstellungen. Durch die direkte Interaktion mit der API können Sie Prozesse beschleunigen, Fehler minimieren und eine beispiellose Skalierbarkeit erreichen. Was im Intune-Portal mühsam und zeitaufwendig sein kann, lässt sich mit ein paar Zeilen Code effizient erledigen.

Mit diesem Schritt-für-Schritt-Leitfaden sind Sie bestens gerüstet, um Ihre eigenen Autopilot Deployment Profile zu erstellen und Ihre Device Management-Strategie auf das nächste Level zu heben. Die Fähigkeit, diese Aufgaben zu skripten und zu automatisieren, ist ein entscheidender Vorteil für jede moderne IT-Organisation, die eine agile und effiziente Verwaltung ihrer Geräte anstrebt. Tauchen Sie ein in die Welt der API-gesteuerten Endpoint Management und entdecken Sie das volle Potenzial von Windows Autopilot.