Sektion 50: Microsoft Graph API Grundlagen: Authentifizierung und Endpunkte

Bis jetzt liefen deine Skripts auf den Geräten selbst: als Plattformskript in Sektion 47 oder als Remediation in Sektion 49. Ab hier drehst du die Richtung um. Mit der Microsoft Graph API steuerst du Intune von außen: Geräte auflisten, Berichte ziehen, Richtlinien anlegen. Laut Microsoft bietet die Graph-API für Intune dieselben Vorgänge, die du sonst im Admin Center ausführst.

Bevor du in den nächsten Sektionen Geräte abfragst und Richtlinien automatisiert anlegst, brauchst du ein solides Fundament: Wie ist eine Graph-Anfrage aufgebaut, welche Version nimmst du, und wie meldest du dich sicher an, interaktiv und ohne Benutzer?

Grundlagen: Was ist Microsoft Graph?

Ein Endpunkt für Microsoft 365

Microsoft Graph ist eine REST-API unter https://graph.microsoft.com. Über sie erreichst du Entra ID, Exchange, Teams und eben auch Intune. Laut Microsoft Learn bietet die Intune-API dieselben Vorgänge, die du auch im Portal ausführen kannst. Wichtig: Auch über die API setzt Intune eine gültige Intune-Lizenz im Mandanten voraus.

Für Intune sind vor allem diese Bereiche interessant:

• /deviceManagement/managedDevices für verwaltete Geräte
• /deviceManagement/deviceConfigurations und /deviceManagement/deviceCompliancePolicies für Konfiguration und Compliance
• /deviceAppManagement/mobileApps für Apps
• /users, /groups und /devices für Benutzer, Gruppen und Geräteobjekte aus Entra ID. Den Unterschied zwischen Entra-Geräteobjekt und Intune-Gerät kennst du aus Sektion 02.

v1.0 oder beta?

Graph gibt es in zwei Versionen. v1.0 enthält allgemein verfügbare Funktionen für den Produktivbetrieb. beta enthält neue Funktionen, die sich jederzeit ändern können. Microsoft schreibt in der Versionsrichtlinie klar: Beta-APIs in Produktionsanwendungen werden nicht unterstützt.

In der Praxis wirst du bei Intune trotzdem oft auf beta stoßen, weil viele neuere Intune-Funktionen zuerst oder nur dort verfügbar sind. Die Faustregel: Wenn es in v1.0 geht, nimm v1.0. Nutzt du beta, tu es bewusst, dokumentiere es im Skript und rechne damit, dass sich Eigenschaften ändern.

So ist eine Anfrage aufgebaut

Jede Anfrage folgt laut Microsoft Learn demselben Muster:

{HTTP-Methode} https://graph.microsoft.com/{Version}/{Ressource}?{Abfrageparameter}

GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=deviceName,complianceState

• Methode: GET liest, POST legt an, PATCH ändert, DELETE löscht.
• Ressource: der Pfad, zum Beispiel deviceManagement/managedDevices oder ein einzelnes Gerät mit seiner ID dahinter.
• Abfrageparameter: etwa $select für bestimmte Felder oder $filter zum Einschränken. Welche Parameter eine Ressource unterstützt, steht auf ihrer jeweiligen Referenzseite und in der Übersicht zu Abfrageparametern.
• Header: Ohne Authorization: Bearer {token} antwortet Graph nicht. Woher das Token kommt, klärt der nächste Abschnitt.

Authentifizierung: Wer fragt eigentlich?

Für jeden Aufruf brauchst du ein Zugriffstoken von der Microsoft Identity Platform. Laut Microsoft Learn gibt es zwei Arten von Zugriff:

Delegierter Zugriff

Eine App handelt im Namen eines angemeldeten Benutzers. Das ist der Fall, wenn du dich in PowerShell interaktiv anmeldest. Die Rechte ergeben sich aus der Schnittmenge: Die App braucht die delegierte Berechtigung, und der Benutzer muss die Aktion selbst ausführen dürfen. Hat dein Konto in Intune nur eine Leserolle, kannst du auch mit DeviceManagementManagedDevices.ReadWrite.All nichts ändern.

App-only-Zugriff

Die App handelt mit ihrer eigenen Identität, ohne Benutzer. Das brauchst du für geplante Aufgaben, etwa einen nächtlichen Bericht. Anwendungsberechtigungen erfordern laut Microsoft Learn immer die Zustimmung eines Administrators und gelten mandantenweit. Deshalb sind sie mächtiger und gehören besonders gut geschützt.

Berechtigungen: so wenig wie möglich

Jede Graph-Methode nennt auf ihrer Referenzseite die nötigen Berechtigungen, sortiert von der geringsten zur höchsten. Für das Auflisten verwalteter Geräte reicht zum Beispiel DeviceManagementManagedDevices.Read.All. Die wichtigsten Intune-Berechtigungen findest du in der Berechtigungsreferenz:

• DeviceManagementManagedDevices.Read.All / .ReadWrite.All: verwaltete Geräte
• DeviceManagementConfiguration.Read.All / .ReadWrite.All: Konfigurationsprofile und Compliance-Richtlinien
• DeviceManagementApps.Read.All / .ReadWrite.All: Apps und App-Schutz
• DeviceManagementServiceConfig.Read.All / .ReadWrite.All: Dienst-Einstellungen wie Enrollment und Autopilot

Fang immer mit Read.All an. ReadWrite.All vergibst du erst, wenn dein Skript wirklich schreiben muss.

Praxis 1: Interaktiv anmelden mit dem Graph PowerShell SDK

Der einfachste Einstieg ist das Microsoft Graph PowerShell SDK. Für Anmeldung und eigene Anfragen reicht das Modul Microsoft.Graph.Authentication, du musst nicht alle über 47 Untermodule installieren. Microsoft empfiehlt laut Installationsanleitung PowerShell 7, Windows PowerShell 5.1 funktioniert mit .NET Framework 4.7.2 oder neuer ebenfalls.

# Einmalig: nur das Authentifizierungsmodul des Graph-SDK installieren
Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Repository PSGallery

# Interaktiv anmelden, nur mit Leserechten auf verwaltete Geräte
Connect-MgGraph -Scopes "DeviceManagementManagedDevices.Read.All" -NoWelcome

# Prüfen, wer angemeldet ist und welche Berechtigungen die Sitzung hat
Get-MgContext | Select-Object Account, TenantId, AuthType, AppName
(Get-MgContext).Scopes

Beim ersten Anmelden fragt Entra ID nach der Zustimmung für die angeforderte Berechtigung. Get-MgContext zeigt dir danach, welches Konto angemeldet ist, ob die Sitzung delegiert oder app-only ist und welche Berechtigungen sie hat. Laut Microsoft Learn bleibt die Anmeldung zwischengespeichert, bis du Disconnect-MgGraph ausführst.

Tipp: Willst du eine Anfrage nur schnell ausprobieren, geht das auch im Browser mit dem Graph Explorer. Dort siehst du die Antwort und die benötigten Berechtigungen, ohne ein Skript zu schreiben.

Praxis 2: Deine erste Abfrage mit Paging

Mit Invoke-MgGraphRequest schickst du beliebige Graph-Anfragen. Das ist praktisch, weil du damit genau die REST-Aufrufe aus der Dokumentation nutzen kannst. Das folgende Skript liest alle verwalteten Geräte mit wenigen ausgewählten Feldern:

# Alle verwalteten Geräte lesen, nur die Felder, die du wirklich brauchst
$uri = 'https://graph.microsoft.com/v1.0/deviceManagement/managedDevices' +
       '?$select=deviceName,operatingSystem,osVersion,complianceState,lastSyncDateTime'

$geraete = [System.Collections.Generic.List[object]]::new()
while ($uri) {
    $antwort = Invoke-MgGraphRequest -Method GET -Uri $uri -OutputType PSObject
    foreach ($g in $antwort.value) { $geraete.Add($g) }
    # Gibt es weitere Seiten, steht die fertige URL in @odata.nextLink
    $uri = $antwort.'@odata.nextLink'
}

"{0} Geräte gefunden" -f $geraete.Count
$geraete | Sort-Object lastSyncDateTime |
    Format-Table deviceName, operatingSystem, osVersion, complianceState, lastSyncDateTime

• Paging: Graph liefert große Sammlungen seitenweise. Gibt es weitere Seiten, enthält die Antwort laut Microsoft Learn die Eigenschaft @odata.nextLink mit der fertigen URL der nächsten Seite. Du rufst sie auf, bis keine mehr kommt. Wer das vergisst, bekommt in großen Umgebungen nur einen Teil der Geräte.
• Einfache Anführungszeichen: $select steht in einfachen Anführungszeichen. In doppelten würde PowerShell $select als leere Variable ersetzen und die Anfrage wäre kaputt.
• -OutputType PSObject: Damit kommt die Antwort als normales PowerShell-Objekt zurück, mit dem Sort-Object und Format-Table direkt funktionieren.

Praxis 3: Ohne Benutzer anmelden, mit Zertifikat

Für Aufgaben, die nachts ohne dich laufen, brauchst du eine App-Registrierung in Entra ID. Microsoft beschreibt den Weg in der Anleitung zur App-only-Authentifizierung. Als Anmeldeinformation nimmst du ein Zertifikat statt eines geheimen Schlüssels: Der private Schlüssel verlässt den Rechner nicht und taucht in keinem Skript auf.

1. Zertifikat erstellen

# 1. Selbstsigniertes Zertifikat im Benutzerspeicher anlegen (privater Schlüssel bleibt auf dem Rechner)
$zert = New-SelfSignedCertificate -Subject "CN=Contoso Intune Reporting" `
    -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy NonExportable `
    -KeySpec Signature -KeyAlgorithm RSA -KeyLength 2048 -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddMonths(12)

# 2. Nur den öffentlichen Schlüssel exportieren, diese .cer lädst du in der App-Registrierung hoch
Export-Certificate -Cert $zert -FilePath "$env:USERPROFILE\Desktop\ContosoIntuneReporting.cer" | Out-Null
"Fingerabdruck: $($zert.Thumbprint)"

2. App registrieren und berechtigen

1. Im Microsoft Entra Admin Center unter App-Registrierungen eine Neue Registrierung anlegen, zum Beispiel „Contoso Intune Reporting“, nur für Konten in diesem Verzeichnis.
2. Unter Zertifikate & Geheimnisse die exportierte .cer-Datei hochladen.
3. Unter API-Berechtigungen → Berechtigung hinzufügen → Microsoft Graph → Anwendungsberechtigungen die Berechtigung DeviceManagementManagedDevices.Read.All auswählen.
4. Administratorzustimmung erteilen. Ohne diesen Schritt bekommt die App zwar ein Token, aber ohne Rechte.
5. Auf der Übersichtsseite die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Mandanten-ID) notieren.

3. Mit der App anmelden

$tenantId   = "00000000-0000-0000-0000-000000000000"   # Mandanten-ID (Verzeichnis-ID)
$clientId   = "11111111-1111-1111-1111-111111111111"   # Anwendungs-ID (Client-ID) der App-Registrierung
$thumbprint = "DEIN_ZERTIFIKAT_FINGERABDRUCK"

Connect-MgGraph -TenantId $tenantId -ClientId $clientId -CertificateThumbprint $thumbprint -NoWelcome

# Bei App-only steht hier AppOnly, und Scopes zeigt die Anwendungsberechtigungen mit Administratorzustimmung
Get-MgContext | Select-Object AppName, AuthType, Scopes

Läuft das Skript später als geplante Aufgabe unter einem Dienstkonto, muss das Zertifikat in dessen Zertifikatspeicher liegen. Laut Microsoft Learn sucht Connect-MgGraph in Cert:\CurrentUser\My und Cert:\LocalMachine\My. In Azure-Diensten wie Azure Automation geht es noch einfacher mit einer verwalteten Identität und Connect-MgGraph -Identity, ganz ohne Zertifikat oder Geheimnis.

Praxis 4: REST ohne SDK

Manchmal steht das SDK nicht zur Verfügung, oder du willst verstehen, was darunter passiert. Dann holst du das Token selbst über den Clientanmeldeinformationsflow und rufst Graph mit Invoke-RestMethod auf. Die Funktion unten folgt dem @odata.nextLink und reagiert auf Drosselung:

function Invoke-GraphGet {
    <#  Liest eine Graph-Sammlung komplett: folgt @odata.nextLink und wartet bei 429 die Retry-After-Zeit ab. #>
    param(
        [Parameter(Mandatory)][string]$Uri,
        [Parameter(Mandatory)][string]$Token,
        [int]$MaxVersuche = 5
    )
    $kopf     = @{ Authorization = "Bearer $Token" }
    $ergebnis = [System.Collections.Generic.List[object]]::new()

    while ($Uri) {
        for ($versuch = 1; ; $versuch++) {
            try {
                $antwort = Invoke-RestMethod -Method Get -Uri $Uri -Headers $kopf -ErrorAction Stop
                break
            }
            catch {
                $status = 0
                if ($_.Exception.Response) { $status = [int]$_.Exception.Response.StatusCode }
                if ($status -ne 429 -or $versuch -ge $MaxVersuche) { throw }

                $warten = 10
                $h = $_.Exception.Response.Headers
                if ($h -is [System.Net.WebHeaderCollection]) {             # Windows PowerShell 5.1
                    if ($h['Retry-After']) { $warten = [int]$h['Retry-After'] }
                }
                elseif ($h.RetryAfter -and $h.RetryAfter.Delta) {          # PowerShell 7
                    $warten = [int]$h.RetryAfter.Delta.TotalSeconds
                }
                Write-Warning "429 Too Many Requests, warte $warten Sekunden (Versuch $versuch von $MaxVersuche)"
                Start-Sleep -Seconds $warten
            }
        }
        foreach ($eintrag in $antwort.value) { $ergebnis.Add($eintrag) }
        $Uri = $antwort.'@odata.nextLink'
    }
    $ergebnis
}

# Token über den Clientanmeldeinformationsflow holen (geheimer Schlüssel kommt aus einer Umgebungsvariablen)
$tenantId = "00000000-0000-0000-0000-000000000000"
$clientId = "11111111-1111-1111-1111-111111111111"
$body = @{
    client_id     = $clientId
    scope         = "https://graph.microsoft.com/.default"
    client_secret = $env:CONTOSO_GRAPH_SECRET
    grant_type    = "client_credentials"
}
$token = (Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
    -Body $body -ContentType "application/x-www-form-urlencoded").access_token

$geraete = Invoke-GraphGet -Token $token `
    -Uri 'https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=deviceName,complianceState'
$geraete | Group-Object complianceState | Select-Object Name, Count

• scope = https://graph.microsoft.com/.default bedeutet: alle Anwendungsberechtigungen, denen ein Administrator für diese App zugestimmt hat.
• Drosselung: Schickst du zu viele Anfragen, antwortet Graph mit 429 Too Many Requests und einem Retry-After-Header. Laut Microsoft Learn ist es am schnellsten, genau diese Anzahl Sekunden zu warten und dann zu wiederholen. Sofortige Wiederholungen verlängern die Drosselung nur.
• Andere Fehler wie 401 oder 403 wirft die Funktion direkt weiter. Da hilft kein Warten.
• Der geheime Schlüssel kommt hier aus einer Umgebungsvariablen und steht nie im Skript. Für den Dauerbetrieb ist ein Zertifikat oder eine verwaltete Identität die bessere Wahl. Microsoft empfiehlt für Produktivanwendungen außerdem eine Authentifizierungsbibliothek wie MSAL statt eigener Tokenanfragen. Das SDK aus Praxis 1 bis 3 nutzt MSAL bereits.

Troubleshooting: Typische Fehler

401 Unauthorized

• Das Token fehlt, ist abgelaufen oder gehört zu einem anderen Mandanten. Zugriffstoken gelten nur begrenzt, das SDK erneuert sie automatisch, bei eigenen REST-Aufrufen musst du das selbst tun.
• Bei App-only: Zertifikat in der App-Registrierung abgelaufen oder ein anderes Zertifikat als das hochgeladene im Speicher.

403 Forbidden

• Die Berechtigung fehlt, oder die Administratorzustimmung wurde nicht erteilt. Nach jeder Änderung an den Berechtigungen muss die Zustimmung neu erteilt werden.
• Delegiert: Dein Konto hat in Intune nicht die nötige Rolle. Die App-Berechtigung allein reicht nicht.
• Prüfe mit (Get-MgContext).Scopes, welche Berechtigungen deine Sitzung wirklich hat.

400 Bad Request oder leere Felder

• $select oder $filter in doppelten Anführungszeichen ohne Escape-Zeichen.
• Eine Eigenschaft, die es nur in beta gibt, wird in v1.0 abgefragt.
• Nicht jede Ressource unterstützt jeden Abfrageparameter. Schau auf der Referenzseite der Methode nach.

Es fehlen Geräte

• Das Skript liest nur die erste Seite und ignoriert @odata.nextLink.
• Du suchst ein Gerät, das nur in Entra ID existiert, aber nicht in Intune verwaltet wird. Dann steht es unter /devices, nicht unter /deviceManagement/managedDevices.

Best Practices

• Immer v1.0, beta nur bewusst und mit Kommentar im Skript.
• Minimale Berechtigungen: Read.All zuerst, ReadWrite.All nur für Skripts, die schreiben.
• Eigene App-Registrierung pro Zweck, zum Beispiel getrennt für Berichte und für Änderungen. So bleibt nachvollziehbar, wer was darf.
• Zertifikat oder verwaltete Identität statt geheimem Schlüssel, und keine Geheimnisse im Skript.
• Ablaufdaten von Zertifikaten und Schlüsseln im Kalender eintragen, bevor die nächtliche Aufgabe still ausfällt.
• Nur die Felder mit $select holen, die du brauchst, Paging immer einbauen und auf 429 mit Retry-After reagieren.
• Schreibende Skripts zuerst in einer Testgruppe oder einem Testmandanten ausprobieren.

Fazit

Microsoft Graph ist der Schlüssel, um Intune zu automatisieren. Das Grundgerüst ist immer gleich: die richtige Version, die passende Berechtigung, ein sauberer Anmeldeweg und Code, der mit Paging und Drosselung umgehen kann. Wenn das steht, ist jede weitere Abfrage nur noch eine andere URL.

Zusammenfassend für deinen Workflow:

• Ressource und Methode in der Graph-Referenz suchen und die geringste nötige Berechtigung notieren.
• Interaktiv mit Connect-MgGraph testen, zum Beispiel erst im Graph Explorer.
• Für Automatisierung eine eigene App-Registrierung mit Zertifikat und Administratorzustimmung anlegen.
• Paging, Fehlerbehandlung und 429 einbauen, bevor das Skript auf den ganzen Mandanten losgeht.

In der nächsten Sektion nutzt du diese Grundlagen und fragst mit der Graph API gezielt Geräte und Benutzer ab. Einen Überblick über alle Sektionen findest du auf der Seite Intune-Kurs.

Quellen

• Microsoft Learn: Arbeiten mit Intune in Microsoft Graph
• Microsoft Learn: managedDevice auflisten
• Microsoft Learn: Versionsverwaltung und Support für Microsoft Graph
• Microsoft Learn: Verwenden der Microsoft Graph-API
• Microsoft Learn: Grundlagen zu Authentifizierung und Autorisierung
• Microsoft Learn: Microsoft Graph-Berechtigungsreferenz
• Microsoft Learn: Microsoft Graph PowerShell SDK installieren
• Microsoft Learn: Authentifizierungsbefehle des Graph PowerShell SDK
• Microsoft Learn: App-only-Authentifizierung mit dem Graph PowerShell SDK
• Microsoft Learn: Ohne Benutzer zugreifen (Clientanmeldeinformationen)
• Microsoft Learn: Paging der Microsoft Graph-Daten
• Microsoft Learn: Abfrageparameter
• Microsoft Learn: Drosselung in Microsoft Graph

↑ Zur Kursübersicht: Intune-Kurs (alle Sektionen)