ScriptRunner, Azure und M365 – ein perfektes Trio

Jede Anwendung und jeder Service, welche der Kontrolle des AAD unterliegen sollen, müssen dem Identity Provider bekannt sein. Dafür hält AAD Methoden zur Registrierung bereit (siehe Abb. 2). Mit der Registrierung entsteht im AAD für externe Dienste bzw. Anwendungen wie ScriptRunner ein minimales digitales Abbild, welches die Zugriffsregelungen für den eigenen AAD-Tenant oder auch im Multi-AAD-Tenant-Betrieb bereithält. Die Einstellungen steuern u.a. auch, ob das ScriptRunner Portal im O365-Portal als App direkt anklickbar ist oder verborgen bleibt.

Abb. 2: Der App Registration-Prozess

Die ScriptRunner Service Registration macht den ScriptRunner Service im AAD bekannt, regelt den Verbindungszugriff durch den Service auf das AAD, autorisiert Zugriffe des Service auf das AAD per Zertifikat und erlaubt per Default Lesezugriffe auf das AAD. Bei der Registrierung wird in der ScriptRunner Server das Built-In-Target „Azure AD Home Tenant“ automatisch auf den AAD-Zugriff konfiguriert.

Außerdem können nun AAD Accounts und AAD Security-Gruppen innerhalb von ScriptRunner verwendet und den Applikationsrollen in ScriptRunner zugewiesen werden.

Achtung: die Konfiguration erlaubt den Zugriff von ScriptRunner Server auf Informationen des AAD für die Konfiguration von Applikationsrollen in ScriptRunner und für Azure Queries. Das inkludiert nicht den Management-Zugriff auf diverse Dienste und Ressourcen über PowerShell!

Die ScriptRunner Portal Registration stellt die Benutzeranmeldung vom internen AD auf das AAD des Unternehmens um. Anwender können sich nun ausschließlich mit ihrem AAD-Benutzerkonto anmelden.

Sofern die Verbindung erfolgreich war, können Sie Ihre ScriptRunner-Instanz nun in AAD registrieren.

Nachdem Sie alle Vorbereitungen abgeschlossen und nochmals kontrolliert haben, können Sie die App Registrierungen für ScriptRunner vornehmen. Dazu benötigen Sie die Rechte als globaler Administrator im AAD.

Zuerst lassen Sie sich die Thumbprints der beiden Zertifikate in der PowerShell anzeigen. Dazu nutzen Sie folgenden Befehl:

Es öffnet sich das AAD-Anmeldefenster. Nach der Anmeldung erfolgt eine umfangreichere Script-Verarbeitung. Am Ende erscheint ein längerer Hinweis für die Fertigstellung der Registrierung.

Sie können nun im Azure Portal, unter dem Reiter „App registrations“, die App Registrierungen überprüfen (Abb. 3).

Abb. 3: Die erfolgreiche App Registrierung können Sie im Azure Portal nachprüfen

Außerdem können Sie in der ScriptRunner Admin App im Hauptmenü „Targets“ die Application ID und den Thumbprint für den Zertifikats-basierten Zugriff im Built-in-Target „Azure AD Home Tenant“ überprüfen.

Abb. 4: In der ScriptRunner Admin App können Sie die Tenant ID, die Application ID und den Thumbprint für den Zertifikats-basierten Zugriff für das Azure AD Target überprüfen

Wenn Sie weiterhin die klassischen AD-Accounts für die Benutzeranmeldung verwenden wollen, führen Sie folgenden Befehl aus:

Anschließend müssen Sie in ScriptRunner im Hauptmenü „Delegation“ in einer Rollengruppe die entsprechenden AAD Security Gruppen hinzufügen (Abb. 7). Die Wirkung zur Zugriffsberechtigung durch Mitglieder der Gruppen auf Funktionen in ScriptRunner ist äquivalent aus AD Gruppen bekannten Verhalten.

Abb. 7: Über die ScriptRunner Admin App können ADD Security-Gruppen hinzugefügt werden

Ab diesem Zeitpunkt werden Ihre Anwender beim Aufrufen des ScriptRunner Portal oder der Admin App im Webbrowser auf die Anmeldung im Azure AD umgeleitet. Nach erfolgreicher Authentifizierung sind die Anwender nun autorisiert, ScriptRunner zu verwenden. Sie können die Anmeldung mittels Azure AD Account rechts oben über die Kennzeichnung JWT am Anmeldenamen erkennen.

Bitte beachten Sie, dass die Rechte und Funktionen im ScriptRunner Portal und der ScriptRunner Admin App durch die Applikationsrollen innerhalb von ScriptRunner verwaltet werden.

Azure Queries ermöglichen eine interaktive Auswahl von Objekten, welche im Azure AD, Azure Cloud oder M365 verfügbar sind (Abb. 8). Wie schon bei den bekannten AD Queries in ScriptRunner ist es möglich sowohl direkt als auch mittels PowerShell diese Abfragen zu tätigen (Abb. 9).

Abb. 8: Abfragen von ScriptRunner auf Azure AD, M365 und Azure

Direkte Azure Queries verwenden Microsoft Graph, Azure Resource Graph oder Azure Data Explorer, um die Datenobjekte abzufragen und als JSON-Objekte an die PowerShell Scripte zu übergeben.

Scripted Queries nutzen ein PowerShell-Script, um die Datenobjekte abzufragen. Das Ergebnis ist jeweils ein Datenset, welches im Portal angezeigt wird und aus denen der Anwender auswählen kann.

Abb. 9: Der Query Type „Azure“ steht seit ScriptRunner Version 2020R2 zur Auswahl

Ein kleines Beispiel soll das illustrieren: Sie möchten den Helpdesk-Mitarbeiter aus einer Liste von Anwendern aus dem Azure AD mit ihren Eigenschaften auswählen lassen. Dem Parameter im Hauptscript weisen Sie eine Azure Query zu.

Die Azure Query selbst nutzt ihren Home Tenant, kann aber auch andere Tenant-Konfigurationen verwenden, was vor allem für MSPs interessant ist.

Für Azure Queries gibt es zur Vereinfachung ein paar vorkonfigurierte Elemente: Users, Groups, Group Members, Member of etc. Im Beispiel verwenden wir Users (Abb. 10).

Als Parameter Value eignet sich JSON, weil mit einer Anfrage gleich mehrere Benutzereigenschaften abgefragt werden können. Als Display Value verwenden wir die Azure AD Eigenschaft DisplayName.

Abb. 10: Konfiguration einer Azure Query in der ScriptRunner Admin App

Ein Testlauf zeigt uns die Liste der User, die Parameter Value ist kodiert. Per Mouse-Over können wir die tatsächlichen Werte in JSON anzeigen. Zur Verwendung dieser Werte im Hauptscript wird das Splatting-Feature verwendet.

Dazu wird ein Hashtable definiert, dessen Parameter die gleichen Namen verwenden, wie im JSON-Objekt. Die tatsächlichen Werte werden automatisch zugeordnet und können im Script weiter verarbeitet werden.

Mit dem Einsatz von Pattern-Filtern können Sie die Datenabfrage gezielt einschränken. Das Beispiel in Abbildung 11 fragt alle Gruppen ab, welche „Mail enabled“ sind.

Abb. 11: Abfrage aller Gruppen die „Mail enabled“ sind über den Pattern-Filter

Die Kaskadierung von Azure Queries ist ebenfalls möglich. So lassen sich Use Cases umsetzen, wie dieser: Ein Helpdesk-Mitarbeiter fragt die AAD-Gruppen ab und wählt eine aus. Anschließend werden alle Mitglieder dieser Gruppe angezeigt und er kann einen oder mehrere Mitglieder auswählen. Die Mitglieder werden aus der Gruppe per PowerShell-Script entfernt.

Azure Queries können auch direkt Microsoft Graph ansprechen. Mit dem Microsoft Graph Explorer von Microsoft können Graph Queries erstellt und getestet werden. Die dort getesteten Graph Queries lassen sich 1:1 in ScriptRunner verwenden, indem die erstellte Graph-URI in die ScriptRunner Azure Query kopiert wird (Abb. 12).

Abb. 12: Einsatz einer Microsoft Graph Query in einer ScriptRunner Azure Query

GET-Queries haben keinen JSON-Body. POST-Queries hingegen, benötigen einen JSON-Body mit den abzufragenden Parametern.

Achtung bei der Verwendung von POST: Der Service Principal der registrierten „ScriptRunner Service App“ ist standardmäßig auf read only. Diese Einstellung können Sie im Azure Portal an der App direkt bei den API-Rechten ändern.

Eine weitere Variante besteht in der direkten Verwendung von Azure Resource Queries. Hierdurch ist es möglich, auf alle Azure Cloud Ressourcen zuzugreifen und diese über PowerShell zu managen. Die Abfragen werden mittels Kusto kodiert.

Abb. 13: Verwendung einer Azure Resource Graph Query innerhalb einer ScriptRunner Azure Query

Mit der Azure Integration können nun mit ScriptRunner vielfältige Anwendungsfälle für das Management von Azure AD, Azure Cloud und M365 mit PowerShell umgesetzt werden. Das gilt sowohl für Single-Tenant- als auch für Multi-Tenant-Betrieb.

ScriptRunner-Anwender können nun primär ihren Azure AD Account verwenden, um sich anzumelden. Die Rollenfunktionen können mit Azure AD Sicherheitsgruppen gesteuert werden.

Azure Queries in ScriptRunner sind ein mächtiges Werkzeug, um Objekte und Ressourcen aus Azure AD, Azure Cloud und M365 abzufragen und die Daten in den eigenen PowerShell Scripten zu verwenden.