Zum Inhalt
Kaffeeundcode

Sektion 52: Graph API: Richtlinien automatisiert erstellen und zuweisen

Compliance-Richtlinie per Skript anlegen, Gruppen sicher zuweisen und Settings-Catalog-Profile als JSON-Vorlage nutzen: Graph schreibend im Einsatz.

Intune-Kurs · Teil 52 von 90 · Block G: Scripting & Automatisierung

Was du in dieser Sektion lernst

  • Compliance-Richtlinien über die v1.0-API anlegen, inklusive Pflichtfeld für Aktionen
  • Zuweisungen an Gruppen setzen, ohne bestehende Zuweisungen zu verlieren
  • Settings-Catalog-Richtlinien als JSON-Vorlage exportieren und neu anlegen
  • Schreibende Skripte mit -WhatIf und Dublettenprüfung absichern

ca. 11 Min. Lesezeit · Alle Sektionen im Überblick

In Sektion 51 hast du Graph nur gelesen: Geräte, Benutzer, Berichte. Jetzt schreibst du. Du legst eine Compliance-Richtlinie per Skript an, weist sie einer Gruppe zu und baust aus einer bestehenden Settings-Catalog-Richtlinie eine wiederverwendbare Vorlage.

Das lohnt sich vor allem dann, wenn du dieselbe Konfiguration öfter brauchst: für einen zweiten Mandanten, einen neuen Standort oder eine Testkopie, bevor du in Produktion etwas änderst. Im Portal klickst du jede Einstellung neu an. Ein Skript macht es jedes Mal gleich.

Grundlagen: Was sich beim Schreiben ändert

  • Berechtigungen: Zum Anlegen und Zuweisen brauchst du DeviceManagementConfiguration.ReadWrite.All. Das nennt Microsoft Learn sowohl beim Erstellen einer Compliance-Richtlinie als auch bei der assign-Aktion. Für das Nachschlagen der Gruppe reicht Group.Read.All. Alles Weitere steht in der Berechtigungsreferenz.
  • v1.0 und beta: Klassische Compliance-Richtlinien gibt es in v1.0. Settings-Catalog-Richtlinien laufen über /deviceManagement/configurationPolicies und sind laut Microsoft Learn nur in beta dokumentiert. Microsoft unterstützt die Intune-beta-APIs, weist aber darauf hin, dass sie sich öfter ändern.
  • Wirkung: Jeder POST verändert deinen Mandanten sofort. Teste deshalb in einer Testumgebung oder mit einer Pilotgruppe, nie direkt mit „Alle Geräte“.

Die Anmeldung kennst du aus Sektion 50. Neu sind die Schreibrechte und eine kleine Funktion, die dir die Objekt-ID einer Gruppe über ihren Namen liefert. Gruppen lassen sich laut Microsoft Learn standardmäßig nach displayName filtern.

CodeKlick markiert alles · Strg+C kopiert
# Diese Sektion schreibt in Intune: ReadWrite für Richtlinien, Read für Gruppen
Connect-MgGraph -Scopes 'DeviceManagementConfiguration.ReadWrite.All',
                        'Group.Read.All' -NoWelcome

# Hilfsfunktion: Objekt-ID einer Entra-Gruppe über den Anzeigenamen
function Get-GruppenId {
    param([Parameter(Mandatory)][string]$Name)
    $filter = [uri]::EscapeDataString("displayName eq '$Name'")
    $treffer = @((Invoke-MgGraphRequest -Method GET -OutputType PSObject `
        -Uri "https://graph.microsoft.com/v1.0/groups?`$filter=$filter&`$select=id,displayName").value)
    if ($treffer.Count -ne 1) { throw "Gruppe '$Name' nicht eindeutig gefunden ($($treffer.Count) Treffer)." }
    $treffer[0].id
}

# Hilfsfunktion aus Sektion 51: holt alle Seiten einer Abfrage
function Get-GraphAll {
    param([Parameter(Mandatory)][string]$Uri)
    $ergebnis = [System.Collections.Generic.List[object]]::new()
    while ($Uri) {
        $antwort = Invoke-MgGraphRequest -Method GET -Uri $Uri -OutputType PSObject
        foreach ($eintrag in $antwort.value) { $ergebnis.Add($eintrag) }
        $Uri = $antwort.'@odata.nextLink'
    }
    $ergebnis
}

Get-GruppenId bricht bewusst ab, wenn es keinen oder mehrere Treffer gibt. Lieber ein klarer Fehler als eine Richtlinie, die an der falschen Gruppe hängt.

Praxis 1: Compliance-Richtlinie per Graph anlegen

Als Beispiel legst du eine Windows-Compliance-Richtlinie an, die BitLocker, Secure Boot und eine Mindestversion verlangt. Was diese Regeln fachlich bedeuten, hast du in Sektion 19 gesehen. Das Skript prüft vorher, ob es eine Richtlinie mit diesem Namen schon gibt. So kannst du es mehrfach laufen lassen, ohne Dubletten zu erzeugen.

CodeKlick markiert alles · Strg+C kopiert
$basis = 'https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicies'
$name  = 'WIN - Compliance - Basis'

# Gibt es die Richtlinie schon? Dann nichts doppelt anlegen.
$vorhanden = @(Get-GraphAll -Uri "$basis`?`$select=id,displayName" |
    Where-Object displayName -eq $name)

if ($vorhanden.Count -gt 0) {
    Write-Host "Richtlinie '$name' existiert bereits: $($vorhanden[0].id)"
    $richtlinieId = $vorhanden[0].id
}
else {
    $richtlinie = @{
        '@odata.type'          = '#microsoft.graph.windows10CompliancePolicy'
        displayName            = $name
        description            = 'Per Graph erstellt: BitLocker, Secure Boot, Mindestversion'
        bitLockerEnabled       = $true
        secureBootEnabled      = $true
        osMinimumVersion       = '10.0.22631'    # Beispielwert, an deine Umgebung anpassen
        # Pflicht beim Anlegen: genau eine block-Aktion
        scheduledActionsForRule = @(
            @{
                ruleName = 'PasswordRequired'
                scheduledActionConfigurations = @(
                    @{ actionType = 'block'; gracePeriodHours = 24 }
                )
            }
        )
    }
    $json = $richtlinie | ConvertTo-Json -Depth 10
    $neu = Invoke-MgGraphRequest -Method POST -Uri $basis -Body $json `
        -ContentType 'application/json' -OutputType PSObject
    Write-Host "Angelegt: $($neu.displayName) ($($neu.id))"
    $richtlinieId = $neu.id
}
  • @odata.type legt fest, welche Plattform du anlegst. Hier ist es #microsoft.graph.windows10CompliancePolicy, die verfügbaren Eigenschaften stehen in der Create-Dokumentation.
  • scheduledActionsForRule ist laut Ressourcenbeschreibung beim Anlegen Pflicht. Ohne diesen Block lehnt Graph die Anfrage ab.
  • ruleName steht laut Microsoft Learn immer auf PasswordRequired, weil Aktionen pro Richtlinie und nicht pro Regel gelten. Der Name ist also kein Hinweis auf eine Kennwortregel.
  • Genau eine block-Aktion muss enthalten sein. gracePeriodHours legt fest, wie viele Stunden ein Gerät Zeit hat, bevor es als nicht konform gilt, erlaubt sind laut Microsoft Learn 0 bis 8760.
  • ConvertTo-Json -Depth 10 ist wichtig. Mit der Standardtiefe schneidet PowerShell verschachtelte Objekte ab, und Graph bekommt unvollständiges JSON.

Praxis 2: Zuweisen, ohne etwas zu verlieren

Zugewiesen wird über die Aktion assign. Du schickst eine Liste von Zuweisungen, jede mit einem Ziel. Für eine Gruppe ist das ein groupAssignmentTarget mit der groupId, für Ausnahmen gibt es das exclusionGroupAssignmentTarget.

Wichtig: Behandle assign so, als würde es die komplette Liste setzen. Die Funktion unten liest deshalb erst die bestehenden Zuweisungen, hängt die neue Gruppe an und schickt dann alles zusammen. So fliegt keine Zuweisung raus, die ein Kollege im Portal gesetzt hat.

CodeKlick markiert alles · Strg+C kopiert
function Add-RichtlinienZuweisung {
    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory)][string]$RichtlinieUri,   # z. B. .../deviceCompliancePolicies/<id>
        [Parameter(Mandatory)][string]$GruppenId,
        [string]$ZuweisungsTyp                          # nur bei Compliance nötig
    )
    # 1. Bestehende Zuweisungen lesen, damit keine verloren geht
    $alt = @((Invoke-MgGraphRequest -Method GET -Uri "$RichtlinieUri/assignments" -OutputType PSObject).value)
    if ($alt.target.groupId -contains $GruppenId) {
        Write-Host "Gruppe ist bereits zugewiesen, nichts zu tun."
        return
    }
    # 2. Komplette Liste aufbauen: alte Ziele plus neue Gruppe
    $ziele = @($alt | ForEach-Object { $_.target }) + @(@{
        '@odata.type' = '#microsoft.graph.groupAssignmentTarget'
        groupId       = $GruppenId
    })
    $zuweisungen = foreach ($ziel in $ziele) {
        $eintrag = @{ target = $ziel }
        if ($ZuweisungsTyp) { $eintrag['@odata.type'] = $ZuweisungsTyp }
        $eintrag
    }
    $json = @{ assignments = @($zuweisungen) } | ConvertTo-Json -Depth 10
    # 3. Erst nach Bestätigung bzw. ohne -WhatIf wirklich zuweisen
    if ($PSCmdlet.ShouldProcess($RichtlinieUri, "Zuweisung an Gruppe $GruppenId")) {
        Invoke-MgGraphRequest -Method POST -Uri "$RichtlinieUri/assign" -Body $json -ContentType 'application/json' | Out-Null
        Write-Host "Zugewiesen: $(@($zuweisungen).Count) Ziel(e) insgesamt."
    }
}

$gruppe = Get-GruppenId -Name 'GRP-Intune-Pilot-Geraete'
Add-RichtlinienZuweisung -GruppenId $gruppe `
    -RichtlinieUri "https://graph.microsoft.com/v1.0/deviceManagement/deviceCompliancePolicies/$richtlinieId" `
    -ZuweisungsTyp '#microsoft.graph.deviceCompliancePolicyAssignment' -WhatIf
  • SupportsShouldProcess schaltet -WhatIf und -Confirm für deine Funktion frei. Mit -WhatIf siehst du nur, was passieren würde. Wie das im Detail funktioniert, erklärt der Deep Dive zu ShouldProcess.
  • Der Aufruf am Ende läuft absichtlich mit -WhatIf. Erst wenn die Ausgabe passt, nimmst du den Schalter weg.
  • ZuweisungsTyp setzt bei Compliance-Richtlinien den Typ deviceCompliancePolicyAssignment, so wie im Beispiel von Microsoft Learn. Für Settings-Catalog-Richtlinien lässt du ihn weg.
  • Ist die Gruppe schon zugewiesen, macht die Funktion nichts. Auch das macht das Skript wiederholbar.

Filter für Zuweisungen, die du aus Sektion 45 kennst, hängen ebenfalls am Ziel. Wenn du sie brauchst, liest du am besten eine im Portal erstellte Zuweisung über /assignments aus und übernimmst die Felder genau so.

Praxis 3: Settings Catalog als Vorlage exportieren

Beim Settings Catalog aus Sektion 16 besteht jede Einstellung aus einer settingDefinitionId und einem passenden Wert, oft mehrfach verschachtelt. Diese IDs von Hand zu schreiben ist fehleranfällig. Der praxistaugliche Weg: Du baust die Richtlinie einmal sauber im Portal und liest sie per Graph als Vorlage aus.

CodeKlick markiert alles · Strg+C kopiert
# Settings-Catalog-Richtlinie samt Einstellungen als JSON-Vorlage sichern (nur beta)
$beta   = 'https://graph.microsoft.com/beta/deviceManagement/configurationPolicies'
$quelle = @(Get-GraphAll -Uri "$beta`?`$select=id,name" |
    Where-Object name -eq 'WIN - Edge - Basis')
if ($quelle.Count -ne 1) { throw "Vorlage nicht eindeutig gefunden ($($quelle.Count) Treffer)." }

$richtlinie = Invoke-MgGraphRequest -Method GET -Uri "$beta/$($quelle[0].id)" -OutputType PSObject
$settings   = @(Get-GraphAll -Uri "$beta/$($quelle[0].id)/settings")

$vorlage = [ordered]@{
    name              = $richtlinie.name
    description       = $richtlinie.description
    platforms         = $richtlinie.platforms
    technologies      = $richtlinie.technologies
    templateReference = $richtlinie.templateReference
    settings          = @($settings | ForEach-Object { @{ settingInstance = $_.settingInstance } })
}
$vorlage | ConvertTo-Json -Depth 30 | Set-Content -Path '.\vorlage-edge-basis.json' -Encoding utf8
Write-Host "Gesichert: $($settings.Count) Einstellung(en)"
  • /settings ist laut Ressourcenbeschreibung die Beziehung mit allen Einstellungen der Richtlinie. Die Grunddaten wie platforms und technologies kommen aus dem Richtlinienobjekt selbst.
  • Nur settingInstance wird gesichert. IDs und Zeitstempel braucht die neue Richtlinie nicht, die vergibt Intune selbst.
  • -Depth 30 reicht auch für tief verschachtelte Einstellungen mit children.
  • Die JSON-Datei kannst du in Git ablegen. Damit siehst du später genau, welche Einstellung sich wann geändert hat.

Praxis 4: Aus der Vorlage eine neue Richtlinie anlegen

Jetzt drehst du den Weg um. Das Skript liest die JSON-Datei, legt daraus über Create deviceManagementConfigurationPolicy eine neue Richtlinie an und weist sie mit der Funktion aus Praxis 2 zu.

CodeKlick markiert alles · Strg+C kopiert
# Vorlage als neue Settings-Catalog-Richtlinie anlegen
$beta    = 'https://graph.microsoft.com/beta/deviceManagement/configurationPolicies'
$vorlage = Get-Content -Path '.\vorlage-edge-basis.json' -Raw | ConvertFrom-Json
$neuName = 'WIN - Edge - Basis (Standort Ulm)'

$vorhanden = @(Get-GraphAll -Uri "$beta`?`$select=id,name" |
    Where-Object name -eq $neuName)
if ($vorhanden.Count -gt 0) { throw "'$neuName' existiert bereits ($($vorhanden[0].id))." }

$body = [ordered]@{
    name         = $neuName
    description  = "Aus Vorlage '$($vorlage.name)' erstellt"
    platforms    = $vorlage.platforms
    technologies = $vorlage.technologies
    settings     = @($vorlage.settings | ForEach-Object {
        @{
            '@odata.type'   = '#microsoft.graph.deviceManagementConfigurationSetting'
            settingInstance = $_.settingInstance
        }
    })
}
# Nur mitschicken, wenn die Vorlage auf einer Vorlage (Template) basiert
if ($vorlage.templateReference.templateId) {
    $body.templateReference = @{ templateId = $vorlage.templateReference.templateId }
}

$json = $body | ConvertTo-Json -Depth 30
$neu  = Invoke-MgGraphRequest -Method POST -Uri $beta -Body $json -ContentType 'application/json' -OutputType PSObject
Write-Host "Angelegt: $($neu.name) ($($neu.id)) mit $($body.settings.Count) Einstellung(en)"

Add-RichtlinienZuweisung -RichtlinieUri "$beta/$($neu.id)" `
    -GruppenId (Get-GruppenId -Name 'GRP-Intune-Pilot-Geraete')
  • Dublettenprüfung zuerst: Gibt es den Namen schon, bricht das Skript ab, statt eine zweite Richtlinie mit gleichem Namen zu erzeugen.
  • templateReference schickst du nur mit, wenn die Vorlage wirklich auf einem Template basiert, etwa bei Endpoint-Security-Richtlinien. Für normale Settings-Catalog-Richtlinien ist die templateId leer.
  • Kein -WhatIf beim Import: Hier wird wirklich angelegt und zugewiesen. Lass das Skript deshalb zuerst gegen eine Testgruppe laufen.

Abkürzung für 1:1-Kopien: createCopy

Willst du eine Richtlinie im selben Mandanten nur duplizieren, etwa um eine Änderung zu testen, gibt es laut Microsoft Learn die Aktion createCopy. Du übergibst nur Namen und Beschreibung. Die Kopie ist zunächst nicht zugewiesen, die Zuweisung setzt du wie oben.

CodeKlick markiert alles · Strg+C kopiert
# Schnellster Weg für eine 1:1-Kopie: die Aktion createCopy (beta)
$beta = 'https://graph.microsoft.com/beta/deviceManagement/configurationPolicies'
$body = @{
    displayName = 'WIN - Edge - Basis (Test)'
    description = 'Kopie zum Testen neuer Einstellungen'
} | ConvertTo-Json

$kopie = Invoke-MgGraphRequest -Method POST -Uri "$beta/$($quelle[0].id)/createCopy" `
    -Body $body -ContentType 'application/json' -OutputType PSObject
# Laut Dokumentation steckt die neue Richtlinie in "value"
$kopieId = if ($kopie.value) { $kopie.value.id } else { $kopie.id }
Write-Host "Kopie angelegt: $kopieId"

Troubleshooting: Typische Fehler

400 Bad Request beim Anlegen

  • Bei Compliance-Richtlinien fehlt scheduledActionsForRule oder es steht nicht genau eine block-Aktion darin.
  • Das JSON ist abgeschnitten, weil -Depth fehlt. Gib $json vor dem POST einmal aus und prüfe es.
  • Ein Wert passt nicht zur settingDefinitionId. Exportiere die Einstellung aus einer funktionierenden Richtlinie, statt sie selbst zusammenzubauen.

403 Forbidden

  • Du bist nur mit Read-Rechten angemeldet. Prüfe mit (Get-MgContext).Scopes, ob DeviceManagementConfiguration.ReadWrite.All dabei ist.
  • Bei App-Anmeldung fehlt die Administratorzustimmung für die Anwendungsberechtigung.

Zuweisung ist nach dem Skript weg

  • Du hast assign nur mit der neuen Gruppe aufgerufen. Lies vorher immer /assignments aus und schick die vollständige Liste.

Eigenschaft fehlt oder heißt plötzlich anders

  • Bei beta-Endpunkten kann sich das Schema ändern. Prüfe nach Fehlern zuerst die aktuelle Seite auf Microsoft Learn und exportiere die Vorlage neu.

Best Practices

  • Schreibrechte nur für Skripte, die wirklich schreiben. Berichte aus Sektion 51 bleiben bei Read.
  • Jedes Skript prüft vorher, ob das Objekt schon existiert. Dann kannst du es gefahrlos wiederholen.
  • Schreibende Funktionen mit SupportsShouldProcess bauen und den ersten Lauf immer mit -WhatIf machen.
  • Zuweisungen immer lesen, ergänzen und komplett zurückschreiben.
  • Neue Richtlinien zuerst einer Pilotgruppe zuweisen und erst nach dem Test erweitern.
  • Vorlagen als JSON versionieren, so hast du gleichzeitig ein Backup deiner Konfiguration.
  • Einheitliche Namen wie „WIN – Bereich – Zweck“ verwenden. Das macht die Suche per Name im Skript zuverlässig.

Fazit

Mit POST und assign wird Graph vom Berichtswerkzeug zum Werkzeug für Konfiguration. Der Trick liegt weniger im Anlegen selbst als in der Absicherung drumherum: Dubletten vermeiden, bestehende Zuweisungen behalten und zuerst mit -WhatIf testen.

Zusammenfassend für deinen Workflow:

  • Mit DeviceManagementConfiguration.ReadWrite.All und Group.Read.All anmelden.
  • Compliance-Richtlinien in v1.0 anlegen, immer mit genau einer block-Aktion in scheduledActionsForRule.
  • Settings-Catalog-Richtlinien im Portal bauen, als JSON exportieren und daraus neue anlegen.
  • Zuweisungen erst lesen, dann ergänzen und mit -WhatIf prüfen, bevor du sie wirklich setzt.

In der nächsten Sektion schaust du dir das Intune PowerShell SDK als Alternative zur direkten API an: Wann dir fertige Cmdlets die Arbeit erleichtern und wann der direkte Aufruf wie hier die bessere Wahl ist. Einen Überblick über alle Sektionen findest du auf der Seite Intune-Kurs.

Quellen


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