Erstellen von PowerShell-Skripts mit Microsoft Graph und nur app-Authentifizierung - Microsoft Graph

In diesem Tutorial erfahren Sie, wie Sie ein PowerShell-Skript erstellen, das die Microsoft-Graph-API verwendet, um mithilfe der reinen App-Authentifizierung auf Daten zuzugreifen. Die reine App-Authentifizierung ist eine gute Wahl für Hintergrunddienste oder Anwendungen, die auf Daten für alle Benutzer in einer Organisation zugreifen müssen.

Hinweis

Informationen zur Verwendung von Microsoft Graph zum Zugreifen auf Daten im Namen eines Benutzers finden Sie in diesem Tutorial zur (delegierten) Benutzerauthentifizierung.

In diesem Lernprogramm wird Folgendes vermittelt:

Benutzer auflisten

Tipp

Alternativ zur Durchführung dieses Tutorials können Sie das GitHub-Repository herunterladen oder klonen und den Anweisungen in der INFODATEI folgen, um eine Anwendung zu registrieren und das Projekt zu konfigurieren.

Voraussetzungen

Bevor Sie mit diesem Tutorial beginnen, sollte PowerShell auf Ihrem Entwicklungscomputer installiert sein. PowerShell 5.1 ist die Mindestanforderung, aber PowerShell 7 wird empfohlen.

Sie sollten auch über ein Microsoft-Geschäfts-, Schul- oder Unikonto mit der rolle "globaler Administrator" verfügen. Wenn Sie kein Microsoft-Konto haben, können Sie sich für das Microsoft 365-Entwicklerprogramm registrieren , um ein kostenloses Microsoft 365-Abonnement zu erhalten.

Hinweis

Dieses Tutorial wurde mit PowerShell 7.2.2 und Microsoft Graph PowerShell SDK Version 1.9.5 geschrieben. Die Schritte in diesem Leitfaden funktionieren möglicherweise mit anderen Versionen, die jedoch nicht getestet wurden.

Registrieren der App im Portal

15 Minuten verbleibend

In dieser Übung registrieren Sie eine neue Anwendung in Azure Active Directory, um die reine App-Authentifizierung zu aktivieren.

Erstellen eines selbstsignierten Zertifikats

Das Microsoft Graph PowerShell SDK erfordert ein Zertifikat für die reine App-Authentifizierung. Für Entwicklungszwecke ist ein selbstsigniertes Zertifikat ausreichend. Sie benötigen ein Zertifikat mit dem privaten Schlüssel, der auf dem lokalen Computer installiert ist, und den öffentlichen Schlüssel, der in eine exportiert wird. CER. PEM oder . CRT-Datei.

Windows
Linux/macOS

Unter Windows können Sie das pki PowerShell-Modul verwenden, um das Zertifikat zu generieren.

$cert = New-SelfSignedCertificate -Subject "CN=PowerShell App-Only" -CertStoreLocation `
  "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 `
  -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "./PowerShellAppOnly.cer"

Unter Linux oder macOS können Sie OpenSSL verwenden, um die privaten und öffentlichen Schlüssel zu generieren. Verwenden Sie dann PowerShell, um den privaten Schlüssel in einem Zertifikatspeicher zu installieren, der von PowerShell lesbar ist.

Generieren Sie mit dem folgenden Befehl ein neues X509-Zertifikat.

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -keyout powershell.pem -out powershell.crt -subj "/CN=PowerShell App-Only"

OpenSSL fordert Sie zur Eingabe eines PEM-Passausdrucks auf. Geben Sie einen Passausdruck ein, den Sie sich merken werden.

Erstellen Sie mit dem folgenden Befehl eine PFX-Datei.

openssl pkcs12 -export -out powershell.pfx -inkey powershell.pem -in powershell.crt

OpenSSL fordert Sie zur Eingabe des Passausdrucks für powershell.pem auf, und geben Sie den Passausdruck ein, den Sie im vorherigen Schritt verwendet haben.
OpenSSL fordert Sie zur Eingabe eines Exportkennworts auf. Geben Sie ein Kennwort ein, das Sie sich merken werden.

Öffnen Sie PowerShell, und führen Sie die folgenden Befehle aus. Ersetzen <Sie dabei export-password> durch das Exportkennwort, das Sie im vorherigen Schritt verwendet haben.

using namespace System.Security.Cryptography.X509Certificates
$store = [X509Store]::new('My', 'CurrentUser', 'ReadWrite')
$store.Add([X509Certificate2]::new('./powershell.pfx', '<export-password>', [X509KeyStorageFlags]::PersistKeyS
et))
$store.Dispose()

Registrieren der Anwendung für die reine App-Authentifizierung

In diesem Abschnitt registrieren Sie eine Anwendung, die die reine App-Authentifizierung mit Clientanmeldeinformationen unterstützt.

Öffnen Sie einen Browser, navigieren Sie zum Azure Active Directory Admin Center, und melden Sie sich mit einem globaler Administrator-Konto an.
Wählen Sie in der linken Navigationsleiste Azure Active Directory aus, und wählen Sie dann App-Registrierungen unter Verwalten aus.
Wählen Sie Neue Registrierung aus. Geben Sie einen Namen für Ihre Anwendung ein, PowerShell Graph Tutorialz. B. .
Legen Sie Unterstützte Kontotypen auf Nur Konten in diesem Organisationsverzeichnis fest.
Lassen Sie URI umleiten leer.
Wählen Sie Registrieren aus. Kopieren Sie auf der Seite Übersicht der Anwendung den Wert der Anwendungs-ID (Client) und der Verzeichnis-ID (Mandanten-ID), und speichern Sie sie. Diese Werte benötigen Sie im nächsten Schritt.
Wählen Sie API-Berechtigungen unter Verwalten aus.
Entfernen Sie die Standardberechtigung User.Read unter Konfigurierte Berechtigungen , indem Sie die Auslassungspunkte (...) in der Zeile auswählen und Berechtigung entfernen auswählen.
Wählen Sie Berechtigung hinzufügen und dann Microsoft Graph aus.
Wählen Sie Anwendungsberechtigungen aus.
Wählen Sie User.Read.All und dann Berechtigungen hinzufügen aus.
Wählen Sie Administratoreinwilligung erteilen für... und dann Ja aus, um die Administratoreinwilligung für die ausgewählte Berechtigung bereitzustellen.
Wählen Sie zertifikate und geheimnisse unter Verwalten und dann Zertifikate aus.
Wählen Sie Zertifikat hochladen aus. Laden Sie die Datei PowerShellAppOnly.cer oder powershell.crt hoch, die Sie im vorherigen Schritt erstellt haben, und wählen Sie dann Hinzufügen aus.

Hinweis

Beachten Sie, dass Sie im Gegensatz zu den Schritten bei der Registrierung für die Benutzerauthentifizierung in diesem Abschnitt Microsoft Graph-Berechtigungen für die App-Registrierung konfiguriert haben. Dies liegt daran, dass die reine App-Authentifizierung den Clientanmeldeinformationsflow verwendet, der erfordert, dass Berechtigungen für die App-Registrierung konfiguriert werden. Ausführliche Informationen finden Sie unter .default-Bereich .

Hinzufügen einer reinen App-Authentifizierung

10 Minuten verbleibend

In diesem Abschnitt verwenden Sie die reine App-Authentifizierung mit dem Microsoft Graph PowerShell SDK.

Herstellen einer Verbindung mit der reinen App-Authentifizierung

Trennen Sie alle vorhandenen Microsoft Graph-Verbindungen mit dem folgenden Befehl.
```
Disconnect-MgGraph
```
Öffnen Sie PowerShell, und verwenden Sie den folgenden Befehl, um die $clientID Sitzungsvariable festzulegen. Ersetzen Sie <dabei your-client-id> durch die Client-ID Ihrer App-Registrierung.
```
$clientId = <your-client-id>
```
Legen Sie die $tenantId Sitzungsvariable fest, und <ersetzen Sie your-tenant-id> durch die Mandanten-ID Ihrer Organisation.
```
$tenantId = <your-tenant-id>
```
Legen Sie die $certificate Sitzungsvariable auf den Betreff des zertifikats fest, das im vorherigen Schritt erstellt wurde.
```
$certificate = "CN=PowerShell App-Only"
```
Verwenden Sie den Connect-MgGraph Befehl, um sich mit dem Zertifikat aus dem vorherigen Schritt zu authentifizieren.
```
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateName $certificate
```

Verwenden Sie Get-MgContext , um zu überprüfen, ob Sie mit der reinen App-Authentifizierung authentifiziert sind. Vergewissern Sie sich, dass AuthType ist AppOnly.

PS > Get-MgContext

ClientId              : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
TenantId              : 601faea3-be45-4960-898f-92b379b17cd9
CertificateThumbprint :
Scopes                : {User.Read.All}
AuthType              : AppOnly
AuthProviderType      : ClientCredentialProvider
CertificateName       : CN=PowerShell App-Only
Account               :
AppName               : PowerShell Graph Tutorial
ContextScope          : Process
Certificate           :
PSHostVersion         : 2022.4.1
ClientTimeout         : 00:05:00

Benutzer auflisten

8 Minuten verbleibend

In diesem Abschnitt listen Sie alle Benutzer in Ihrer Azure Active Directory-Instanz auf, die die reine App-Authentifizierung verwenden.

Führen Sie in Ihrer authentifizierten PowerShell-Sitzung den folgenden Befehl aus, um Benutzer aufzulisten.
```
Get-MgUser -Select "displayName,id,mail" -Top 25 -OrderBy "displayName"
```

Überprüfen Sie die Ausgabe.

Id                                   DisplayName              Mail                  UserPrincipalName UserType
--                                   -----------              ----                  ----------------- --------
05fb57bf-2653-4396-846d-2f210a91d9cf Adele Vance              AdeleV@contoso.com
a36fe267-a437-4d24-b39e-7344774d606c Alex Wilber              AlexW@contoso.com
54cebbaa-2c56-47ec-b878-c8ff309746b0 Allan Deyoung            AllanD@contoso.com
9cb2ad7c-8e69-46a6-a947-a02c255048de Automate Bot
9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Bianca Pisani
a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Brian Johnson (TAILSPIN) BrianJ@contoso.com
9e2d4937-44ee-4af4-bd56-77a12cc3ecc4 Cameron White
8990227d-31dc-4120-a38e-f652576974f4 Christie Cline           ChristieC@contoso.com
...

Code erläutert

Betrachten Sie den Befehl, der zum Auflisten von Benutzern verwendet wird.

Wird verwendet -Select , um bestimmte Eigenschaften anzufordern.
Wird verwendet -Top , um die Anzahl der zurückgegebenen Benutzer zu begrenzen.
-OrderBy Verwendet, um die Antwort zu sortieren.

Optional: Fügen Sie Ihren eigenen Code hinzu.

5 Minuten verbleibend

In diesem Abschnitt verwenden Sie Ihre eigenen Microsoft Graph PowerShell SDK-Befehle. Dies kann ein Codeausschnitt aus der Microsoft Graph-Dokumentation oder graph-Explorer oder code sein, den Sie erstellt haben. Dieser Abschnitt ist optional.

Auswählen einer API

Suchen Sie eine API in Microsoft Graph, die Sie ausprobieren möchten. Beispielsweise die API für Listengruppen . Sie können eines der Beispiele in der API-Dokumentation verwenden, eine API-Anforderung im Graph-Explorer anpassen und den generierten Codeausschnitt verwenden oder den Find-MgGraphCommand Befehl verwenden, um den entsprechenden Befehl zu suchen.

Der API-Endpunkt zum Auflisten von Gruppen ist GET /groupsbeispielsweise . Sie können dies verwenden, um den entsprechenden PowerShell-Befehl zu suchen.

PS > Find-MgGraphCommand -Uri "/groups" -Method "GET"

   APIVersion: v1.0

Command     Module Method URI     OutputType           Permissions
-------     ------ ------ ---     ----------           -----------
Get-MgGroup Groups GET    /groups IMicrosoftGraphGroup {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, G…

   APIVersion: beta

Command     Module Method URI     OutputType            Permissions
-------     ------ ------ ---     ----------            -----------
Get-MgGroup Groups GET    /groups IMicrosoftGraphGroup1 {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, …

Die Ausgabe gibt an, dass der Get-MgGroup Befehl der entsprechende Befehl ist.

Konfigurieren von Berechtigungen

Überprüfen Sie den Abschnitt Berechtigungen der Referenzdokumentation für Die ausgewählte API, um zu sehen, welche Authentifizierungsmethoden unterstützt werden. Einige APIs unterstützen z. B. keine app-only.

Um eine API mit nur app-Authentifizierung aufzurufen (sofern die API dies unterstützt), fügen Sie den erforderlichen Berechtigungsbereich im Azure AD Admin Center hinzu. Stellen Sie sicher, dass Sie die Verbindung trennen und die Verbindung erneut herstellen, indem Sie nur die App-Berechtigung verwenden.

Tipp

Die Verwendung des -ForceRefresh Parameters mit dem Connect-MgGraph Befehl stellt sicher, dass neu konfigurierte Berechtigungen angewendet werden.

Ausführen des Befehls

Nachdem Sie nun mit den erforderlichen Berechtigungen verbunden sind, führen Sie den ausgewählten Befehl aus.

Herzlichen Glückwunsch!

100 % abgeschlossen!

Sie haben das PowerShell-Tutorial für microsoft Graph-Apps abgeschlossen. Nachdem Sie nun über eine funktionierende App verfügen, die Microsoft Graph aufruft, können Sie experimentieren und neue Features hinzufügen.

Erfahren Sie, wie Sie die (delegierte) Benutzerauthentifizierung mit dem Microsoft Graph PowerShell SDK verwenden.
Besuchen Sie die Übersicht über Microsoft Graph , um alle Daten anzuzeigen, auf die Sie mit Microsoft Graph zugreifen können.