Graph PowerShell SDK – 1. Teil der Graph Artikelreihe

Die ein oder andere Hürde steht Nutzern im Weg, wenn sie anfangen Graph zu nutzen. In drei Teilen liefert Damian Hilfe. Bevor die Themen Teams und Exchange behandelt werden, geht es hier los mit dem Thema Graph SDK (Software Development Kit).

Ein Anfang

Beim Schreiben dieses Artikels stellte sich die Frage: Wo anfangen? Graph ist eine interessante Mischung aus Sicherheit, Geheimhaltung und Macht in einem Paket, meint der Autor, selbst langjähriger PowerShell-Benutzer (man denke nur an Monad). Aus der Sicherheitsperspektive zeigt das am wenigsten privilegierte Modell, dass Graph über sehr granulare Berechtigungen verfügt, mit denen man realistischerweise ein strengeres Regiment führen kann. Andererseits könnten Nutzer, die an das weniger granulare RBAC-Berechtigungsmodell gewöhnt sind, diese Granularität als abschreckend empfinden. Hinzu kommt das Fehlen eines vollständigen Hilfesystems für alle Cmdlets, die für Graph verfügbar sind. Manchmal ist es entweder eine Schatzsuche oder reines Glück, ein brauchbares Cmdlet zu finden. Wenn wir diese Hürde überwunden haben, sehen wir, welche Möglichkeiten uns in Bezug auf die Sicherheit, die Verfügbarkeit von Cmdlets und die Aufgaben, die mit einem Modul ausgeführt werden können, zur Verfügung stehen. In diesem Artikel werden wir uns mit Graph und den Möglichkeiten der PowerShell-Konnektivität beschäftigen und zeigen, wie man sie im Test- und Produktivsystem einsetzt (du hast hoffentlich einen Tenant zum Testen?).

Mit Graph verbinden

Grundlegendes

Um sich mit der Graph API zu verbinden, verwenden wir eines dieser Cmdlets:

Connect-MgGraph

Oder

Connect-Graph

Eigentlich gibt es keinen Unterschied zwischen den beiden, aber Connect‑MgGraph ist ein Cmdlet, während Connect‑Graph ein Alias ist, der auf Connect‑MgGraph verweist.

Bei Graph wird das Modell mit den wenigsten Berechtigungen verwendet. Wenn wir also eine Verbindung ohne weitere Parameter herstellen, werden keine Berechtigungen oder Rollen zugewiesen. Mit den Basisberechtigungen können wir nicht viel mehr tun, als einige grundlegende Ressourcen und Objekte in Graph abzufragen. Um mehr aus Graph herauszuholen, brauchen wir die richtigen Berechtigungen. Als nächstes werden wir uns ansehen, wie man das macht.

Granulare Berechtigungen (scoped permissions)

Hier kann die Verbindung zu Graph kompliziert werden. Die Berechtigungen für deine Aufgabe zu definieren, kann einige Arbeit und Experimente erfordern, da eine Aufgabe mehr oder weniger Berechtigungen benötigen kann, als ursprünglich erwartet. Wenn die Verbindung über eine Azure-Anwendung mit zertifikatsbasierter Authentifizierung hergestellt wird, müssen möglicherweise auch die vordefinierten Berechtigungen angepasst werden. Sehen wir uns ein Beispielszenario an.

Berechtigungen finden 

Für unser Szenario möchten wir eine Liste der Anwendungen abrufen, die in Azure für einen Tenant registriert sind. Das zu verwendende Cmdlet lautet:  

Find-MgGraphCommand Get-MgApplication 

Ausgabe

Die Ausgabe des Cmdlets Find-MgGraphCommand enthält eine Verbindungs-URL und die Berechtigungen, die zum Ausführen des Cmdlets erforderlich sind.

Es gibt eine Spalte namens Permissions, die eine Eigenschaft dieses Cmdlets ist und die erforderlichen Berechtigungen speichert. Im Folgenden wird die vollständige Liste der Berechtigungen für dieses Cmdlet angezeigt:

Find-MgGraphCommand (Get-MgApplication).Permissions 

Berechtigungen

Beachte, dass es zwei Gruppen von Berechtigungen gibt, die auf den verschiedenen URIs basieren, die für die Verbindung verwendet werden. Wenn wir Anwendungen auflisten wollen, benötigen wir nur die Berechtigung Application.Read.All. Wie verwenden wir diese?

Berechtigungen verwenden

Sobald wir wissen, welche Berechtigungen wir benötigen, können wir diese bei einer neuen Verbindung zu Graph angeben:

Connect-MgGraph -Scopes Application.Read.All

Wenn du diese Berechtigung zum ersten Mal verwendest, erscheint ein Pop-up-Fenster (Permissions requested), in dem du gefragt wirst, ob du diese Änderung genehmigen möchtest:

Lies dieses Pop-up genau durch, um zu verstehen, welche Berechtigungen du erteilst

Um zu überprüfen, ob der Vorgang erfolgreich war, können wir dieses Cmdlet ausführen, um unsere Berechtigungen abzurufen:

(Get-MgContext).scopes

Unsere hinzugefügten Berechtigungen – im gelben Rechteck 

Fehlende Berechtigungen?

Wenn die falschen Berechtigungen vergeben wurden, erhältst du eine Fehlermeldung wie diese:

Die fehlenden Berechtigungen sind in gelben Klammern angegeben

Andere Methoden

• Geräte-ID (device code): Erfordert die Verwendung eines Geräts zur Authentifizierung einer PowerShell-Verbindung.
• Zugriffstoken (access token): Benutze dein Zugriffs-Token, um auf Graph zuzugreifen. Du findest es zum Beispiel im Graph Explorer unter dem Reiter 'Zugriffstoken'. 
• Azure App: Eine in Azure registrierte App kann verwendet werden, um Berechtigungen für deine Graph PowerShell-Verbindungen zu vergeben.
• Certificate Based: Per Azure App weisen wir ein selbst-signiertes Zertifikat zu, um den Zugriff zu kontrollieren – ein Beispiel mit Exchange Online findest du in unserem Blogbeitrag hier (So klappt die Verbindung zu Exchange Online mit CBA (zertifikatsbasierter Authentifizierung)).
• Managed-ID: Azure Automation nutzen und eine Azure Managed Identity verwenden, um auf Graph zuzugreifen.

Ausführen von Cmdlets

Da wir nun mit der Graph PowerShell verbunden sind, haben wir zusätzliche Optionen, um Cmdlets in der Shell auszuführen:

• Graph PowerShell cmdlets: PowerShell-Cmdlets sind Wrapper für die zugrunde liegenden Verbindungen zur Graph-API. Sie sind denjenigen vertraut, die andere PowerShell-Module für andere Microsoft 365-Workloads verwenden.
• Invoke-RestMethod: Mit dieser Methode wird eine direkte Verbindung zur jeweiligen Schnittstelle der Graph API hergestellt. Macht das Sinn? Werfen wir einen Blick darauf.

Graph PowerShell

Beispiele hierfür sind:

Get-MgReportMailboxUsageDetail

Get-MgReportMailboxUsageMailboxCount

Get-MgReportMailboxUsageQuotaStatusMailboxCount

Get-MgReportMailboxUsageStorage 

Wenn du einen dieser Befehle ausführst, erhältst du eine Ausgabe mit den richtigen Parametern oder Switchen:

Get-MgReportMailboxUsageStorage -period 'D7' -OutFile c:\data\test.txt

Die Ausgabe für die Postfachnutzung wird in einer Textdatei zur Analyse/Überprüfung gespeichert.

Invoke-RestMethod

Wie PowerShell-Cmdlets werden diese Cmdlets nach der Verbindung mit Microsoft Graph ausgeführt.

$Results = (Invoke-MGGraphRequest -Method get -Uri 'https://graph.microsoft.com/v1.0/applications/?$select=id,displayName' -OutputType PSObject -Headers @{'ConsistencyLevel' = 'eventual' }).Value

Beachte die URL, die für die Verbindung verwendet wird und die auf die Graph API URI für Anwendungen verweist. Es gibt auch eine "Select"-Aktion, mit der die ID und der Anzeigename der Anwendungen abgerufen werden: 

• https://graph.microsoft.com/v1.0/applications/?$select=id,displayName 

Wenn die Aktion ausgeführt wird, erhalten wir die folgende Ausgabe:

Liste der Anwendungen in einem Tenant mit den Eigenschaften ID und DisplayName als ausgewählte Merkmale

URLs und Graph Explorer

Eine häufige Frage an dieser Stelle ist: Wie finde ich die richtige URL, wenn ich die Invoke-RestMethod noch nicht kenne? Wir können den Microsoft Graph Explorer verwenden, um herauszufinden und zu verstehen, was abgerufen werden kann. Melde dich zuerst bei deinem Tenant an:

Anmelden bei einem Tenant zur Ermittlung der Graph URI Endpunkte 

Nach der Anmeldung sehen wir oben die Basis-URL (https://graph.microsoft.com/v1.0/me), die auf das persönliche Konto des angemeldeten Nutzers verweist. Auf der linken Seite sehen wir ein Fenster, in dem wir verschiedene Endpunkte für eine Query/Abfrage auswählen können.

Links, im roten Rechteck, sehen wir einige Beispielabfragen, die wir ausführen können, um die Grundlagen zu erlernen

Wenn wir eine dieser Optionen unter Anwendungen auswählen, können wir auf die Schaltfläche 'Abfrage ausführen' klicken, um die Query auszuführen. Die URL für diese lautet:

• https://graph.microsoft.com/v1.0/applications?$count=true

Dies ist ähnlich der Abfrage, die wir zuvor ausgeführt haben. Jetzt können wir auch eine Liste der Gruppen im Tenant erhalten, indem wir uns mit dieser URL verbinden:

• https://graph.microsoft.com/v1.0/groups

GET, POST, UPDATE, DELETE

Diese vier Aktionen beschreiben, was wir tun wollen, wenn wir uns mit den verschiedenen Verbindungspunkten (URLs) verbinden. Hier eine kurze Zusammenfassung:

• GET: Wie bei PowerShell Get- wollen wir Objekte in Graph auflisten.
• POST: Erstellt ein neues Objekt, ähnlich dem PowerShell New verb-Cmdlet.
• UPDATE: Ändert ein Objekt in Graph, ähnlich wie ein Set-Cmdlet.
• DELETE: Entfernt ein Objekt aus Graph, ähnlich Remove- in der PowerShell.

Überlegungen zu Graph PowerShell

Wenn du die Graph PowerShell verwendest, ist es gut zu wissen, dass es im Vergleich zu anderen PowerShell-Modulen mögliche Einschränkungen oder generelle Macken/Features gibt. In diesem Abschnitt gehen wir kurz auf diese ein.

• Paginierung: Dies ist ein Punkt, der nicht notwendigerweise auf Graph beschränkt ist, aber unbedingt beachtet werden sollte. Wenn ein Cmdlet ausgeführt wird, werden nicht alle Daten auf einmal zurückgegeben. Stattdessen wird nur ein Abschnitt (eine Seite) in der Ausgabe angezeigt, auch wenn mehr Ergebnisse zurückgegeben werden könnten. Die Seiten werden aus Gründen der Effizienz und zur Verringerung der Ressourcenauslastung des Dienstes zurückgegeben. Um mehr Ergebnisse zu erhalten, können wir die Seitengröße (abhängig vom Cmdlet) und die Seite angeben, von der die Daten angezeigt werden sollen. Einige Cmdlets haben einen -All-Switch, um alle Ergebnisse anzuzeigen. Wenn eine Abfrage 11.000 Ergebnisse hat und die Seitengröße 1.000 ist, gibt es elf Seiten (0 – 10), auf die verwiesen wird. Dies erfordert etwas zusätzlichen Code, sollte aber einfach zu handhaben sein.
• Berechtigungen: Wie bereits erwähnt, handelt es sich bei Graph PowerShell um ein Least Privilege-Modell, das sich von den meisten anderen PowerShell-Modulen unterscheidet, bei denen eine Rolle zugewiesen wird und wir PowerShell-Cmdlets basierend auf diesem Zugriff ausführen können. In Graph müssen wir bestimmte Rechte zuweisen bevor wir unsere Cmdlets ausführen.
• Updates: Das Graph PowerShell Modul wird ständig aktualisiert und verändert. Achte darauf, dass dein lokales Modul auf dem neuesten Stand ist, um es optimal nutzen zu können.
• Filter: Verwende Filter, um schneller Ergebnisse zu erhalten und vermeide wenn möglich Where-Object.
• .
• Filters: Use filters for quicker results and skip using Where-Object if possible.
• Modulkonsolidierung: Microsoft hat kürzlich die Module MSOL und Azure AD eingestellt und Graph übernimmt diese Funktionen. Dies kann dazu führen, dass andere Module ebenfalls obsolet werden und in Graph integriert werden. (Hier der Artikel zum Thema: Hilfe bei Migration zu Graph – das Ende der Azure AD und MSOnline Module.)
• Objekt-GUIDs: Graph referenziert Objekte normalerweise über ihre GUID und nicht über ihren Namen oder andere Attribute. Obwohl ein UPN auch funktioniert, sind GUIDs die beste Wahl.

Was kommt als Nächstes?

Nachdem wir nun die Grundlagen der Graph PowerShell kennengelernt haben, stellt sich die Frage, was wir als nächstes erkunden sollten? In dieser Reihe von Blogartikeln werden wir uns damit beschäftigen, wofür wir Graph in Bezug auf verschiedene Workloads in Microsoft 365 verwenden können. Wir beginnen mit Exchange und gehen dann zu Teams über. Die Artikel werden sich darauf konzentrieren, wie praktisch es ist, Graph PowerShell für die Verwaltung dieser Workloads zu verwenden, welche Aufgaben in Graph ausgeführt werden können und ob das ursprüngliche Modul für eine effiziente Verwaltung noch benötigt wird. Ziel ist es, praktische und nützliche Ratschläge zu geben, welche Methode für beide Workloads verwendet werden sollte. Wir hoffen, dass dies Administratoren hilft, die mit der Abschaffung der Module MSOL und Azure AD zu kämpfen haben. Vielen Dank, dass Sie diesen Artikel gelesen haben.

Weiterführende Links

• ScriptRunner Graph ActionPacks
• Microsoft Graph Explorer 
• Hilfe bei Migration zu Graph – Abkündigung März 2024 (ScriptRunner | Blog)
• Teil 2, Graph und Exchange, Teil 3, Graph und Teams (ScriptRunner | Blog)
• Jetzt ScriptRunner testen
• ScriptRunner: Buche eine Demo mit unseren Produktexperten