Mit Microsoft Graph PowerShell SDK und MSAL arbeiten

Warum Microsoft Graph?

In den letzten Jahren hat Microsoft den Microsoft Graph entwickelt – ein einheitliches Programmierbarkeitsmodell, das verwendet wird, um mit den Daten von Microsoft 365, Windows 10 und den Enterprise Mobility and Security Services zu arbeiten.

Microsoft Graph verbindet die Daten von Benutzern mit den Microsoft-365-Diensten. Diese können Administratoren dann nutzen, um Informationen abzurufen oder Konfigurationsänderungen vorzunehmen. Microsoft Graph stellt eine Verbindung zu Azure Active Directory her, der Technologie, die zur Verwaltung der Benutzeridentitäten in Office 365/Microsoft 365 verwendet wird.

Microsoft Graph ist ein einzelner Endpunkt, der API-Zugriff bietet und viele Objekte für Microsoft 365 zurückgibt. So können Unternehmen beispielsweise Anwendungen erstellen, die auf Daten über mehrere Microsoft-365-Dienste hinweg zugreifen, anstatt dies manuell über verschiedene Anwendungen wie Exchange Online, SharePoint Online oder Planner zu erledigen. Die zukünftigen Investitionen von Microsoft für das Identitätsmanagement werden sich auf die Verbesserung von Microsoft Graph PowerShell-Befehlen konzentrieren.

Microsoft verknüpft alle Dienste innerhalb von Microsoft Graph, um es zur besten Option für die Abfrage und Aktualisierung von Microsoft-365-Diensten zu machen. Es gibt Software Development Kits (SDKs) für mehrere Sprachen, darunter ein neues Microsoft Graph PowerShell-Modul. Das Ziel von Microsoft ist es, sicherzustellen, dass jedes aktuelle Azure Active Directory Feature über einen passenden Microsoft Graph-Befehl verfügt.

Was ist der Unterschied zwischen aktuellen und Microsoft Graph-Befehlen?

Ein wesentlicher Unterschied zwischen den Befehlen für Azure Active Directory und Microsoft Online einerseits und dem Microsoft Graph andererseits sind die erforderlichen PowerShell-Module. Das Azure-Active-Directory-Modul heißt AzureAD und das Microsoft-Online-Modul nennt sich MSOnline. Für den Microsoft Graph lautet der Modulname Microsoft.Graph.

Ein weiterer Unterschied ist die Verbindungsmethode zum jeweiligen Dienst. Sie installieren und importieren das erforderliche Modul im aktuellen Modell und rufen dann den servicespezifischen Connect-Befehl auf. Beispielsweise verwendet das AzureAD-Modul Connect-AzureAD und das MSOnline-Online-Modul Connect-MsolService, während das Microsoft Graph-Modul Connect-MgGraph verwendet.

Die Befehle in den Modulen AzureAD und MSOnline unterstützen Authentifizierung für Browser, Berechtigungsobjekte und Token-Zugriff. Die Microsoft Graph-Befehle hingegen unterstützen Browser-, Token-Zugriffs- und Zertifikatsauthentifizierung und erfordern die Übergabe von Berechtigungen, die als Scopes bezeichnet werden. Die Scopes bestimmen, welche Befehle innerhalb von Microsoft Graph ausgeführt werden können.

Die folgenden Befehle zeigen, wie eine Verbindung mit dem AzureAD PowerShell-Modul hergestellt werden kann:

$credentials = Get-Credential

Connect-AzureAD -Credential $credentials

Die folgenden Befehle zeigen, wie eine Verbindung mit dem MSOnline PowerShell-Modul erfolgt:

$credentials = Get-Credential

Connect-MsolService -Credential $credentials

Schließlich demonstriert dieses Beispiel, wie eine Verbindung mit dem Microsoft Graph PowerShell-Modul mit einer Browser-Authentifizierung hergestellt wird:

Connect-MgGraph -Scopes `

"User.ReadWrite.All", `

"Group.ReadWrite.All", `

"GroupMember.ReadWrite.All", `

"Application.ReadWrite.All"

Ein Vorteil der Methode ist die Verwendung einer vordefinierten Azure Active Directory-Anwendungsregistrierung und eines Zertifikats mit den entsprechenden Graph-API-Berechtigungen als Verbindungsmethode. Das gibt Ihnen die Möglichkeit, verschiedene Verbindungstypen zu erstellen. Das folgende Beispiel zeigt, wie eine Verbindung mit dieser Methode erfolgen kann.

$certificate = "a904602dd82ae51433e6f83996b00d4277a32a7b"

$appid = "b0771954-8594-4fe8-88ad-025f7074a89e"

$tenantid = "3f4b41d2-b28b-49d6-b441-2615829bb51f"

Connect-MgGraph `

-CertificateThumbprint $certificate`

-ClientId $appid `

-TenantId $tenantid

Im Gegensatz zu den anderen PowerShell-Modulen müssen bei den Microsoft Graph-Befehlen die Berechtigungen oder – wie es das Unternehmen nennt – Scopes für die Verbindung übergeben werden.

Wie man von AzureAD oder MSOnline zu Microsoft Graph migriert

Die Migration von PowerShell-Skripten, die entweder das AzureAD- oder das MSOnline-Modul verwenden, ist keine leichte Aufgabe. Sie müssen jedes Skript auf die aktuellen Befehle überprüfen und sie dann mit den neuen Microsoft Graph-Entsprechungen abgleichen.

Der Migrationsprozess besteht aus vier Hauptschritten:

• aktualisieren Sie die Befehle zum Importieren und Installieren der Module
• wählen Sie den besten Verbindungsansatz
• überprüfen Sie die erforderlichen Berechtigungen für die Verbindung
• aktualisieren Sie die Skripte mit neuen Befehlen aus dem Microsoft Graph-Modul

Die Aktualisierung der Befehle zum Importieren und Installieren des Moduls ist relativ einfach. Beachten Sie aber, dass es zwei Endpunkte gibt: die aktuelle oder Version 1 und die Beta-Version. Die Befehle sind ähnlich, aber die Beta-Version hat neue oder verbesserte Funktionen. Für die Befehle zum Importieren und Installieren benötigen Sie den Modulnamen und das zu verwendende Profil. Um den Beta-Endpunkt zu verwenden, führen Sie Select-MgProfile aus und geben Sie beta als Namen an.

Install-Module Microsoft.Graph

Select-MgProfile -Name "beta"

Import-Module Microsoft.Graph

Die Wahl des Verbindungsansatzes ist etwas komplizierter. Wenn Sie statische oder verteilbare Skripte erstellen, können Sie eine Standard-Browser-Eingabeaufforderung anstelle der App-Registrierungsroute wählen. So können Sie dem Modell der geringsten Privilegien folgen und einen sichereren Ansatz wählen. Bei den meisten Skripten funktioniert das einfache Austauschen der Verbindungsbefehle. Der Benutzer, der das Skript ausführt, wird jedoch möglicherweise einen anderen Ansatz verfolgen.

Nachdem Sie den Verbindungsansatz gewählt haben, müssen Sie die Berechtigungen definieren. Microsoft Graph verwendet ein resource.operation.constraint-Modell.

Microsoft Graph verfügt über einen Befehl zur Überprüfung der Berechtigungen für eine bestimmte Kategorie.

Sie können den Namen der Berechtigungskategorie in Azure Active Directory ermitteln, wenn Sie einer App-Registrierung API-Berechtigungen zuweisen.

Um zum Beispiel die verfügbaren Berechtigungen für die Arbeit mit Benutzern zu sehen, können Sie den folgenden Befehl ausführen:

Find-MgGraphPermission user -PermissionType Delegated

Nach Ausführung des Befehls können Sie die verfügbaren Berechtigungen für alles, was mit Benutzern zu tun hat, in Microsoft Graph sehen. Sie können zum Beispiel die Berechtigungen für das Lesen und Schreiben von Benutzerinformationen in Azure Active Directory einsehen und haben die Möglichkeit, Microsoft Teams-Registerkarten für Benutzer zu verwalten.

Möglicherweise benötigen Sie mehrere Kategorieberechtigungen, um die aktuelle PowerShell-Modulfunktionalität zu replizieren. Beispielsweise brauchen Sie alle Berechtigungen, die in den Bereichen für die Verwaltung von Benutzern, Mail, Teams Chat, Personen, Verzeichnis, Gruppen, Aufgaben und Standorten aufgeführt sind.

Connect-MsGraph -Scopes `

"User.Read", `

"User.ReadWrite.All", `

"Mail.ReadWrite", `

"Directory.Read.All", `

"Chat.ReadWrite", `

"People.Read", `

"Group.Read.All", `

"Tasks.ReadWrite", `

"Sites.Manage.All"

Der Vorteil dieses Ansatzes liegt darin, dass Sie bei jeder Aktualisierung der Berechtigungen diese an den Befehl anhängen, die Verbindung erneut herstellen und dann die Zustimmung abschließen.

Connect-MsGraph -Scopes `

"User.Read", `

"User.ReadWrite.All", `

"Mail.ReadWrite", `

"Directory.Read.All", `

"Chat.ReadWrite", `

"People.Read", `

"Group.Read.All", `

"Tasks.ReadWrite", `

"Sites.Manage.All" `

"eDiscovery.ReadWrite.All"

Nach Verbindung mit dem Microsoft Graph können Sie auf alle Befehle zugreifen, die innerhalb der in den Bereichen angegebenen Kategorie(n) liegen.

Für das Ändern eines Skripts, das entweder das AzureAD- oder das MSOnline-PowerShell-Modul verwendet, sind die am häufigsten erforderlichen Scopes:

• User.ReadWrite.All
• Group.ReadWrite.All
• GroupMember.ReadWrite.All
• PrivilegedAccess.ReadWrite.AzureADGroup
• Application.ReadWrite.All
• AppRoleAssignment.ReadWrite.All
• Domain.ReadWrite.All
• RoleManagement.ReadWrite.Directory
• RoleManagementPolicy.ReadWrite.Directory
• RoleAssignmentSchedule.ReadWrite.Directory
• RoleEligibilitySchedule.ReadWrite.Directory
• Policy.ReadWrite.ApplicationConfiguration
• Policy.ReadWrite.PermissionGrant
• DelegatedPermissionGrant.ReadWrite.All
• Directory.ReadWrite.All
• Contacts.ReadWrite
• Contacts.ReadWrite.Shared
• AdministrativeUnit.ReadWrite.All
• EntitlementManagement.ReadWrite.All

Diese Berechtigungen gewähren volle Lese-/Schreibfähigkeit für die angegebenen Kategorien und ermöglichen die Ausführung der PowerShell-Befehle ohne Berechtigungsprobleme.

Wenn beispielsweise ein Skript, das auf dem AzureAD-Modul basiert, nach bestimmten Benutzerkonten sucht, muss es zum neuen Microsoft Graph-Befehl wechseln.

#  AzureAD PowerShell Command

Get-AzureADUser `

-Filter "UserPrincipalName eq '[email protected]'"

# Microsoft Graph PowerShell Command

Get-MgUser `

-Filter "UserPrincipalName eq '[email protected]'"

Das folgende Beispiel zeigt, wie Sie ein neues Benutzerkonto erstellen, eine Lizenz zuweisen und den Benutzer dann mit dem MSOnline-Modul und dem Microsoft Graph-Äquivalent zu einer Sicherheitsgruppe hinzufügen:

# MSOnline PowerShell Command

$userprincipalname = [email protected]

$firstname = "Firstname"

$lastname = "Lastname"

$location = "US"

$licensename = "ENTERPRISEPACK"

$license = Get-MsolAccountSku | `

Where-Object { $_.skuPartNumber -eq "$licensename" }

$user = New-MsolUser `

-UserPrincipalName $userprincipalname `

-DisplayName "$firstname $lastname" `

-FirstName $firstname `

-LastName $lastname `

-UsageLocation $location `

-LicenseAssignment $license.AccountSkuId

$searchstring = "Contoso"

$group = Get-MsolGroup `

-SearchString $searchstring

$membershiptype = "User"

Add-MsolGroupMember `

-GroupObjectId $group.ObjectId `

-GroupMemberType $membershiptype `

-GroupMemberObjectId $user.ObjectId

# Microsoft Graph PowerShell Command

$userprincipalname = [email protected]

$firstname = "Firstname"

$lastname = "Lastname"

$location = "US"

$licensename = "ENTERPRISEPACK"

$passwordprofile = @{

Password = "P@ssw0rd1"

}

$license = Get-MgSubscribedSku | `

Where-Object { $_.skuPartNumber -eq "$licensename" }

$user = New-MgUser `

-DisplayName "$firstname $lastname" `

-PasswordProfile $passwordprofile `

-AccountEnabled `

-MailNickName "$firstname.$lastname" `

-GivenName $firstname `

-Surname $lastname `

-UsageLocation $location `

-UserPrincipalName $userprincipalname

Set-MgUserLicense `

-UserId $user.UserPrincipalName `

-AddLicenses @{ SkuId = $license.SkuId } `

-RemoveLicenses @()

$searchstring = "Contoso"

$group = Get-MgGroup `

-Search "DisplayName:$searchstring" `

-ConsistencyLevel:eventual

New-MgGroupMember `

-GroupId $group.Id `

-DirectoryObjectId $user.Id

Die Umstellung vorhandener MSOnline- oder AzureAD-PowerShell-Befehle auf die Arbeit mit dem Microsoft Graph ist nicht allzu kompliziert. Sie müssen jedoch die neuen Befehle und die aktuelle Dokumentation überprüfen. Es könnte auch hilfreich sein, sich die Microsoft Graph-Aufrufe mit dem Graph Explorer anzusehen, um die Datenformate für die Übergabe zu überprüfen.