Hilfe bei Migration zu Graph – das Ende der Azure AD und MSOnline Module

Mit der Abkündigung von MS Online und dem Azure AD-Modul ist es an der Zeit, die bisherigen Abläufe durch neue Lösungen zu ersetzen. Wir hoffen, dass die folgenden Ideen dir helfen werden.

Bist du betroffen vom Ende dieser Module?

Microsoft stellt Ende März 2024 einige wichtige PowerShell-Module ein. Die Module MS Online (MSOL) und Azure AD/Preview sind davon betroffen. Microsoft hat diese Änderungen zwar schon vor Jahren angekündigt und die Frist dann doch verlängert – jetzt ist es aber so weit.

Was bedeutet das für dich, wenn du diese Module für die IT-Verwaltung und für Migrationsprojekte nutzt?

Es bedeutet, dass es an der Zeit ist, sicher im Umgang mit Graph PowerShell zu werden und einen Weg zu finden, bisherige Abläufe mit den neuen Möglichkeiten zu gestalten. Einige Administratoren haben sich bereits an diese Änderungen gewöhnt und haben keine oder nur wenige Probleme, während andere feststellen werden, dass das Microsoft Graph PowerShell-Modul weniger flexibel oder gar hinderlich bei der Erledigung ihrer Aufgaben ist. In diesem Artikel gehen wir auf diese Herausforderungen ein, zeigen Beispiele, wie sich die Änderungen auf PowerShell Nutzer auswirken, und gehen auf die Hilfedokumentation von Microsoft für diese Veränderungen ein.

Was ist ab 30. März nicht mehr verfügbar?

• Azure AD / Azure AD Preview
• Microsoft Online (MSOL or MSOnline)

Ankündigungen

Wie bei großen Änderungen üblich, hat sich Microsoft Zeit genommen, um Administratoren schrittweise dazu anzuhalten, Änderungen vorzunehmen und sich auf die Zukunft vorzubereiten. Sie wurden fast zwei Jahre im Voraus angekündigt – als kleine Auswahl der Ankündigungen: 

Juni 2022 / Juni 2023 / September 2023 / Dezember 2023

Umstellung auf Graph

Microsoft hat Ressourcen bereitgestellt, die bei der Migration von Cmdlets, Skripten und Anwendungen helfen:

• Migrate Azure AD Graph (link)
• Migrating apps (link)
• Migration steps (link)

Kompatibilität prüfen mit dem Compatibility-Checker

Mit diesem Tool kannst du dein Skript auf Kompatibilität prüfen. Es ist hier in der PowerShell Gallery verfügbar.

Graph PowerShell Grundlagen

Wenn du Graph zum ersten Mal verwendest, ist der Prozess der Verbindung und Vorbereitung ähnlich wie bei anderen PowerShell-Modulen.

Installiere zunächst das Microsoft Graph SDK PowerShell-Modul:

Install-Module Microsoft.Graph

Importiere danach das Modul in PowerShell:

Import-Module Microsoft.Graph

Verbinden mit Graph: Dieses kurze Beispiel zeigt, dass es bei Graph einige Unterschiede gibt, da es in Bezug auf Aufgaben und Berechtigungen detaillierter ist. In diesem Artikel (von Microsoft) erfährst du mehr über die Verbindung zu Graph, die Auswahl von Berechtigungen und mehr.  

Connect-MgGraph -Scopes 'Directory.ReadWrite.All'

Beispiele aus der Praxis

In diesem Abschnitt sehen wir uns einige kurze Beispiele für Aufgaben an, die in den vorher verwendeten Modulen ausgeführt wurden, wir betrachten, wie sie jetzt in der Graph PowerShell ausgeführt werden können. 

MSOnline

(1)  Auflisten aller Nutzer in einem Tenant

MSOnline Service Module:

(Get-MsolUser).Count

Microsoft Graph PS Module:

(Get-MgUser -ALL).Count

Das obere Beispiel ist Graph mit 119 Nutzern und das untere Beispiel ist von MS Online mit ebenfalls 119 Nutzern.

(2) Auflisten von Nutzern als Gast oder Tenant-Mitglied mithilfe eines Einzeilers

MSOnline Service Modul:

Get-MsolUser | Where-Object UserType -eq Member | Sort-Object DisplayName

MSOnline Ausgabe:

Um dasselbe im Graph-Modul zu erhalten, führen wir einen gefilterten Suchlauf/Abruf durch:

Get-MgUser -All -Filter "UserType eq 'Member'"

Graph Ausgabe:

Die Standardausgabe ist unterschiedlich und muss daher angepasst werden, je nachdem, welche Eigenschaften des Nutzers gesucht werden.

(3) Gruppenlizenzierung

Die Lizenzierung hat sich ebenfalls grundlegend geändert und die vorherigen Schritte müssen nun in Microsoft Graph durchgeführt werden. Zu diesem Thema hatte ich bereits einen Artikel für diesen Blog geschrieben. Hier ist der Artikel "Lizenzen und Microsoft Graph PowerShell" verlinkt.

(4) Methoden zur Authentifizierung von Nutzern

Die Authentifizierung eines Kontos in einem Microsoft 365-Tenant kann einige zusätzliche Authentifizierungsmethoden (auch als MFA bekannt) erfordern, um die Person, die sich mit dem Konto verbindet, weiter zu verifizieren. Im MSOnline-Dienst gibt es eine Möglichkeit, die Einstellungen für die starke Authentifizierung festzulegen, aber mit dem Wegfall dieses Moduls ist Graph nun unser Werkzeug. Die Graph PowerShell hat eine gewisse Komplexität und Detailliertheit, die wir hier untersuchen werden. Zunächst zu MSOnline:

$st = New-Object -TypeName Microsoft.Online.Administration.StrongAuthenticationRequirement

$st.RelyingParty = "*"

$st.State = "Enabled"

$sta = @($st)

Set-MsolUser -UserPrincipalName damian@practicalpowershell.com -StrongAuthenticationRequirements $sta

Graph verfügt über zahlreiche Cmdlets, aber bedenke, dass das obige Cmdlets nicht nur in Bezug auf die Methode (MFA pro Nutzer), sondern auch auf das Modul (MSOnline) als veraltet gilt. Wir können es über die Graph PowerShell anpassen. Frage zunächst die Konfiguration für einen Nutzer ab:

Get-MgUserAuthenticationMethod 

-UserId damian@practicalpowershell.com | Format-List

Wir sehen, dass dieser Nutzer MFA konfiguriert hat und drei verschiedene Methoden zur Überprüfung verwendet. Mit Graph PowerShell können wir eine bestehende Methode mit Remove-MgUserAuthentication* cmdlets entfernen, neue Authentifizierungsmethoden mit New-MgUserAuthentication* cmdlets hinzufügen, die Authentifizierungsmethoden mit Update-MgUserAuthentication* cmdlets aktualisieren oder einzelne Einstellungen mit Get-MgUserAuthentication* cmdlets auflisten. Auch wenn eine MFA-Konfiguration pro Nutzer im Allgemeinen nicht empfohlen wird, kann es sein, dass wir Anpassungen vornehmen müssen, wenn ein Nutzer einen Nutzer hat oder wenn eine Authentifizierungsmethode einfach nicht funktioniert.

Methode hinzufügen – Telefonauthentifizierung Phone:

In diesem Beispiel fügen wir die Telefonauthentifizierungsmethode für einen Nutzer hinzu und geben seine Handynummer an:

$params = @{

    phoneNumber = "+1 3125551212"

    phoneType = "mobile"

}

New-MgUserAuthenticationPhoneMethod -UserId postmaster@powershellgeek.com -BodyParameter $params

Methode aktualisieren:

In diesem Beispiel müssen wir dieselbe $params-Variable verwenden, um die neue Telefonnummer zu definieren. Außerdem benötigen wir die bestehende Telefonauthentifizierungsmethode, da wir mehrere Zeilen definiert haben könnten, und schließlich das Update-Cmdlet:

$PhoneAuthID = (Get-MgUserAuthenticationPhoneMethod -UserId postmaster@ powershellgeek.com).Id

$params = @{

    phoneNumber = "+1 3125551212"

    phoneType = "mobile"

}

Update-MgUserAuthenticationPhoneMethod -UserId postmaster@ powershellgeek.com -BodyParameter $params -PhoneAuthenticationMethodId $PhoneAuthId 

Methode entfernen:

Wenn wir eine bestehende Telefonauthentifizierungsmethode aktualisieren müssen (es kann nicht zwei vom gleichen Typ geben) oder wenn wir die Authentifizierungsmethode einfach entfernen wollen, können wir dies mit PowerShell tun:

$PhoneAuthID = (Get-MgUserAuthenticationPhoneMethod -UserId postmaster@powershellgeek.com).Id

Remove-MgUserAuthenticationPhoneMethod -UserId postmaster@powershellgeek.com -PhoneAuthenticationMethodId $PhoneAuthID

Azure AD Beispiele

(1) Hinzufügen von Nutzern zu einer Gruppe

In diesem Beispiel, das üblicherweise verwendet wird, um neue Nutzer zu einer Lizenz- oder Berechtigungsgruppe hinzuzufügen, muss PowerShell eine CSV-Datei lesen, um eine Liste von Nutzern zu verarbeiten und dann die Gruppe aufzufüllen:

Azure AD-Code:

$CSV = Import-Csv .\MailboxesToAdd.txt

Foreach ($User in $CSV) {

  $ID = $User.Alias

  $UPN = $ID+'@mydomain.com'

  $ObjectID = (Get-AzureADUser -ObjectId $UPN).ObjectID

  Add-AzureADGroupMember -ObjectId a616b6a9-21ad-41f3-8204-f52e944d9df4 -RefObjectId $ObjectID

}

Graph Beispiel:

$CSV = Import-Csv .\MailboxesToAdd.txt

Foreach ($User in $CSV) {

  $ID = $User.Alias

  $UPN = $ID+'@mydomain.com'

  $ObjectID = (Get-MgUser -UserId $UPN).Id

  New-MgGroupMember -GroupId a616b6a9-21ad-41f3-8204-f52e944d9df4 -DirectoryObjectId $ObjectID

}

In diesem Beispiel sehen wir, dass sich zwei Cmdlets ändern, und zwar von den Azure AD Cmdlets zu Graph-spezifischen Cmdlets. Das ist ziemlich einfach. Beachte, dass sich in den meisten Fällen auch die Parameter ändern werden.

(2) Abfrage aller Nutzerinformationen

In diesem Beispiel fragen wir eine Liste von Eigenschaften eines Nutzers ab, die zur Dokumentation, Überprüfung oder möglicherweise zur Archivierung verwendet werden können, wenn ein Nutzerobjekt zwischen Tenants verschoben wird.

Get-AzureADUser -Top 500 | Where-Object UserType -eq member | Sort-Object DisplayName | Select-Object UserPrincipalName, DisplayName, GivenName, Surname, Mail, MailNickName, Company, Country, Department, Title, Mobile, PostalCode, State, StreetAddress, TelephoneNumber, UsageLocation | Export-Csv -Path "c:\downloads\atlantix\$Tenant-AzureAD-Export.csv" -NoTypeInformation

Überschneidung

Da zwei verschiedene Module gleichzeitig eingestellt gesetzt werden und sich beide bereits überschneiden, kann es sein, dass einige Cmdlets in Azure AD und dem MSOnline PowerShell-Modul auf ein einziges Cmdlet im Graph PowerShell-Modul abgebildet werden. Hier einige Beispiele:

Get-MgUser (Graph)

Get-CorrespondingGraphCommand Get-AzureADUser

Get-CorrespondingGraphCommand Get-MsolUser

Wir sehen, dass diese beiden Cmdlets aus verschiedenen Modulen in Graph den Get-MgUser als Nachfolger verwenden.  

Beachte, dass es trotz der Überschneidung nicht ideal ist, da nicht alle Parameter und Optionen gleich sind, sodass eine echte Konvertierung Zeit und Lernen erfordert.

Get-MgGroupMember (Graph)

Ein weiteres Beispiel sind Gruppen, die in deinem Tenant existieren. In der Vergangenheit gab es eine Reihe von Cmdlets zur Verwaltung dieser Gruppen, sowohl von MSOnline als auch von AzureAD. Unten sehen wir, dass die Get-Cmdlets auf dasselbe Graph PowerShell Cmdlet verweisen:

Get-CorrespondingGraphCommand Get-MsolGroupMember

Get-CorrespondingGraphCommand Get-AzureADGroupMember

Wir sehen, dass das resultierende Cmdlet Get-MgGroupMember heißt:

Die Zukunft

Gute Werkzeuge für die Zukunft

Wenn wir ein entsprechendes Cmdlet in Graph finden wollen, haben wir mehrere Möglichkeiten, es zu suchen:

.
Verwende dieses clevere Tool, das auf die vorherige Seite verweist und das neue Cmdlet aufruft.

When finding a corresponding cmdlet in Graph, we have a couple of methods of discovery:

• Nutze diese Seite von Microsoft.
• Nutze dieses clevere Tool, das auf die vorherige Seite verweist und das neue Cmdlet zur Verfügung stellt.

Einzelne Cmdlets

Kombiniere das Tool mit der Möglichkeit, zu prüfen, welche Graph-Berechtigungen für die Ausführung des Cmdlets erforderlich sind. Nimm zum Beispiel das Cmdlet Get-MsolUser, ein typisches Cmdlet aus dem MSOnline PowerShell Modul. Mithilfe des PowerShell-Moduls DependencySearch können wir das passende Cmdlet finden und ein Graph-Cmdlet verwenden, um die Berechtigungen zu ermitteln:

$NewCmdlet = (Get-CorrespondingGraphCommand Get-MSOLUser).GraphCommand

(Find-MgGraphCommand $NewCmdlet).Permissions

Nachfolgend findest du einen Auszug aus den Ergebnissen dieser beiden One-Liner:

Auszug aus der vollständigen Liste der Berechtigungen für das Cmdlet Get-MsolUser

Die einzige Komplikation besteht darin, dass einige Cmdlets eine lange Liste von Berechtigungen haben, die den Zugriff auf das Cmdlet erlauben. Wenn möglich, wähle die geringste Berechtigung, beginnend mit den Leseversionen der Berechtigungen.

Ganze Skripte

Es ist eine Sache, ein einzelnes Cmdlet zu übersetzen, aber es ist etwas ganz anderes, wenn wir ganze Skripte haben, für die wir die gleiche Übersetzung brauchen. Mit dem Modul DependencySearch können wir unsere Skripte auf mögliche Probleme untersuchen. Im folgenden Beispiel ermitteln wir zunächst alle verfügbaren Module und wenden dann die Suchfunktion auf das Beispielskript "C:\Repository\ScriptToAnalyze.ps1" an.

$AvailableModule = @(Get-Module -ListAvailable)

Get-CodeDependency -scriptPath "C:\Repository\ScriptToAnalyze.ps1" -AvailableModules $AvailableModule

Die Ergebnisse dieser beiden Zeilen geben dann Cmdlets aus, die durch Graph-Cmdlets ersetzt werden müssen:

Fazit – Schlusswort

Microsoft hat die Endtermine für diese Änderung mehrfach verschoben. Jetzt ist es an der Zeit, die Änderungen vorzunehmen, den Umgang mit Graph zu lernen und sich von den bisherigen, veralteten PowerShell-Modulen zu trennen. Andernfalls kann es passieren, dass du ein kritisches Skript hast, das nicht mehr funktioniert, oder noch schlimmer, dass ein Geschäftsprozess nicht mehr funktioniert und dein Unternehmen finanzielle Verluste erleidet.

Weiterführende Links 

• ScriptRunner Dokumentation für Microsoft Graph
• Hinweise zur Abkündigung:  June 2022 / June 2023 / September 2023 / December 2023 
• Hilfen von Microsoft (Englisch): Migrate Azure AD Graph (link), migrating apps (link) and migration steps (link)
• PowerShell Gallery
• Microsoft learn: Find Azure AD PowerShell and MSOnline cmdlets in Microsoft Graph PowerShell
• ScriptRunner: Erfahre mehr über unsere Software