Entra ID mit PowerShell DSC konfigurieren
Streng nach Vorschrift
Veröffentlicht in Ausgabe 01/2024 - PRAXIS
Der vorbildlich agiert und die Konfiguration mehrerer Tenants, Test, Integration und Produktion im Einklang hält oder regelmäßig die wichtigsten sicherheitsrelevanten Einstellungen in der Microsoft-Cloud prüfen und dokumentieren muss, hat sich mit Sicherheit schon Wege und Skripte zurechtgelegt, um die Arbeit leichter zu gestalten. Eines der interessanten Werkzeuge, die mehr und mehr Einzug in Unternehmen halten, ist Microsoft 365 Desired State Configuration (DSC).
Die Idee des Projekts: Das Rahmenwerk der PowerShell DSC fit für die Microsoft Cloud machen und Funktionen wie Dokumentation, Änderungserkennung, Rückkorrektur von Änderungen und Konfigurations-Clones anzubieten. Wer beispielsweise PowerShell DSC für Windows Server schon kennt, soll sich mit M365DSC schnell wieder zurechtfinden. Das Projekt umfasst viele der Microsoft-365-Produkte – in diesem Workshop beschäftigen wir uns mit Beispielen aus Entra ID.
Erste Konfiguration
Für Testzwecke und zum Erstellen der ersten Konfigurationsprototypen können Sie die M365DSC-PowerShell auf einem Testrechner oder der eigenen Maschine mit Zugriff auf einen Test-Tenant installieren – das Kommando dazu in der PowerShell lautet
Der vorbildlich agiert und die Konfiguration mehrerer Tenants, Test, Integration und Produktion im Einklang hält oder regelmäßig die wichtigsten sicherheitsrelevanten Einstellungen in der Microsoft-Cloud prüfen und dokumentieren muss, hat sich mit Sicherheit schon Wege und Skripte zurechtgelegt, um die Arbeit leichter zu gestalten. Eines der interessanten Werkzeuge, die mehr und mehr Einzug in Unternehmen halten, ist Microsoft 365 Desired State Configuration (DSC).
Die Idee des Projekts: Das Rahmenwerk der PowerShell DSC fit für die Microsoft Cloud machen und Funktionen wie Dokumentation, Änderungserkennung, Rückkorrektur von Änderungen und Konfigurations-Clones anzubieten. Wer beispielsweise PowerShell DSC für Windows Server schon kennt, soll sich mit M365DSC schnell wieder zurechtfinden. Das Projekt umfasst viele der Microsoft-365-Produkte – in diesem Workshop beschäftigen wir uns mit Beispielen aus Entra ID.
Erste Konfiguration
Für Testzwecke und zum Erstellen der ersten Konfigurationsprototypen können Sie die M365DSC-PowerShell auf einem Testrechner oder der eigenen Maschine mit Zugriff auf einen Test-Tenant installieren – das Kommando dazu in der PowerShell lautet
Install-Module -Name Microsoft365DSC
Die Installation geht üblicherweise still vonstatten und endet nach ein paar Minuten wortlos. Es schadet nicht, nach der Installation des M365DSC die Abhängigkeiten zu aktualisieren:
Update-M365DSCDependencies
Ist das Setup beendet, laden Sie das Modul mit
Import-Module Microsoft365DSC. Sollten Sie bisher noch keine externen Skripte auf dem System erlaubt haben, quittiert die PowerShell mit einer Fehlermeldung, dass Sie zunächst die Execu-tionPolicy mit Set-ExecutionPolicy anpassen müssen. Anschließend starten Sie den ersten Versuch und inspizieren die Konfiguration von "TenantDetails" – dazu nutzen Sie:Export-M365DSCConfiguration -Components @('AADTenantDetails') -Path C:\temp\DSCExport\ -ConfigurationName "TenantDetails" -FileName TenantDetails.PS1
Das System fragt daraufhin in einer Maske nach Anmeldedaten. Das Kommando ist so aufgebaut, dass es bestimmte Konfigurationen, im Beispiel die "TenantDetails", "AADGroup" oder "AADConditionalAccessPolicy", also Konfiguration und Inhalt des Tenants, abholt und lokal speichert. Das Cmdlet nimmt Kontakt mit dem benannten Tenant auf und legt die Daten in den Exportordner "C:\temp\DSCExport" ab, den Sie frei auswählen können. Konfigurationsname und Dateiname sind ebenfalls frei bestimmbar. Abgespeichert werden die Settings im PowerShell-DSC-Format, das aber gerade in komplexen Umgebungen unhandlich zu erforschen ist. Ein zweites Kommando überführt die Rohdaten in einen lesbaren HTML-Report:
New-M365DSCReportFromConfiguration -Type HTML -ConfigurationPath C:\temp\DSCExport\TenantDetails.PS1 -OutputPath C:\temp\DSCExport\TenantDetails.HTML
Als Alternative zu "-Type HTML" können Sie "-Type Excel" nutzen, wonach das Cmdlet die Informationen dann in Tabellenform im Excel-Format als XLSX-Datei ablegt.
Die verfügbaren "Components", die im Moment via M365DSC unterstützt werden, finden Sie in [1] aufgeführt. Die Export-Webseite liefert nicht nur eine Übersicht über alle M365-Produkte und Details, die Sie mit Configuration-as-Code verwalten können, sondern auch einen Generator, der die Konfiguration direkt exportieren kann.
Desired State Configuration
Das Microsoft-365-DSC-Modul ist, wie der Name bereits verrät, Teil des Desired-State-Configuration-Frameworks für die PowerShell. Das Framework ist seit Jahren als eine in die PowerShell eingebettete Beschreibungssprache für Systemkonfigurationen bekannt. Die DSC-Konfiguration enthält einen Wunschzustand, der dann bei einem Zielsystem überprüft wird. Aus diesem Check ergeht dann ein Resultat oder falls erforderlich eine Korrektur des Zielsystems, um den Wunschzustand hervorzurufen. Damit lassen sich bestehende wie auch neue Systeme, VMs, Serverrollen, AD-Objekte oder – wie in diesem Workshop – Microsoft-365-Tenants geradeziehen oder initial konfigurieren.
Die Beschreibung der Konfiguration lässt sich dabei einmalig per händischer Ausführung starten, nächtlich via Skript oder gar über eine Integration in Azure Dev-Ops verwalten und pflegen.
Ein Punkt der Umgewöhnung sei jedoch erwähnt: Die PowerShell kann die Wunschkonfiguration nur mit den richtigen Berechtigungen am Zielsystem überprüfen und ändern. Für Server im eigenen Rechenzentrum oder VMs in Azure nutzen Sie hierzu meist Windows-AD-Accounts. Für M365-Tenants müssen Sie sich zwischen der manuellen Ausführung mit einem Benutzerkonto oder einem Service Principal (SP) entscheiden. Anmeldungen von Service Principals lassen sich entweder via Appsecret, was ein langes, komplexes Passwort darstellt, oder Zertifikatsanmeldung schützen.
Service Principal anlegen
Für den regelmäßigen Betrieb ohne Benutzerkontext empfiehlt sich das Anlegen eines Service Principals, das über die erforderlichen Rechte zur Sammlung und Korrektur der Konfigurationen via Microsoft Graph API verfügt. Die Konfiguration hierfür findet in Entra ID statt. Sie ist dabei dreigeteilt: Zunächst erstellen Sie ein Schlüsselpaar für das Service Principal, anschließend das Service Principal selbst mit seiner Konfiguration und zum Schluss folgt die Bestätigung der Graph-Berechtigungen durch einen Admin via "Consent".
Im Beispiel legen wir ein Service Principal mit Zertifikatsanmeldung an, da dies den besten Kompromiss aus Komfort und sicherer Anmeldung darstellt. Noch sicherer ginge es mit einer Managed Identity (MI), die das Zertifikat dann aus einem KeyVault herausholt – MIs finden aber noch nicht mit allen M365-Funktionen und M365DSC Unterstützung. Für das Cert-Credential können Sie Ihre hauseigene PKI bemühen, die dann privaten und öffentlichen Schlüssel mit Zertifikaten für das Service Principal zur Verfügung stellen kann. Für Testzwecke tut es auch das kleine PowerShell-Skript aus Listing 1, das ein sechs Monate gültiges Cert-Credential erstellt und im Zertifikatsstore sowie in "C:\temp" ablegt. Aus dem PFX mit dem privaten Schlüssel müssen Sie zunächst eine CER-Datei mit öffentlichem Schlüssel erstellen, den Sie nach Azure hochladen.
In Entra ID legen Sie in der Sektion "Applications / App registrations" eine neue Anwendung an. Mit "+ new registration" müssen Sie zunächst nur einen eindeutigen Namen angeben. Ist die Anwendung angelegt, laden Sie in "Certificates & secrets" das Public-Key-Zertifikat im Tab "Certificates" hoch. Auf der Übersichtsseite sehen Sie die Application-ID – diese sollten Sie sogleich in die Zwischenablage kopieren. In "API permissions" konfigurieren Sie dann die Berechtigungen, mit denen das Service Principal die Daten abrufen soll. Für einen ersten Test mit dem nachfolgenden Kommando sollte die Berechtigung "Organization.Read.All" für "Microsoft Graph" im Application-Kontext ausreichen:
Export-M365DSCConfiguration -Components @('AADTenantDetails') -ApplicationId <AppID> -TenantId contoso.onmicrosoft.com -Path C:\temp\DSCExport\ -ConfigurationName "TenantDetails" -FileName TenantDetails.PS1
Listing 1: Cert-Credential erstellen
$today = Get-Date
$endDate = $today.AddMonths(6)
$notAfter = $today.AddMonths(6)
$pass = "Pa$$ToProt3ctThePFX!"
$thumbprint = (New-SelfSignedCertificate -CertStoreLocation cert:\Currentuser\My -DnsName powershell.contoso.com -KeyExportPolicy Exportable -Provider "MicrosoftEnhancedRSA and AES Cryptographic Provider" -NotAfter $notAfter).Thumbprint
$pwd = ConvertTo-SecureString -String $pass -Force -AsPlainText
Export-PfxCertificate -cert "cert:\currentuser\my\$thumbprint" -FilePath c:\temp\SPCert.pfx -Password $pwd
Mit den richtigen Berechtigungen arbeiten
Wer mit dem Microsoft Graph bereits zu tun hatte, kennt Freud und Leid der Berechtigungsvergabe: Selbst mit hohen administrativen Berechtigungen lassen sich nicht zwingend mit jeder beliebigen Anwendung kritische Daten abrufen. Nutzen Sie beispielsweise den Graph Explorer [2], um Ihre Graph-Abfragen im Browser auszuprobieren und zu schärfen, können Sie zwar als globaler Admin agieren, müssen jedoch sowohl den Graph Explorer per Consent für den Tenant freigeben als auch die Detailberechtigungen erlauben, die Sie gerade benötigen – relativ zur gewünschten Graph-Abfrage.
Die richtigen Berechtigungen müssen Sie auch für M365DSC konfigurieren, damit Einzelabfragen oder ein automatisiertes Skript die passenden Daten aus Graph abholen kann. Die Berechtigungen wie etwa "Policy.Read.All" für Conditional Access weisen Sie dann Ihrem neu erstellten Service Principal zu. Welche Berechtigungen erforderlich sind, sagt Ihnen M365DSC, wenn Sie die gewünschte Komponente angeben:
permissions = Get-M365DSCCompiledPermissionList -ResourceNameList @('AADGroup')
permissions["Read"] | % {$_["Permission"]}
Name Value
---- -----
Name Organization.Read.All
Type Application
Name Group.Read.All
Type Delegated
Name ReportSettings.Read.All
Type Delegated
Name Group.Read.All
Type Application
Name ReportSettings.Read.All
Type Application
Zunächst laden Sie die Berechtigungsdefinition für die Konfiguration für AAD-Gruppen-Reports herunter und speichern diese nach "permissions". Die Informationen sind in vier Hashtables hinterlegt: "RequiredRoles", "Read", "RequiredRoleGroups", "Update". Abhängig davon, welche Berechtigungen (Lesen oder Schreiben) Sie konfigurieren wollen, müssen Sie die Hashtable aufdröseln – das macht das zweite Kommando im Beispiel für "Read"-Zugriffe. Der Typ der jeweiligen Berechtigung weist aus, wie Sie Entra ID und den Consent konfigurieren müssen.
Wenn Sie M365DSC ohne Admin-Benutzer, sondern als Service Principal mit Zertifikatsanmeldung nutzen, können Sie alle Berechtigungen als "application permission" freigeben. Einige Konfigurationen wie etwa der Conditional Access profitieren zusätzlich von den Berechtigungen "Group.Read.All" und "User.Read.All" – die mögen zwar nicht explizit für das Lesen der CA-Konfiguration notwendig sein, wenn Sie aber "Include" und "Exclude" in der CA-Policy auf Benutzer- oder Gruppenebene einsetzen, kann M365DSC diese auch auflösen. Für bestimmte M365-Produkte wie OneDrive oder das Security- und Compliance-Center benötigt PowerShell DSC zusätzliche Rollenzuweisungen, die das Projektteam unter [3] beschreibt.
Komplette Konfiguration überprüfen
Starten Sie das Cmdlet ohne Angabe von "Components", versucht es, die gesamte Konfiguration der M365-Cloud, soweit die Berechtigungen reichen, abzuholen und zu dokumentieren. Wenn Sie allerdings nicht an allen Cloudprodukten interessiert sind, sondern nur einzelne Werkzeuge dokumentieren wollen, sollten Sie dem Cmdlet mit dem Parameter "Workloads" auf die Sprünge helfen:
Export-M365DSCConfiguration -ApplicationId <AppID> -TenantId contoso.onmicrosoft.com -Path C:\temp\DSCExport\ -ConfigurationName "AllSettings" -FileName AllSettings.PS1 -Workloads @('AAD')
Wollen Sie Exchange und Intune ebenfalls in den Report einbeziehen, müssen Sie das Array in Workloads um die Kürzel erweitern: "-Workloads @('AAD', 'EXO', 'INTUNE')". Somit werden alle Komponenten abgefragt und dokumentiert, die M365DSC für diese Workloads kennt und unterstützen kann.
Der Export der Entra-ID-Konfiguration dauert eine Weile, gerade wenn der Tenant etwas größer ist. Da er auch alle Gruppen, Benutzer sowie CA-Regeln umfasst, ist die Wartezeit proportional zur Objektanzahl im Tenant.
Konfigurationen vergleichen
Sollten Sie regelmäßige Snapshots der Tenant-Konfiguration ziehen wollen, können Sie unterschiedliche Versionen des Exports hinterlegen und die resultierenden PS1-Dateien mit einer Datumsreferenz benennen. Das macht es einfacher, zwei Konfigurationen, die zeitlich auseinanderliegen, miteinander zu vergleichen.
Für den Vergleich erstellen Sie einen Delta-Report, indem Sie die beiden Konfigurationen gegenüberstellen und einen HTML-Abgleich erzeugen lassen:
New-M365DSCDeltaReport -Source C:\temp\DSCExport\CA-Policy-01-NOV-2023.PS1 -Destination C:\temp\DSCExport\CA-Policy-01-DEC-2023.PS1 -OutputPath C:\temp\DSCExport\CA-Policy-DeltaReport.HTML
Der Report wird offline generiert, erfordert also keine Berechtigungen oder Online-Zugriff auf Microsoft. Die HTML-Übersicht weist sowohl auf fehlende als auch auf neue Ressourcen wie CA-Richtlinien hin sowie geänderte Konfigurationen wie Scope oder MFA-Einstellungen.
Abweichungen schnell erkennen
Das DSC-Framework funktioniert für On-Premises-Komponenten wie für die Cloud identisch: Die zu überprüfende und korrigierende Definition von Einstellungen liegt in einer PS1-Definitionsdatei, die vor dem Start in das MOF-Format (Managed Object Format) konvertiert wird. Daraus prüft das Framework dann regelmäßig, ob sich die Konfiguration verändert hat und nachgezogen werden muss.
Für M365DSC erstellen Sie entweder eigene Konfigurationsdateien im PS1-Format oder Sie passen eine bestehende an. Eine gute Vorlage dafür kann eine der Konfigurationen sein, die Sie zuvor exportiert haben – im Beispiel die "TenantDetails.PS1". Die Datei wurde so erzeugt, dass Sie bei der Ausführung mit der PowerShell vom DSC-System erkannt und in MOF überführt wird. Anschließend weisen Sie die PowerShell an, die DSC-Überprüfung zu starten – unter Angabe des Ordners, in dem sich die erstellte MOF-Datei befindet:
Start-DscConfiguration -Path C:\temp\DSCExport\ConditionalAccess -Wait -Verbose
Die beiden Schalter "wait" und "verbose" sind nur für die ersten Gehversuche interessant, damit Sie nachverfolgen können, was das System macht. Später können Sie die Schalter weglassen – dann erledigt DSC im Hintergrund seine Arbeit. Ist der Prozess einmal gestartet, überprüft DSC die Konfiguration laut Voreinstellung selbstständig alle 15 Minuten neu. Sind Sie nur an einem Durchlauf interessiert, müssen Sie DSC das sagen und die nächsten Durchläufe stoppen:
Stop-DSCConfiguration -Force
Remove-DSCConfigurationDocument -Stage Current
Je nach Computerkonfiguration kann
Start-DscConfiguration zunächst in eine Fehlermeldung laufen. Wenn PowerShell DSC noch nicht zuvor eingesetzt wurde, müssen Sie gegebenenfalls die Konfiguration von WinRM, dem Remote-Management-Werkzeug, abschließen und die entsprechende Firewallfreigabe erteilen.Außerdem sollten Sie sicherstellen, dass das Benutzerkonto oder das Service Principal neben den Leseberechtigungen in Microsoft Graph auch Schreibberechtigungen für die relevanten Komponenten besitzt. Üblicherweise müssen Sie zu den "*Read.*"-Berechtigungen die "*ReadWrite.*"-Repräsentation wählen – oder Sie befragen
Get-M365DSCCompiledPermissionList und sehen sich die "Update"-Berechtigungen für die gewünschte Komponente an.Wenn Sie die lokalen DSC-Einstellungen für den Rechner, der DSC ausführt, per
Get-DscLocalConfigurationManager überprüfen, sehen Sie auf einem unberührten DSC-System das 15-Minuten-Intervall im Attribut "ConfigurationModeFrequencyMins" und "ConfigurationMode" auf "ApplyAndMonitor" voreingestellt. Letzteres weist die PowerShell an, die Konfiguration zu überprüfen, aber bei Abweichungen nicht zu korrigieren. Sollte eine Autokorrektur erwünscht sein, ist die Einstellung "ApplyAndAutoCorrect" als Konfigurationsmodus erforderlich.Für eine bessere Nachvollziehbarkeit werden dafür auch Eventlog-Einträge geschrieben. Im Windows-Eventviewer unter "Applications and Services Logs / M365DSC" sind dann "Warning"-Einträge zu finden, die ein Abweichen (Drift) signalisieren. Als Quelle des Ereignisses ist dabei die M365DSC-Komponente vermerkt, gegen die geprüft wurde: "MSFT_AADConditionalAccessPolicy". So können Sie effizient nach Drift- und Korrekturevents filtern.
DSC-Einstellungen anpassen
Die Überprüfung des Entra-ID-Tenants durch DSC wird von einem Server aus gestartet, der DSC ausführt und die notwendigen Konfigurationsdefinitionen besitzt. Feineinstellungen für das lokale DSC-System konfigurieren Sie – Sie ahnen es bereits – ebenfalls per DSC. Hierzu erstellen Sie eine eigene PowerShell-Konfigurationsdatei, die die gewünschten Einstellungen vornimmt, generieren daraus eine MOF-Datei und laden diesen dann ins DSC-System zur lokalen Ausführung.
Listing 2 zeigt eine PS1-Definitionsdatei, die das Intervall von 15 Minuten auf 10 Minuten heruntersetzt und DSC außerdem anweist, veränderte Konfigurationen sofort und selbstständig zu korrigieren. Speichern Sie den Code als PS1-Skript und führen es aus, erstellt die PowerShell die dazugehörige MOF-Datei, die Sie wiederum per PowerShell übernehmen:
Set-DscLocalConfigurationManager -Path C:\temp\DSCLocalConfig\
Weitere Detailkonfigurationen für das DSC-System, das sie auf ähnliche Weise vornehmen können, sind unter [4] genauer beschrieben.
Listing 2: DSC-Konfiguration anpassen
[DSCLocalConfigurationManager()]
Configuration LCMConfig
{
Node localhost
{
Settings
{
ConfigurationMode =
'ApplyAndAutoCorrect'
ConfigurationModeFrequencyMins = ‘10’
}
}
}
LCMConfig -OutputPath C:\temp\DSCLocalConfig -Verbose
Schutz der Konfigurationen
Configuration-as-Code macht Infrastruktur-, Software- und SaaS-Projekte angenehmer zu verwalten. Gerade, wenn Sie einzelne Komponenten über mehrere Stufen, etwa Entwicklung, Test, Integration und Produktion nutzen, reduziert ein automatisiertes Verfahren des Deployments der Konfiguration manuelle Fehler. Nicht zu vernachlässigen ist allerdings, dass CaC, weitreichende Berechtigungen in den Zielsystemen erhalten muss, wenn Sie Abweichungen nicht nur erkennen, sondern auch korrigieren wollen. Die Schreibberechtigungen sollten sowohl für den Anwendungsfall fein dosiert als auch geschützt werden. Wer die CaC-Komponente, in diesem Fall den Server mit PowerShell DSC oder die Konfigurationsdateien in Form der PS1 oder MOF-Datei kontrolliert, erhält weitreichende Macht über die Microsoft-Cloud.
Es lohnt sich darüber nachzudenken, die verschiedenen Komponenten, zumindest für schreibenden Zugriff, voneinander in unterschiedliche Service Principals mit verschiedenen Credentials zu trennen. So existiert nicht ein übermächtiger SP für die ganze Cloud, sondern die Dokumentation für die gesamte Cloud ist getrennt von einzelnen, korrigierenden Service Principals.
Für die Konfigurationsdateien im PS1- und MOF-Format sollten Sie andenken, gerade für die Produktionsumgebung sichere Prozesse oder Erstellung und solide Wege der Speicherung zu suchen. Ein möglicher Ansatz wäre DevOps, womit Änderungen in einer Testumgebung erprobt, automatisiert aufgenommen, überprüft und dann in die Soll-Konfiguration für die Produktion übernommen werden – möglichst ohne menschliche Interaktion.
Fazit
Das Microsoft-365-DSC-Projekt erleichtert viele Schritte der Tenant-Konfiguration, die Admins in mühseliger, manueller Arbeit oder kreativer Skriptlogik selbst vollbringen müssten. Mit recht wenigen Schritten sind die PowerShell-Kommandos einsatzbereit und liefern für die Änderungsverfolgung, die Dokumentation, aber auch für schwergewichtigere Tätigkeiten wie Konfigurationsmanagement und -erzwingung sowie das Klonen von Einstellungen zwischen Test-, Integrations- und Produktionsumgebungen tolle Ergebnisse. Mit den erforderlichen Berechtigungen in Entra ID, Exchange und Co. sollten Sie sich allerdings eingängig beschäftigen.
(ln)
Link-Codes
[1] Microsoft365DSC: https://export.microsoft365dsc.com/
[2] Graph Explorer: https://aka.ms/ge
[3] Microsoft-365-DSC-Authentifizierung: https://microsoft365dsc.com/user-guide/get-started/authentication-and-permissions/
[4] Befehlsreferenz Set-DscLocalConfigurationManager: https://learn.microsoft.com/en-us/powershell/module/psdesiredstateconfiguration/set-dsclocalconfigurationmanager?view=dsc-1.1