Intune-Aufgaben mit PowerShell und Microsoft Graph automatisieren

Die meisten haben den Begriff Microsoft Graph API schon einmal gehört. Ms Graph ist eine Schnittstelle von MS für den Zugriff auf und die Steuerung einer Vielzahl von Microsoft-Cloud-Diensten. In diesem Blogbeitrag gehe ich genauer darauf ein, wie du Graph in Verbindung mit Intune nutzen kannst, welche Möglichkeiten du hast und wie das Ganze funktioniert. Außerdem gebe ich dir in diesem Blog Skriptbeispiele an die Hand, die du direkt verwenden kannst.

Verschiedene Möglichkeiten

Um Microsoft Graph API-Aufrufe über PowerShell auszuführen, kannst du die folgenden Optionen verwenden:

• Microsoft Graph REST API : Dies ist die einfachste Methode, bei der du Invoke-RestMethod oder Invoke-WebRequest verwenden kannst, um HTTP-Anfragen an den Microsoft Graph API-Endpunkt zu senden.

• Microsoft Graph SDK – Dies ist eine Client-Bibliothek, die das Aufrufen der Microsoft Graph API erleichtert, indem sie die REST API kapselt. Du kannst das Microsoft Graph SDK in PowerShell verwenden, indem du das Microsoft.Graph-Paket über Install-Module Microsoft.Graph installierst. Weitere Informationen findest du in dem GitHub-Repository.

So testest du einen Graph-Aufruf

Um Graph-Aufrufe zu testen, kannst du den Microsoft Graph Explorer verwenden, ein webbasiertes Tool zum Ausführen von Microsoft Graph API-Aufrufen und zum Testen der API, ohne Code schreiben zu müssen. Mit dem Graph Explorer kannst du mit der API experimentieren und verschiedene Abfragen und Vorgänge ausprobieren. Der Graph Explorer hilft dir außerdem dabei, PowerShell-Code auf Basis des SDK zu generieren. Den Graph Explorer findest du in dieser Anleitung.

So installierst du das Graph SDK

Bevor du das Graph SDK verwenden kannst, musst du das Graph Intune Module auf deinem System installieren. Du kannst diese Zeilen im Skript verwenden, um das Modul zu installieren, falls es noch nicht auf dem System vorhanden ist.

$moduleName = "Microsoft.Graph.Intune"
if (-not (Get-Module-ListAvailable -Name $moduleName)) {
    try {
        Install-Module-Name $moduleName -Scope CurrentUser -Repository PSGallery -Force
    }catch {
        Write-Error "Failed to install $moduleName"
        Exit
    }
}
Import-Module $moduleName

So authentifizierst du dich

PowerShell SDK

Wenn du das PowerShell SDK verwendest, ist die Authentifizierung wirklich einfach. Du musst zu Beginn deines Skripts den folgenden Befehl ausführen:

• Mit Benutzer-Authentifizierung:

Connect-MgGraph -Scopes "DeviceManagementManagedDevices.Read.All"

• Mit Service Principal:

# Certificate Thumbprint:
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT"

# Certificate name:
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateName "YOUR_CERT_SUBJECT"

# Select a certificate:
$Cert = Get-ChildItem Cert:LocalMachineMy$CertThumbprint
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -Certificate $Cert

Invoke-WebRequest

Mit der Methode Invoke-WebRequest musst du kein Modul auf dem System installieren. Hier findest du ein Beispiel, wie du dich mit einem Service Principal authentifizieren kannst:

• Mit Service Principal

function Get-AuthHeader{
    param (
        [parameter(Mandatory=$true)]$tenantId,
        [parameter(Mandatory=$true)]$clientId,
        [parameter(Mandatory=$true)]$clientSecret
       )

    $authBody=@{
        client_id=$clientId
        client_secret=$clientSecret
        scope="https://graph.microsoft.com/.default"
        grant_type="client_credentials"
    }

    $uri="https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
    $accessToken=Invoke-WebRequest -Uri $uri -ContentType "application/x-www-form-urlencoded" -Body $authBody -Method Post -ErrorAction Stop -UseBasicParsing
    $accessToken=$accessToken.content | ConvertFrom-Json

    $authHeader = @{
        'Content-Type'='application/json'
        'Authorization'="Bearer " + $accessToken.access_token
        'ExpiresOn'=$accessToken.expires_in
    }

    return $authHeader
}

# Add values for tenantId, clientId and clientSecret
$tenantId = ''
$clientId = ''
$clientSecret = ''

# Authentication
$global:authToken = Get-AuthHeader -tenantId $tenantId -clientId $clientId -clientSecret $clientSecret

So findest du die Graph-Endpunkt-URL

Auch hier haben wir zwei Möglichkeiten. Die eine ist, das integrierte Netzwerk-Trace-Tool deines Browsers zu verwenden, und die andere ist, Graph X-Ray von merill zu nutzen.

Graph X-Ray

Lass mich zeigen, wie das funktioniert. Beginnen wir mit Graph X-Ray. Als Erstes musst du die Chrome-/Edge-Erweiterung aus dem Store installieren. Sobald das erledigt ist, kannst du Intune öffnen und die Transaktion ausführen, für die du den Endpunkt suchst. Doch bevor du das tust, öffne die Entwicklertools des Browsers über F12 und wähle Graph X-Ray aus.

• Führe die Transaktion aus, und das PowerShell-Skript wird generiert. Du kannst den Befehl auch als Skript speichern:

All diese Aufrufe basieren auf dem Graph SDK.

Network Monitor

Dieser Ansatz ist sehr ähnlich. Auch hier musst du die Entwicklertools über F12 öffnen und zu Network navigieren. Simuliere auch hier die Aktion, für die du den Befehl suchst. Sobald das erledigt ist, findest du den Aufruf im Network-Trace.

Wenn du auf diese Anfrage klickst, findest du auch einige weitere Details. Das kann bei HTTP-POSTs wirklich hilfreich sein, um den benötigten Body zu sehen oder wenn du den Inhalt der Antwort einsehen möchtest.

Intune Graph-Dokumentation und Graph Explorer

Es gibt aber auch einen dritten Weg, nämlich die Intune Graph-Dokumentation zu verwenden. In dieser Dokumentation sind nahezu alle Aufrufe aufgelistet und erklärt. Auch von hier aus findest du alle notwendigen Informationen. Du kannst außerdem den Graph Explorer verwenden; dort gibt es einen großen Ressourcenkatalog, in dem du ebenfalls nahezu alle Intune Graph-Aufrufe findest.

So führst du das Skript aus

Es gibt verschiedene Möglichkeiten, ein PowerShell-Skript auszuführen. Am einfachsten ist es, das Skript lokal auf deinem PC über PowerShell ISE oder über Visual Studio Code auszuführen. Das hilft bei einmaliger Ausführung, z. B. beim Generieren eines Reports. Wenn du das Skript geplant ausführen möchtest, ist es am einfachsten, das Skript in einem Azure Automation Runbook auszuführen. Dazu habe ich viele Blogs mit Beispielen geschrieben.

Wo finde ich Beispielskripte?

Du findest unzählige Beispiele und GitHub-Repositories mit Intune Graph PowerShell-Skripten. Die beste Quelle ist das offizielle Microsoft Intune Graph-Repository auf GitHub. Außerdem lohnt sich ein Blick auf diese Repositories:

• https://github.com/scottbreenmsft/
• https://github.com/andrew-s-taylor
• https://github.com/jseerden
• https://github.com/FlorianSLZ
• https://github.com/ugurkocde
• https://github.com/iBowler1995/
• https://github.com/okieselbach
• https://github.com/j0eyv
• https://github.com/JayRHa

Dies ist nur ein Ausschnitt aus vielen großartigen Repositories.

Nachfolgend findest du zwei Beispiele, wie du alle Geräte ausgeben kannst:

Ohne SDK (Service Principal)

function Get-AuthHeader{
    param (
        [parameter(Mandatory=$true)]$tenantId,
        [parameter(Mandatory=$true)]$clientId,
        [parameter(Mandatory=$true)]$clientSecret
       )

    $authBody=@{
        client_id=$clientId
        client_secret=$clientSecret
        scope="https://graph.microsoft.com/.default"
        grant_type="client_credentials"
    }

    $uri="https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
    $accessToken=Invoke-WebRequest -Uri $uri -ContentType "application/x-www-form-urlencoded" -Body $authBody -Method Post -ErrorAction Stop -UseBasicParsing
    $accessToken=$accessToken.content | ConvertFrom-Json

    $authHeader = @{
        'Content-Type'='application/json'
        'Authorization'="Bearer " + $accessToken.access_token
        'ExpiresOn'=$accessToken.expires_in
    }

    return $authHeader
}

# Add values for tenantId, clientId and clientSecret
$tenantId = ''
$clientId = ''
$clientSecret = ''

# Authentication
$global:authToken = Get-AuthHeader -tenantId $tenantId -clientId $clientId -clientSecret $clientSecret


# Call the Intune Graph API to retrieve a list of devices
$devicesUrl = "https://graph.microsoft.com/v1.0/deviceManagement/managedDevices"
$devicesResponse = Invoke-RestMethod -Uri $devicesUrl -Headers $global:authToken
$devices = $devicesResponse.value

# Print the device names
foreach ($device in $devices) {
    Write-Host $device.deviceName
}

Mit SDK (Benutzer-Authentifizierung)

$moduleName = "Microsoft.Graph.Intune"
if (-not (Get-Module-ListAvailable -Name $moduleName)) {
    try {
        Install-Module-Name $moduleName -Scope CurrentUser -Repository PSGallery -Force
    }catch {
        Write-Error "Failed to install $moduleName"
        Exit
    }
}
Import-Module $moduleName

# Authenticate
Connect-MgGraph


# Get all managed devices
$devices = Get-MgDeviceManagementManagedDevice

# Print the device names
$devices | ForEach-Object {
    Write-Output $_.DisplayName
}

Graph 1.0 vs. Beta

Graph 1.0 ist die stabile Version von Microsoft Graph und für den Produktiveinsatz gedacht. Graph 1.0 hat ein stabiles Schema, was bedeutet, dass die APIs und Endpunkte vorhersehbar sind und über die Zeit stabil bleiben. Das macht es zu einer zuverlässigen Wahl für Entwickler, die produktive Anwendungen mit Microsoft Graph erstellen möchten.

Graph Beta hingegen ist die Vorabversion von Microsoft Graph und kann sich ändern. Sie bietet neue Features und Funktionen, die noch nicht für Graph 1.0 freigegeben wurden. Da es sich jedoch um eine Beta-Version handelt, wird sie für den Produktiveinsatz nicht empfohlen. Graph Beta kann Fehler und Breaking Changes enthalten, die bei darauf aufbauenden Anwendungen zu Kompatibilitätsproblemen führen können. Entwickler, die sich für Graph Beta entscheiden, sollten sich bewusst sein, dass sie ihren Code möglicherweise häufig aktualisieren müssen, wenn neue Änderungen vorgenommen werden.

Zusammengefasst ist der wesentliche Unterschied zwischen Microsoft Graph 1.0 und Graph Beta die Stabilität. Graph 1.0 ist eine stabile und zuverlässige Wahl für produktive Anwendungen, während Graph Beta neue Features und Funktionen bietet, die sich ändern können und möglicherweise nicht für den Produktiveinsatz geeignet sind. Entwickler sollten ihre Anforderungen und Anwendungsfälle bei der Wahl zwischen den beiden Versionen von Microsoft Graph sorgfältig abwägen.