Sektion 47: PowerShell-Skripts in Intune: Bereitstellung und Ausführung

In Sektion 46 haben wir uns die Intune Management Extension (IME) angesehen, den Agenten, der auf Windows-Geräten Win32-Apps, Skripts und Remediations ausführt. Jetzt nutzen wir ihn gezielt: mit PowerShell-Skripts, die Sie direkt aus Intune auf Ihre Geräte verteilen. Im Admin Center heißen sie heute Plattformskripts.

Plattformskripts sind schnell angelegt. Die meisten Probleme entstehen danach: Das Skript läuft im falschen Kontext, schreibt in den falschen Registry-Zweig, läuft nur ein einziges Mal oder meldet Erfolg, obwohl nichts passiert ist. In dieser Sektion gehen wir die Einstellungen der Reihe nach durch, sehen uns an, wann die IME ein Skript ausführt, und bauen ein Beispielskript, das sauber protokolliert und Fehler ehrlich an Intune zurückmeldet.

Grundlagen: Wofür Plattformskripts gedacht sind

Plattformskript, Remediation oder Win32-App?

Intune bietet drei Wege, PowerShell auf ein Gerät zu bringen. Die Wahl hängt davon ab, wie oft der Code laufen soll und ob Intune den Zustand prüfen muss:

• Plattformskript: läuft einmal pro Gerät bzw. Benutzer und danach nur wieder, wenn Sie das Skript oder die Richtlinie ändern. Ideal für einmalige Konfigurationen, etwa einen Registry-Wert, einen Ordner oder eine Grundeinstellung nach der Bereitstellung.
• Remediation: besteht aus Erkennungs- und Korrekturskript und läuft nach Zeitplan immer wieder. Das ist der richtige Weg, wenn ein Zustand dauerhaft sichergestellt werden soll. Mehr dazu im Beitrag Intune Remediations und in der nächsten Sektion.
• Win32-App: sinnvoll, wenn Sie eine Erkennungsregel, Abhängigkeiten, Neustartverhalten oder eine Deinstallation brauchen. Ein Skript lässt sich dafür als .intunewin verpacken, siehe Sektion 33: Detection Methods und Sektion 38: PSADT.

Voraussetzungen

• Die IME wird automatisch installiert, sobald dem Benutzer oder Gerät ein PowerShell-Skript zugewiesen ist. Sie müssen nichts vorbereiten.
• Das Gerät ist mit Microsoft Entra ID verbunden. Laut Microsoft erhalten Geräte, die nur registriert sind (Workplace Join), keine Skripts. An anderer Stelle derselben Seite heißt es, dass bei solchen Geräten nur Gerätegruppen funktionieren und Benutzerzuweisungen ignoriert werden. Planen Sie Plattformskripts deshalb für Entra-joined- und Hybrid-joined-Geräte.
• Auf Surface Hubs und unter Windows im S-Modus laufen keine Skripts.
• Die Systemuhr des Geräts muss stimmen. Ist sie um Monate oder Jahre falsch, schlagen Skripts fehl, bis die Zeit korrigiert ist.
• Ein Benutzer muss nicht angemeldet sein, damit ein Skript läuft.

Skript anlegen und zuweisen

Der Assistent im Admin Center

1. Im Intune Admin Center Geräte > Skripts und Korrekturen > Plattformskripts > Hinzufügen > Windows 10 und höher wählen.
2. Unter Grundlagen einen Namen und eine Beschreibung eintragen. Die Beschreibung ist optional, hilft aber später enorm, wenn Sie zum Beispiel Zweck, Version und Ansprechpartner hineinschreiben.
3. Unter Skripteinstellungen die Datei hochladen und die drei Schalter setzen (siehe unten). Das Skript muss kleiner als 200 KB sein.
4. Optional Bereichstags setzen.
5. Unter Zuweisungen die Entra-Gruppen auswählen, dann Überprüfen + hinzufügen. Mit dem Speichern wird das Skript an die Gruppen verteilt.

Die drei Schalter, auf die es ankommt

• Dieses Skript mit den Anmeldeinformationen des angemeldeten Benutzers ausführen: Ja (Standard) startet das Skript im Kontext des Benutzers. Nein startet es im Systemkontext, also als SYSTEM. Alles, was HKLM, Programme, Dienste oder Systemordner betrifft, gehört in den Systemkontext. Benutzerkontext brauchen Sie für HKCU und das Benutzerprofil. Laut Microsoft laufen Skripts im Benutzerkontext mit Administratorrechten, wenn der Benutzer lokaler Administrator ist.
• Skriptsignaturprüfung erzwingen: Bei Ja muss das Skript von einem vertrauenswürdigen Herausgeber signiert sein. Bei Nein ist keine Signatur nötig. Mit Ja ohne passende Signatur läuft das Skript nicht. Die Hintergründe zu Signaturen und Ausführungsrichtlinien stehen in about_Execution_Policies.
• Skript im 64-Bit-PowerShell-Host ausführen: Standard ist Nein. Dann läuft das Skript im 32-Bit-Host, auch auf 64-Bit-Windows. Bei Ja läuft es auf 64-Bit-Geräten im 64-Bit-Host.

Der 64-Bit-Schalter ist der häufigste Stolperstein. Ein 32-Bit-Prozess sieht auf 64-Bit-Windows eine umgeleitete Welt: Zugriffe auf C:\Windows\System32 landen in C:\Windows\SysWOW64, und Schreibzugriffe auf HKLM:\SOFTWARE landen im Zweig WOW6432Node. Microsoft beschreibt das im Artikel Dateisystemumleitung. Ihr Skript meldet dann Erfolg, aber der Wert steht nicht dort, wo Sie ihn erwarten.

Achtung bei bestehenden Skripts: Stellen Sie den Schalter bei einem bereits verteilten Skript nachträglich von Nein auf Ja um, wird das Skript laut Microsoft im 64-Bit-Host nur geöffnet, aber nicht erneut ausgeführt. Wer den Host wechseln will, lädt das Skript am besten als neues Plattformskript hoch.

Benutzer- oder Gerätegruppen?

Skripts lassen sich an Entra-Gerätegruppen und Entra-Benutzergruppen zuweisen. Ein Skript, das einem Gerät zugewiesen ist, läuft laut Microsoft für jeden neuen Benutzer, der sich an diesem Gerät anmeldet. Für reine Gerätekonfiguration im Systemkontext sind Gerätegruppen meist die klarere Wahl, weil das Ergebnis dann nicht davon abhängt, wer sich anmeldet.

Ausführung: Was auf dem Gerät passiert

Einmal ausführen, dreimal wiederholen, 30 Minuten Zeit

• Die IME prüft nach jedem Neustart und bei ihren regulären Check-ins auf neue oder geänderte Skripts. Wie der Check-in-Zyklus funktioniert, steht in Sektion 46.
• Ein Skript läuft genau einmal. Es läuft erst wieder, wenn Sie das Skript oder die Richtlinie ändern. Plattformskripts laufen also nicht bei jeder Anmeldung.
• Schlägt ein Skript fehl, versucht die IME es bei den nächsten drei Check-ins erneut. Danach gibt sie auf, solange Sie nichts am Skript ändern.
• Nach 30 Minuten bricht die IME ein Skript mit Timeout ab. Lange Downloads oder Installationen gehören deshalb eher in eine Win32-App.

Microsoft zeigt den Wiederholungsablauf an einem Beispiel: Ein Skript schlägt um 8 Uhr fehl, wird um 9, 10 und 11 Uhr bei den folgenden Check-ins erneut versucht und ab 12 Uhr nicht mehr gestartet. Wenn Sie also ein fehlerhaftes Skript korrigieren wollen, laden Sie eine geänderte Version hoch. Erst dadurch läuft es wieder.

Reihenfolge und Enrollment Status Page

Beim Start verarbeitet die IME zuerst die PowerShell-Skripts und beginnt danach im selben Ablauf mit den Win32-Apps. Microsoft hat die Dokumentation hier präzisiert: Diese Reihenfolge garantiert nicht, dass ein Skript fertig ist, bevor eine Win32-App startet. Andere Check-ins oder Benachrichtigungen können die App-Verarbeitung unabhängig anstoßen. Braucht eine App eine Vorbereitung, packen Sie diese in die Win32-App selbst, etwa als Teil des Installationsskripts oder als Abhängigkeit.

Auch die Registrierungsstatusseite (ESP) wartet nicht auf Plattformskripts. Skripts können während der ESP laufen, werden aber nicht als blockierende Workloads verfolgt. Dazu kommt ein bekanntes Problem: Skripts im Benutzerkontext laufen während der ESP unter Umständen gar nicht. Microsoft empfiehlt als Workaround, solche Skripts im Systemkontext auszuführen.

Wer das Skript tatsächlich startet

Ausgeführt wird das Skript vom AgentExecutor, einem Teil der IME. In Microsofts Beispiel ruft er die Windows PowerShell aus C:\Windows\SysWOW64\WindowsPowerShell\v1.0 auf, also Windows PowerShell 5.1 und nicht PowerShell 7. Schreiben Sie Plattformskripts deshalb so, dass sie unter Windows PowerShell 5.1 laufen. Was der AgentExecutor tut, protokolliert er in AgentExecutor.log. Die Ausgabe- und Fehlerdateien der einzelnen Läufe räumt die IME nach der Ausführung wieder weg.

Praxis: Skripts bauen, testen und prüfen

1. Kontext und Architektur sichtbar machen

Bevor Sie ein echtes Skript verteilen, lohnt sich ein kleines Diagnoseskript. Es schreibt auf, unter welchem Konto, mit welchen Rechten und in welcher Architektur es läuft. Weisen Sie es einmal im Benutzerkontext und einmal im Systemkontext einer Testgruppe zu, jeweils mit und ohne 64-Bit-Option:

# Zeigt, in welchem Kontext und welcher Architektur das Skript läuft
$id        = [Security.Principal.WindowsIdentity]::GetCurrent()
$principal = [Security.Principal.WindowsPrincipal]::new($id)

$info = [pscustomobject]@{
    Zeitpunkt    = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
    Konto        = $id.Name
    IstSystem    = $id.IsSystem
    IstAdmin     = $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
    Prozess64Bit = [Environment]::Is64BitProcess
    OS64Bit      = [Environment]::Is64BitOperatingSystem
    PSVersion    = $PSVersionTable.PSVersion.ToString()
}

$info | Format-List | Out-File -FilePath (Join-Path $env:TEMP 'kc-kontext.txt') -Encoding utf8 -Append
$info

IsSystem ist True, wenn das Skript als SYSTEM läuft. Prozess64Bit zeigt, ob der 64-Bit-Host aktiv ist. Die Datei landet in $env:TEMP: im Systemkontext ist das in der Regel C:\Windows\Temp, im Benutzerkontext der Temp-Ordner im Profil des Benutzers. So sehen Sie auf einen Blick, ob Ihre Einstellungen im Admin Center wirklich das bewirken, was Sie erwarten.

2. Ein Plattformskript mit Logging und ehrlichem Fehlerstatus

Das folgende Skript setzt einen Registry-Wert unter HKLM. Wichtiger als der Wert ist das Gerüst drumherum, das Sie für eigene Skripts übernehmen können:

# Set-FirmenInfo.ps1 - Plattformskript für Intune
# Einstellungen: Systemkontext (angemeldete Anmeldeinformationen = Nein), 64-Bit-Host = Ja
$logDir = Join-Path $env:ProgramData 'Kaffeeundcode\Logs'
New-Item -Path $logDir -ItemType Directory -Force | Out-Null
Start-Transcript -Path (Join-Path $logDir 'Set-FirmenInfo.log') -Append | Out-Null

$exitCode = 0
try {
    if ([Environment]::Is64BitOperatingSystem -and -not [Environment]::Is64BitProcess) {
        throw 'Skript läuft im 32-Bit-Host. In Intune "Skript im 64-Bit-PowerShell-Host ausführen" auf Ja setzen.'
    }

    $key = 'HKLM:\SOFTWARE\Kaffeeundcode'
    if (-not (Test-Path $key)) {
        New-Item -Path $key -Force -ErrorAction Stop | Out-Null
    }
    New-ItemProperty -Path $key -Name 'Abteilung' -Value 'IT' -PropertyType String -Force -ErrorAction Stop | Out-Null
    Write-Output "OK: $key\Abteilung = IT"
}
catch {
    Write-Error -Message "Fehler: $($_.Exception.Message)" -ErrorAction Continue
    $exitCode = 1
}
finally {
    Stop-Transcript | Out-Null
}
exit $exitCode

• Start-Transcript schreibt alle Ausgaben in eine eigene Logdatei unter C:\ProgramData\Kaffeeundcode\Logs. Die bleibt erhalten, auch wenn die IME ihre temporären Dateien aufräumt.
• Die 64-Bit-Prüfung am Anfang verhindert, dass der Wert still in WOW6432Node landet. Läuft das Skript versehentlich im 32-Bit-Host, bricht es mit einer klaren Meldung ab.
• -ErrorAction Stop macht aus Fehlern der Cmdlets abbrechende Fehler, die im catch-Block landen.
• Im catch-Block schreibt Write-Error die Meldung in den Fehlerstream. Microsoft nutzt genau dieses Mittel in seinem Testskript, das in Intune immer als Fehler gemeldet wird. Zusätzlich endet das Skript mit Exitcode 1, was beim lokalen Testen und in eigenen Logs hilft.
• finally sorgt dafür, dass das Transcript in jedem Fall sauber geschlossen wird.
• Das Skript ist idempotent: Es kann mehrfach laufen, ohne etwas kaputtzumachen. Das ist wichtig, weil die IME es nach einer Änderung oder bei neuen Benutzern erneut ausführt.

3. Lokal als SYSTEM testen

Testen Sie ein Skript vor dem Upload so, wie Intune es ausführt. Microsoft empfiehlt dafür PsExec aus den Sysinternals-Tools. Damit starten Sie eine PowerShell im Systemkonto:

# Eingabeaufforderung als Administrator, im Ordner mit PsExec:
psexec.exe -i -s powershell.exe

# In der neuen PowerShell (läuft als SYSTEM):
whoami

# 64-Bit-Host (Standard-PowerShell auf 64-Bit-Windows)
powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Test\Set-FirmenInfo.ps1

# 32-Bit-Host, so wie Intune ohne die 64-Bit-Option startet
C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Test\Set-FirmenInfo.ps1

-i startet die Sitzung interaktiv, -s im Systemkonto. whoami sollte nt authority\system zurückgeben. Der zweite Aufruf über SysWOW64 simuliert den 32-Bit-Host. Testen Sie Ihr Skript am besten in beiden Varianten, dann fallen Umleitungsprobleme vor dem Rollout auf.

4. AgentExecutor.log auswerten

Läuft ein Skript in Intune nicht wie erwartet, ist AgentExecutor.log die erste Anlaufstelle. Für einen schnellen Blick reicht PowerShell:

$log = 'C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\AgentExecutor.log'

# Letzte Einträge ansehen
Get-Content -Path $log -Tail 40

# Nach Fehlern oder einem Skriptnamen suchen
Select-String -Path $log -Pattern 'error|fail|Set-FirmenInfo' |
    Select-Object -Last 20 LineNumber, Line

Select-String arbeitet mit regulären Ausdrücken und ignoriert Groß- und Kleinschreibung. Mit Select-Object -Last 20 sehen Sie nur die neuesten Treffer. Für längere Analysen empfiehlt Microsoft CMTrace.exe.

Status überwachen

Im Admin Center öffnen Sie unter Plattformskripts das Skript und wählen Überwachen. Dort gibt es die Berichte Gerätestatus und Benutzerstatus. Laut Microsoft nutzt der CSV-Export des Gerätestatus inzwischen die Intune-Export-API, die Spaltennamen entsprechen deshalb dem API-Schema. Das ist wichtig, wenn Sie Exporte automatisiert weiterverarbeiten.

Troubleshooting: Typische Probleme

Das Skript läuft gar nicht

• Prüfen Sie, ob die IME installiert ist: Unter %ProgramFiles(x86)%\Microsoft Intune Management Extension muss sie vorhanden sein, und der Dienst IntuneManagementExtension sollte laufen. Steht der Dienst auf Manuell, startet er nach einem Neustart unter Umständen nicht wieder.
• Ist das Gerät mit Entra ID verbunden und nicht nur registriert?
• Hat das Skript schon dreimal fehlgeschlagen? Dann läuft es erst nach einer Änderung wieder.
• Bei aktivierter Signaturprüfung: Ist das Skript gültig von einem vertrauenswürdigen Herausgeber signiert?
• Stimmt die Systemuhr des Geräts?

Erfolg gemeldet, aber nichts passiert

• Häufigste Ursache ist der 32-Bit-Host: Der Registry-Wert steht unter WOW6432Node, die Datei in SysWOW64. Prüfen Sie dort zuerst.
• Falscher Kontext: Ein Skript im Benutzerkontext schreibt nach HKCU des angemeldeten Benutzers, nicht in die Systemkonfiguration.
• Das Skript fängt Fehler ab, ohne sie zu melden. Ohne Eintrag im Fehlerstream sieht Intune keinen Fehler.
• Laut Microsoft kann auch eine Antivirenlösung den AgentExecutor in eine Sandbox stecken. Microsoft schlägt dafür dieses Testskript vor, das in Intune immer als Fehler erscheinen muss:

Write-Error -Message "Forced Fail" -Category OperationStopped
mkdir "c:\temp"
echo "Forced Fail" | out-file c:\temp\Fail.txt

Meldet Intune hier Erfolg, sehen Sie in AgentExecutor.log nach, ob die Fehlerausgabe ankommt.

Best Practices

• Keine Kennwörter, Schlüssel oder personenbezogenen Daten in Skripts. Microsoft weist ausdrücklich darauf hin, auch keine personenbezogenen Daten mit Skripts von Geräten einzusammeln.
• Für Gerätekonfiguration den Systemkontext und den 64-Bit-Host verwenden. Den Benutzerkontext nur für Benutzereinstellungen.
• Skripts idempotent schreiben, mit eigenem Log unter ProgramData und klarer Fehlermeldung über den Fehlerstream.
• Vor dem Rollout mit PsExec als SYSTEM testen, in 32 und 64 Bit, dann mit einer kleinen Pilotgruppe starten.
• Version und Zweck in die Beschreibung schreiben. Bei einer Korrektur eine neue Version hochladen, damit das Skript erneut läuft.
• Was regelmäßig geprüft werden soll, gehört in eine Remediation. Was eine Erkennung, Abhängigkeit oder Deinstallation braucht, in eine Win32-App.

Fazit

Plattformskripts sind das einfachste Werkzeug, um PowerShell per Intune auf Windows-Geräte zu bringen. Sie laufen einmal, werden höchstens dreimal wiederholt und haben 30 Minuten Zeit. Die meisten Fehler kommen nicht vom Code, sondern von den Einstellungen: falscher Kontext, 32-Bit-Host oder ein Skript, das Fehler verschluckt. Wer das Gerüst aus Logging, 64-Bit-Prüfung und Fehlerstream nutzt und vorher als SYSTEM testet, spart sich viele Runden im Log.

Zusammenfassend für Ihren Workflow:

• Kontext und 64-Bit-Option bewusst wählen, für Systemeinstellungen: Systemkontext und 64 Bit.
• Skript lokal mit PsExec als SYSTEM testen.
• An eine Pilotgruppe zuweisen und unter Überwachen den Gerätestatus prüfen.
• Bei Problemen AgentExecutor.log und das eigene Log auswerten.

In der nächsten Sektion geht es um Proactive Remediations: Skripts, die einen Zustand regelmäßig prüfen und bei Bedarf selbst korrigieren. Einen Überblick über alle Sektionen finden Sie auf der Seite Intune-Kurs.

Quellen

• Microsoft Learn: Verwenden von PowerShell-Skripts auf Windows-Geräten in Intune
• Microsoft Learn (englisch, aktuellere Fassung): Use PowerShell scripts on Windows devices in Intune
• Microsoft Learn: Grundlegendes zur Microsoft Intune Management Extension
• Microsoft Learn: PowerShell script execution during ESP
• Microsoft Learn: Verwenden von Korrekturmaßnahmen (Remediations)
• Microsoft Learn: Dateisystemumleitung (File System Redirector)
• Microsoft Learn: PsExec (Sysinternals)
• Microsoft Learn: about_Execution_Policies

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