Abweichler finden

von Nico Thiemer

Die Desired State Configuration ist eine deklarative PowerShell-Erweiterung, die die einfache und transparente Konfiguration von Systemen und Anwendungen erlaubt. Damit ist möglich, Änderungen automatisch zu verfolgen und bei Bedarf wieder auf den gewünschten Zustand zurückzusetzen. Microsoft hat diese Erweiterung vor einiger Zeit für Microsoft 365 zur Verfügung gestellt. Wir beschreiben die recht aufwändige Ersteinrichtung und den Einsatz der Microsoft 365 Desired State Configuration.

Im Umfeld von Microsoft 365 mit seiner Vielfalt der Konfigurationen und mit mehreren zu verwaltenden Mandanten ist Desired State Configuration (DSC) eine ideale Möglichkeit, um den Überblick zu behalten und Änderungen einfach nachzuvollziehen. Microsoft stellt zum Projekt viele Informationen [1] bereit, allerdings sind diese unserer Erfahrung nach zum Teil veraltet. Unser Artikel wurde derweil im März dieses Jahres verfasst und bezieht sich auf diesen Stand.

Vorbereitungen für DSC

Bevor wir mit der Einrichtung von DSC in Microsoft 365 (M365DSC) beginnen, müssen wir eine Azure-Active-Directory-(AAD)-Anwendung erstellen, die wir später zur Authentifizierung des PowerShell-Skripts nutzen. Alternativ ist auch eine Anmeldung per Benutzername und Passwort möglich – die Vor- und Nachteile der Verfahren betrachten wir später noch im Detail.

Bei der Authentifizierung mit einer AAD-Anwendung kommt entweder ein Zertifikat oder ein Client-Secret zum Einsatz. In unserem Beispiel nutzen wir ein Zertifikat, weil dies der aktuell von Microsoft empfohlene Weg ist. Das Zertifikat erstellen wir dabei selbst. Im Zuge des Anlegens besagter AAD-Anwendung landet das Zertifikat im Zertifikatsspeicher des aktuell angemeldeten Benutzers – nur für ihn funktioniert also die Authentifizierung.

Da in Microsoft 365 die Arbeit mit SharePoint Online unerlässlich ist, nutzen die meisten Administratoren das PowerShell-Modul "Office PnP". Mit diesem legen wir unsere AAD-Applikation an. Das klappt selbstverständlich auch auf anderen Wegen, zum Beispiel im AAD-Webportal. Wir gehen hier jedoch den Weg über Office PnP und falls Sie das Modul nicht installiert haben, erledigt dies folgender Befehl in einer administrativen PowerShell:

Um der PnP-Management-Shell die notwendigen Rechte zu gewähren, ist nach der Installation das Kommando

auszuführen. Danach legen Sie die AAD-Anwendung an:

Dies erzeugt automatisch ein Zertifkat in "C:\DSC" und das Passwort des privaten Schlüssels entspricht dem Parameter "GeheimesPasswort".

Das Zertifikat landet automatisch im Zertifikatspeicher des Benutzers und wird ebenso in unsere AAD-Anwendung hochgeladen. So erhält diese Applikation in SharePoint alle Rechte ("Sites.FullControl.All", "Group.ReadWrite.All" und "User.Read.All").

Ist für den ausführenden Benutzer eine Multifaktor-Authentifizierung aktiviert, was in Microsoft 365 für einen Administrator selbstverständlich sein sollte, nutzen Sie zusätzlich den Parameter "-Device-

Login". Nun wird in der PowerShell ein Code generiert, den Sie in dem sich öffnenden Browserfenster eintragen. Anschließend melden Sie sich mit Benutzername und Passwort an. Weitere Informationen finden Sie unter [2]. Nach dieser Vorbereitung installieren Sie DSC mit

Der erste Befehl nach einer erfolgreichen Installation sollte

sein. Planen Sie hier etwas Zeit ein, die Ausführung kann langwierig sein.

Je nachdem, auf welche Komponenten Sie in Microsoft 365 zugreifen möchten, sind Berechtigungen in Microsoft Graph zu setzen. Wollen Sie DSC für alle Komponenten in Microsoft 365 nutzen, lassen sich die entsprechenden Rechte über

abfragen. Um nur einzelne Komponenten einzusetzen oder einfach zu prüfen, welche es gibt, nutzen Sie den Befehl:

Alle Rechte für einzelne Komponenten setzt das Cmdlet:

Das folgende Kommando setzt das Leserecht für die Komponenten "SharedMailbox" und "TeamsUser". Die Liste der Komponenten wird dabei im Parameter "ResourceNameList" als Array übergeben. Eine Änderung der Komponenten (Update) ist mit dem Befehl allerdings nicht möglich.

Diese Aktion erfordert eine aktive Zustimmung während der Ausführung. Möchten Sie für alle Komponenten die Rechte "Lesen" und "Ändern" setzen, so geht dies mit diesen Befehlen:

Anmeldung für Mandanten-Snapshot

Im ersten Schritt exportieren wir die Konfiguration eines Microsoft-365-Mandanten und legen sie als Textdatei ab (Snap-shot). Doch bevor wir damit beginnen, muss noch einmal das Thema Authentifizierung auf den Tisch, denn es ist wichtig zu verstehen, welche Risiken damit verbunden sind.

Wie schon erwähnt, kann sich eine Anwendung, also auch ein PowerShell-Skript, am Azure Active Directory und damit an Microsoft 365 über mehrere Wege authentifizieren. Die beiden für uns relevanten sind dabei die Anmeldung als Benutzerkonto mit Benutzername und Passwort oder die Anmeldung als Service Principal mit einer AAD-Application-ID. Dort ist noch zwischen einer Anmeldung mit einem Client-Secret und einer mit einem Zertifikat zu unterscheiden. Die Anmeldung mit einer AAD-Application-ID und einem Zertifikat ist der Lösung mit Benutzername/Passwort immer vorzuziehen. Zum einen reduziert dies die Angriffsfläche und auch der Wartungsaufwand (Konto wird deaktiviert/Passwort wird geändert) ist geringer. Bedauerlicherweise ist es allerdings in M365DSC nicht möglich, sich an allen Komponenten mit einer AAD-Application-ID anzumelden.

So ist es zwar möglich, sich am AAD mit einer AAD-Application-ID und einem Zertifikat anzumelden. Wollen Sie aber zum Beispiel den bedingten Zugriff konfigurieren, so geht das wiederum nur mit Benutzername/Passwort. Um also einen Snapshot eines gesamten Mandanten erstellen zu können, bleibt nur die Anmeldung mit Benutzername und Passwort. Der Export der Daten erfolgt mit

Den Befehl mit seinen Optionen können Sie entweder auf der Kommandozeile zusammenbauen oder mit dem Parameter "-LaunchWebUI" starten. Es erfolgt eine Weiterleitung im Browser zu "HTTPS:// Export.Microsoft365DSC.com", wo Sie den Export über eine GUI bequem zusammenstellen. Beachten Sie jedoch, dass in der Standardeinstellung nicht alles ausgewählt ist. In Planner wird zum Beispiel überhaupt nichts exportiert. Möchten Sie alle Daten berücksichtigen, stellen Sie das Dropdown-Menü oben links auf "Full" und klicken anschließend oben rechts auf "Generate".

Dies erzeugt ein Skript, das kopiert und dann in der PowerShell zur Ausführung kommt. Der Vorgang kann einige Minuten oder gar Stunden dauern. Unter Umständen müssen Sie auch noch einmal das Modul "PnP Management Shell" berechtigen – dies hängt von der vorherigen Konfiguration und Verwendung ab.

Ist die Konfiguration abgeschlossen, haben Sie einen Snapshot des Mandanten zum Ausführungszeitpunkt. Das ist schön und gut, aber nicht wirklich praktisch. Besser wäre ein unbeaufsichtigter Export, der zum Beispiel einmal die Woche läuft. Dafür ist die interaktive Anmeldung notwendig, denn das kopierte Skript fragt immer nach Benutzername und Passwort.

Als Alternative ist zum einen die Anmeldung mit der AAD-Applikation zu nennen. Möchten Sie nicht alle Komponenten exportieren, sondern nur die, die zu einer Anmeldung mit einer AAD-Anwendung kompatibel sind, ist dies das Mittel der Wahl. Hier müssen Sie einfach etwas testen. Das generierte Skript auf der Website verlangt für das Login "ApplicationId", "CertificateThumbprint" und "TenantId". ApplicationId und TenantId finden Sie in der vorher erstellten AAD-Anwendung unter "App Registration". Klicken Sie dort auf den Namen der App, stehen im Header die Daten. Das CertificateThumbprint finden Sie in der App unter "Certificates & Secrets". Den privaten Schlüssel haben wir vorher in unseren Zertifikatsspeicher importiert.

Da aber nicht alles mit einer AAD-Applikation geht, führt kein Weg daran vorbei, ein persönliches Login zu nutzen. Die Herausforderung liegt dabei darin, das Passwort des Benutzers im Skript zu verschlüsseln. Denn natürlich lässt sich im Skript das Passwort mit

als Klartext speichern. Dies ist aber keine ideale Lösung. Besser wäre es, das Passwort mit einem AES-Key zu verschlüsseln. Dazu legen wir das Passwort und den AES-Key jeweils in einer Datei ab und verweisen im Skript darauf:

Zur Anmeldung im Skript dient:

Export von Konfigurationen

Das zuvor erwähnte Skript von der Website wird exportiert und in der PowerShell ausgeführt. Ist es durchgelaufen, fragt es nach einem Speicherplatz für die Konfiguration. Stellen Sie hier nichts ein, hat die Exportdatei immer den gleichen Namen. Um dies zu vermeiden oder wenn Sie das Skript periodisch ausführen möchten, ergänzen Sie den Befehl "Export-M365DSCConfiguration" und die Parameter "-Path" und "-FileName".

Alternativ lassen Sie die Auflistung der Komponenten weg und nutzen stattdessen den Parameter "-Mode" mit den Argumenten "Lite|Default|Full". Ein Aufruf könnte dann wie folgt aussehen. Er exportiert die gesamte Konfiguration eines Mandaten und legt sie im Pfad "C:\DSC" ab:

Neben dem Export ist es auch möglich und wichtig, eine vorhandene Konfiguration wieder einzuspielen. Dazu muss die erzeugte PS1-Datei erst in eine sogenannte Managed-Object-Format-(MOF)-Datei kompiliert werden. Dies geht einfach, indem Sie die Datei "M365Tenant- Config.ps1" in der PowerShell ausführen.

Allerdings findet sich in der MOF-Datei das darin verwendete Passwort im Klartext. Auch wenn vorher eine Verschlüsselung erfolgte oder ein verschlüsseltes Benutzerobjekt zum Einsatz kam – an dieser Stelle steht es immer im Klartext.

Zum Glück gibt es ein Bordmittel von DSC, mit dem Sie das Problem lösen. Dazu führen Sie den Befehl

aus. Dieser erzeugt ein Zertifikat, das DSC nutzt, um im MOF-File die Anmeldedaten zu verschlüsseln. Aber Achtung: Der Vorgang schlägt fehl, wenn Sie WinRM noch nicht konfiguriert haben. In diesem Fall richten Sie WinRM mit dem Befehl winrm quickconfig ein. Passt die Konfiguration, wird das Passwort in der Datei verschlüsselt angezeigt.

Ein weiterer wichtiger Hinweis: Der Export einer Konfiguration muss nach dem Erzeugen des Zertifikats erfolgen. Am besten führen Sie den Befehl also vor dem ersten Export aus. Beim Export wird dann auch das entsprechende Zertifikat im Ordner abgelegt und in der Datei "ConfigurationData.psd1" entsprechend referenziert.

Arbeiten mit Konfigurationen

Der Import einer Konfiguration stellt sich im Gegensatz zum Export vergleichsweise einfach dar. Schließlich ist ja nun schon alles konfiguriert. Der Befehl lautet Start-DSCConfiguration und als Argument übergeben wir den Pfad, in dem die MOF-Datei liegt. Nutzen Sie hierbei den "Verbose"-Parameter, um bei eventuellen Fehlern mehr Möglichkeiten zu haben. Auch hier kann es wieder Stunden dauern, bis der Vorgang abgeschlossen ist:

Unter Umständen erhalten Sie den Fehler, dass in WinRM die Anforderungsgröße überschritten ist. In diesem Fall erhöhen Sie diese Größe mit dem Befehl:

Mit DSC ist es möglich, eine gegebene Konfiguration alle 15 Minuten gegen eine Vorgabe zu überprüfen. Ist die Vorgabe nicht erfüllt, kann DSC den gewünschten Zustand aus der MOF-Datei wiederherstellen. Dieser Vorgang ist einstellbar, Anleitungen finden sich unter [3].

Außerdem lassen sich damit auch Konfigurationen klonen. Gerade wenn Sie mehrere Mandanten mit eigentlich gleichen Konfigurationen verwalten, ist diese Möglichkeit sehr nützlich. Sie nehmen alle Einstellungen auf einem Master-Mandanten vor und exportieren anschließend die Konfiguration in andere Mandanten.

Auswertungen erzeugen

Interessant ist auch die Möglichkeit, verschiedene Konfigurationen miteinander zu vergleichen. Dabei kann es sich um Exporte ein und desselben Mandanten zu verschiedenen Zeitpunkten, aber auch verschiedene Mandanten handeln. M365DSC bietet dazu die Möglichkeit, Auswertungen zu erstellen, die im Excel- und HTML-Format zur Verfügung stehen. Dabei dient eine Excel-Datei nur als Dokumentation für einen Mandanten, mit den HTML-Berichten können Sie auch Vergleiche anstellen. Einen einfachen Report erzeugt

Hier können Sie zusätzlich den Parameter "-Type" mit Excel oder HTML übergeben und mit "ConfigurationPath" den Ort der Konfigurationsdatei. Dabei ist nicht die MOF-Datei gemeint, sondern die (standardmäßig benannte) M365TenantConfig.ps1-Datei.

Der Parameter "-OutputPath" gibt den Speicherort des Berichts an. Dabei müssen Sie Ort und Dateinamen angeben. Ohne einen Dateinamen sehen Sie bei der Option "HTML" zwar den HTML-Output in der PowerShell, die Datei wird aber im Dateisystem nicht erzeugt. Mit der Option "Excel" öffnet sich die Datei zwar in Excel, doch "-OutputPath" hat keine Bedeutung, denn eine Datei lässt sich nur aus Excel heraus speichern. Zum Vergleichen nutzen Sie den Befehl

mit den Parametern "-Source" und "-Destination". Diese verweisen ebenfalls auf die jeweiligen Konfigurationsdateien. So erzeugen Sie eine HTML-Datei, für die Sie mit "-OutputPath" erneut den Speicherort angeben. Lassen Sie den Parameter weg, zeigt sich der HTML-Output in der PowerShell-Konsole.

Fazit

DSC für Microsoft 365 ist ein Werkzeug, mit dem sich Konfigurationen archivieren und gegebenenfalls wiederherstellen lassen. Auch ist ein Vergleich verschiedener Mandanten umsetzbar. Nicht zu vergessen ist die Möglichkeit, einfach und zuverlässig die Einstellungen mehrerer Mandanten synchron zu halten. Dabei macht der administrative Gewinn die vergleichsweise aufwendige Einrichtung mehr als wett.