Migration von AzureAD und Msol-Modul zu Microsoft Graph

Seit dem 30. Juni 2023 sind das AzureAD-Modell und das Msol-Modul als veraltet eingestuft. Administratoren sollten nun zum Microsoft Graph-Modul wechseln. Um dabei Unterstützung zu erhalten, können die offiziellen Migrationsanleitungen von Microsoft genutzt werden:

Die Nichtbeachtung dieser Änderung kann zu Funktionsunterbrechungen führen, da die veralteten Module nicht mehr unterstützt und aktualisiert werden. In dem Nachfolgenden Beitrag erläutere ich ein paar Grundlagen, insbesondere das Thema der Authentifizierung zur Nutzung in PowerShell.

Inhaltsverzeichnis

Microsoft Graph-API Authentifizierung mit PowerShell

Automatisierung und Integration sind Schlüsselkonzepte für effiziente Geschäftsabläufe. In dieser Anleitung erkläre ich die unterschiedlichen Authentifizierungsmethoden zur Nutzung der Microsoft Graph-API mit PowerShell, insbesondere Connect-MgGraph.

Schritt 1: Installation der notwendigen Tools

Falls nicht bereits auf eurem System installiert, beginnen wir mit der Installation von PowerShell mittels Winget:

winget install --id Microsoft.Powershell --source winget

Als nächstes installieren und importieren wir das Microsoft.Graph-Modul in PowerShell:

Install-Module Microsoft.Graph -Scope AllUsers Import-Module Microsoft.Graph.Authentication

Um alle Microsoft.Graph-Module zu importieren, führen wir folgenden Code aus:

$graphModules = Get-Module -ListAvailable -Name Microsoft.Graph* $graphModules | ForEach-Object { Write-Output "Importing $($_.Name)" Import-Module -Name $_.Name }

Schritt 2: Verbindung mit Connect-MgGraph

Nachdem wir die Module installiert und importiert haben, können wir uns nun mit Connect-MgGraph verbinden:

Connect-MgGraph -Scopes "User.ReadWrite.All", "Group.ReadWrite.All"

Eine vollständige Liste der verfügbaren Berechtigungen findet ihr hier: https://learn.microsoft.com/en-us/graph/permissions-reference

Verschiedene Authentifizierungsansätze

Hier sind einige Möglichkeiten, wie ihr Connect-MgGraph verwenden könnt:

Anmelden mit Nutzeranmeldedaten (Modern Auth)

Wir können die Connect-MgGraph-Cmdlet verwenden, die eine interaktive Authentifizierung unterstützt. In diesem Fall benötigen wir gültige Benutzeranmeldeinformationen. Zudem muss der Benutzer über entsprechende «App-Consent-Permssions» verfügen.
Standardmäßig erlaubt Azure AD Benutzerzustimmungen, doch dies kann im Azure-Verwaltungsportal beschränkt werden. Diese Einschränkung verhindert, dass Benutzer (außer Office 365 Global Administratoren) sich bei der Directory Webanwendung anmelden können. Es sei denn, es erfolgen zwei entscheidende Anpassungen:
- Benutzern oder Gruppen muss Zugriff auf die Directory-Anwendung zugewiesen werden.
- Ein Global Administrator muss im Namen der Benutzer Zustimmung erteilen.

Anmeldung als «Registered App»

Um Microsoft GraphAPI in PowerShell zu verwenden, muss zunächst eine Anwendung in Azure Active Directory (Azure AD) registriert werden. Diese Anwendung wird als „Registered App“ bezeichnet.

Die Registrierung einer Anwendung in Azure AD ermöglicht es ihr, sich in Azure AD zu authentifizieren und Ressourcen, wie z.B. GraphAPI, abzurufen. Die Anwendung erhält dabei eine eindeutige Anwendungs-ID und einen Anwendungsschlüssel (Application Key), die zur Authentifizierung gegenüber Azure AD verwendet werden.

Bei der Registrierung der Anwendung werden auch die notwendigen Berechtigungen (Permissions) festgelegt, die die Anwendung für den Zugriff auf die Ressourcen benötigt. Diese Berechtigungen werden in Form von Rollen definiert, die entweder auf Anwendungsebene (Application Permissions) oder auf Benutzerebene (Delegated Permissions) gewährt werden können.

Für die Verwendung von GraphAPI in PowerShell sind in der Regel mindestens folgende Berechtigungen erforderlich:

Directory.Read.All: Ermöglicht es der Anwendung, alle Verzeichnisse im Azure AD zu lesen.
User.Read.All: Ermöglicht es der Anwendung, alle Benutzerinformationen im Azure AD zu lesen.
Group.Read.All: Ermöglicht es der Anwendung, alle Gruppeninformationen im Azure AD zu lesen.

Bitte beachte, dass für einige Funktionen von GraphAPI weitere Berechtigungen erforderlich sein können. Den Berechtigungen können nun durch den Admin im Kontext der Organisation zugestimmt werden.

HowTo: Registrierung einer App mit Azure AD:

Die Anwendungsregistrierung in Azure AD ermöglicht den Zugriff auf MS Graph ohne interaktives Login.

Wir loggen uns ins Microsoft Entra Admin Center ein.
Unter Azure Active Directory, wählen wir ‚Applications‘ -> ‚App registrations‘. Wir klicken auf ‚New registrations‘.
Wir geben unserer Anwendung einen Namen, legen fest, wer Zugriff haben soll und lassen das ‚Redirect URI‘ Feld leer. Wir klicken auf ‚Register‘.
Wir speichern die Client ID und Tenant ID für später.
Wir konfigurieren die Berechtigungen für die Anwendung: Wir gehen zu ‚API permission‘ unter ‚Manage‘, wählen ‚Microsoft Graph‘, dann ‚Application Permissions‘. Wir fügen User.Read.All und Group.Read.All hinzu und entfernen die Standardberechtigung User.Read (Delegated type).
Wir gewähren die Admin-Zustimmung und laden unser Zertifikat hoch. Wir speichern den Zertifikat-Fingerabdruck für später.

Option 1: Anmelden mit Clientzertifikatsanmeldedaten:

In diesem Fall verwenden wir ein Zertifikat zur Authentifizierung:

Connect-MgGraph -TenantId „33c6aefa-de35-487d-b1af-bb34313e48b8“ -ClientId „80560428-7c1b-48bc-a951-f690b22bbfa4“ -CertificateThumbprint „a09ff183ea16ad0b7b7996e54fd8be7d9221599c“

HowTo: Erstellung eines selbstsignierten Zertifikats mit PowerShell:

Für die Zertifikatsbasierte Authentifizierung in MS Graph müssen wir ein X.509 Zertifikat auf der Maschine installieren, die das Skript ausführt.

Wir können entweder ein CA-Zertifikat oder ein selbstsigniertes Zertifikat verwenden. Für interne Zwecke kann ein selbstsigniertes Zertifikat ausreichend sein. Hier ist, wie wir ein solches Zertifikat mit PowerShell erstellen:

Wir führen den folgenden Befehl in der PowerShell aus:

$Zertifikat=New-SelfSignedCertificate –Subject MSGraph -CertStoreLocation Cert:\CurrentUser\My

Das exportiert ein Zertifikat mit dem Namen ‘MSGraph’ in den Zertifikatspeicher des Benutzers mit einem Jahr Gültigkeit.

Zum Exportieren des Zertifikats, führen wir den folgenden Befehl aus:

Export-Certificate -Cert $Zertifikat -FilePath "C:\Users\admin\Desktop\certname.cer"

Jetzt können wir dieses selbstsignierte öffentliche Zertifikat verwenden, um unsere Azure AD Anwendung zu authentifizieren.

Option 2: Anmelden mit Client-Secret-Anmeldedaten:

In diesem Szenario verwenden wir ein Client Secret zur Authentifizierung:

$ApplicationId = "80560428-7c1b-48bc-a951-f690b22bbfa4" $SecuredPassword = "cIz8Q~OrXb-DWTAgys-tycz4aqHFlisfWq22OcBH" $tenantID = "33c6aefa-de35-487d-b1af-bb34313e48b8" $SecuredPasswordPassword = ConvertTo-SecureString -String $SecuredPassword -AsPlainText -Force $ClientSecretCredential = New-Object -TypeNameSystem.Management.Automation.PSCredential -ArgumentList $ApplicationId, $SecuredPasswordPassword

Anmelden mit verwalteter Identität (Managed Identity)

Azure Subskription benötigt.

Die verwaltete Identität ist eine Funktion von Azure Active Directory. Es handelt sich dabei um eine Identität, die von Azure verwaltet wird und die wir zur Authentifizierung in Diensten, die Azure Active Directory unterstützen, verwenden können. Die Verwendung von verwalteten Identitäten kann die Sicherheit erhöhen, da keine Anmeldeinformationen im Code oder in Konfigurationsdateien gespeichert werden müssen.

Anwendungsbeispiele für das MgGraph Modul

Abrufen aller Benutzer in einem Tenant:

$users = Get-MgUser foreach ($user in $users) { Write-Output ("User: " + $user.UserPrincipalName) }

Abrufen von Details zu Benutzerlizenzen

$users = Get-MgUser foreach ($user in $users) { $licenses = Get-MgUserLicenseDetail -UserId $user.Id foreach ($license in $licenses) { Write-Output ("User: " + $user.UserPrincipalName + " - License: " + $license.SkuPartNumber) } }

Abrufen von Domaininformationen

$domains = Get-MgDomain foreach ($domain in $domains) { Write-Output ("Domain: " + $domain.Id) }

Abrufen von Gruppenmitgliedern

$groupId = "your-group-id" $members = Get-MgGroupMember -GroupId $groupId foreach ($member in $members) { Write-Output ("Member: " + $member.Id) }

Diese Beispiele sollten einen guten Ausgangspunkt für die Nutzung des MgGraph Moduls in PowerShell bieten. Bitte denkt daran, dass ihr für diese Beispiele die entsprechenden Berechtigungen in eurem Microsoft 365 Tenant benötigt. Die benötigten Berechtigungen hängen von den spezifischen Cmdlets ab, die ihr nutzen möchtet.

Schlussfolgerung

Dank Connect-MgGraph und den diversen Authentifizierungsmethoden können wir effiziente und sicherheitsorientierte Lösungen für unsere Organisationen erstellen. Es ist wichtig, sich mit den unterschiedlichen Authentifizierungsverfahren vertraut zu machen und diese gemäß Best Practices zu nutzen.

Ich hoffe, dass diese Anleitung euch dabei hilft, Connect-MgGraph zu nutzen und eure Microsoft 365-Umgebung zu verwalten. Bleibt sicher und automatisiert!