Verwendung des Microsoft Graph SDK für PowerShell mit Azure Automation

Von Runbooks bis E-Mail

In einem früheren Artikel über die Verwendung von Azure Automation-Konten und Runbooks mit dem PowerShell-Modul für die Exchange Online-Verwaltung habe ich auch erklärt, wie Graph-API-Abfragen in einem PowerShell-Skript verwendet werden, das in einem Runbook ausgeführt wird. Die natürliche Folgefrage besteht darin, zu fragen, ob das Microsoft Graph PowerShell SDK Runbooks unterstützt. Ich kann berichten, dass das SDK mit Azure Automation mithilfe zertifikatbasierter Authentifizierung oder verwalteter Identitäten verwendet werden kann. Natürlich kann eine einfache Aussage eine Menge Komplexität verbergen, also schauen wir uns die Details an.

Als praktisches Beispiel dafür, was möglich ist, konvertiere ich in diesem Artikel das hier beschriebene Skript zum Senden von E-Mails an neue Postfächer, um es in einem Runbook auszuführen.

Azure Automation-Setup

Wie im vorherigen Artikel erläutert, verwenden wir ein Azure Automation-Konto (das an ein Azure-Abonnement gebunden ist), um das Skript auf einem Sandbox-Server auszuführen. Azure Automation unterstützt verwaltete Identitäten, und ich werde mich in einem zukünftigen Artikel mit diesem Thema befassen. Im Moment reicht die bewährte Technik aus.

Update: Azure Automation unterstützt keine Runbook-Konten mehr. Verwenden Sie stattdessen eine verwaltete Identität. Weitere Informationen finden Sie in diesem Artikel. Die hier erläuterten Prinzipien zum Laden von Modulen in ein Automatisierungskonto und zum Zuweisen von Graph-Berechtigungen zu Automatisierungskonten sind weiterhin gültig.

Diagrammmodule importieren

Das RunAs-Konto verfügt über einen Dienstprinzipal und ein von Azure verwaltetes Zertifikat. Dies sind die Schlüsselkomponenten für die Authentifizierung. Die Authentifizierung ist jedoch nur der Anfang. Um das Microsoft Graph PowerShell SDK für ein Runbook verfügbar zu machen, müssen wir seine Module als gemeinsam genutzte Ressourcen in das Automatisierungskonto importieren.

Möglicherweise fällt Ihnen auf, dass ich Module und keine Module verwendet habe. Wenn Sie das Microsoft Graph PowerShell SDK aus der PowerShell-Galerie herunterladen und auf einer Workstation installieren, erhalten Sie kein einziges Modul. Stattdessen ist das SDK in viele verschiedene Module aufgeteilt, von denen jedes einen kleinen Teil der gesamten Graph-Landschaft betreut. Wenn Sie das SDK in ein Automatisierungskonto importieren, müssen Sie die von einem Skript benötigten Module importieren. Die erste Aufgabe besteht darin, die Dokumentation der Cmdlets zu überprüfen, die Sie verwenden möchten, um herauszufinden, in welchem Modul sich die einzelnen Cmdlets befinden.

Nehmen wir beispielsweise an, dass Ihr Skript das Cmdlet Get-MgOrganization verwendet, um Details Ihres Mandanten zurückzugeben. Aus der Dokumentation von Microsoft geht hervor, dass das Cmdlet zum Modul Microsoft.Graph.Identity.DirectoryManagement gehört (Abbildung 1).

Nebenbei möchte ich sagen, dass die Dokumentation für die SDK-Cmdlets ein schreckliches Beispiel dafür ist, warum künstliche Intelligenz manchmal nicht so gut funktioniert, wenn sie zur Erstellung von Dokumentationen auf Basis von Quellcode verwendet wird. Eine Verbesserung der Dokumentation würde dazu beitragen, die SDK-Cmdlets besser zu verstehen und ihre Verwendung zu fördern. Vorerst sind fundierte Interpretationen und viel Geduld erforderlich.

Laden von SDK-Modulen in das Azure Automation-Konto

Nachdem ich das Skript überprüft hatte, um alle SDK-Cmdlets zu finden, importierte ich schließlich vier Module (Abbildung 2):

Microsoft.Graph.Authentication: zur Authentifizierung gegenüber dem Graph.
Microsoft.Graph.Users.Action: um eine Nachricht zu senden.
Microsoft.Graph.Mail: um auf E-Mail-Nachrichten zuzugreifen.
Microsoft.Graph.Identity.Management: um Organisationsdetails abzurufen.

Zuweisen von Diagrammberechtigungen

Das Laden der SDK-Module für die Interaktion mit dem Graph beginnt für uns: Mit den entsprechenden Berechtigungen schließt sich der Kreis. Wenn Sie eine Verbindung mit dem Cmdlet Connect-MgGraph herstellen, kann die von Ihnen erstellte Sitzung bestimmte Graph-Berechtigungen verwenden. Dies ist der Sitzungsbereich. In diesem Fall muss das Skript auf das Postfach eines Benutzers zugreifen, um eine Nachricht zu erstellen, bevor es diese an die Nachrichtenempfänger sendet. Daher muss die für die Authentifizierung verwendete Entität über die zum Ausführen dieser Aktionen erforderliche Graph-Anwendungsberechtigung verfügen. Die Entität ist der Dienstprinzipal für das RunAs-Konto. Bevor das Skript E-Mails senden kann, muss ein Administrator seine Zustimmung erteilen, damit der Dienstprinzipal über die Berechtigungen Mail.Send und Mail.ReadWrite verfügt.

Das Zuweisen von Berechtigungen zum Dienstprinzipal für das RunAs-Konto ist dasselbe wie das Zuweisen von Berechtigungen zu einer registrierten App. Gehen Sie zum Azure AD Admin Center, suchen Sie den Dienstprinzipal in der Gruppe der registrierten Apps, fügen Sie die erforderlichen Berechtigungen hinzu und erteilen Sie die Zustimmung im Namen der Organisation. Am Ende sollten Sie etwas wie Abbildung 3 erhalten. Es sind zwei zusätzliche Graph-Berechtigungen vorhanden, da ich diesen Dienstprinzipal im vorherigen Artikel verwendet habe.

Achten Sie darauf, keine Dienstprinzipale mit zu vielen Graph-Berechtigungen zu erstellen. Wie der Dienstprinzipal, der für interaktive Sitzungen mit dem Microsoft Graph PowerShell SDK verwendet wird, kann ein Dienstprinzipal im Laufe der Zeit leicht Berechtigungen ansammeln, wenn er für mehrere Aufgaben verwendet wird. Erwägen Sie in der Produktion die Verwendung separater Automatisierungskonten für verschiedene Jobs.

Änderung des PowerShell-Codes

Wir haben jetzt ein RunAs-Konto mit den richtigen Berechtigungen und Zugriff auf die erforderlichen Module, also ist es an der Zeit, Code zu schreiben. Als Ausgangspunkt steht ein funktionierendes Skript zur Verfügung, das jedoch angepasst werden muss, damit es in einem Runbook funktioniert. Folgendes habe ich getan:

Zuerst habe ich einen neuen Authentifizierungsabschnitt hinzugefügt, um den Fingerabdruck des Zertifikats vom Automatisierungskonto abzurufen. Das Zertifikat authentifiziert dann die Verbindung zum Microsoft Graph.

$Connection = Get-AutomationConnection -Name AzureRunAsConnection
# Get certificate from the automation account
$Certificate = Get-AutomationCertificate -Name AzureRunAsCertificate
# Connect to the Graph SDK endpoint using the automation account
Connect-MgGraph -ClientID $Connection.ApplicationId -TenantId $Connection.TenantId -CertificateThumbprint $Connection.CertificateThumbprint

Als Nächstes habe ich die Mandantendienstdomäne abgerufen und sie zusammen mit demselben Zertifikatfingerabdruck verwendet, um eine Verbindung zu Exchange Online herzustellen (um die kürzlich hinzugefügten Postfächer abzurufen).

$Organization = Get-MgOrganization
$TenantName = $Organization.DisplayName
$TenantDomain = $Organization.Verifieddomains | ? {$_.IsInitial -eq $True} | Select -ExpandProperty Name
# Connect to Exchange Online
Connect-ExchangeOnline –CertificateThumbprint $Connection.CertificateThumbprint –AppId $Connection.ApplicationID –ShowBanner:$false –Organization $TenantDomain

Denken Sie daran, dass das Automatisierungskonto einige Berechtigungen benötigt, um eine Verbindung zu Exchange Online herzustellen. Diese Berechtigungen werden in meinem vorherigen Artikel beschrieben.

Anschließend habe ich definiert, von wem die Nachricht stammt (das Postfach, das ich verwenden möchte). Wenn ich das Skript interaktiv ausführe, rufe ich diese Informationen von dem Konto ab, das derzeit mit PowerShell verbunden ist. Dies funktioniert jedoch nicht für ein RunAs-Konto. Daher müssen wir die SMTP-Adresse des zu verwendenden Kontos in einer Variablen definieren.

$MsgFrom = "WelcomeNewUsers@Office365itpros.com"

Mein Skript hängt einen Willkommensbrief an, der auf einem lokalen Laufwerk gespeichert ist. Offensichtlich hat ein in einer Sandbox ausgeführtes Skript keinen Zugriff auf mein lokales Laufwerk. Stattdessen lade ich den Willkommensbrief von einer Website herunter und speichere ihn in einem lokalen Ordner. Anschließend kodiert das Skript den Inhalt, um das Anhängen der Datei an eine Nachricht zu ermöglichen.

$WebAttachmentFile = "https://office365itpros.com/wp-content/uploads/2022/02/WelcomeToOffice365ITPros.docx"
New-Item -Path c:\TempForScriptxxx -ItemType directory -ErrorAction SilentlyContinue
$AttachmentFile = "c:\TempForScriptxxx\WelcomeNewEmployeeToOffice365itpros.docx"
Invoke-WebRequest -uri $WebAttachmentFile -OutFile $AttachmentFile
$Attachment = (Get-Item -Path $AttachmentFile).Name
$EncodedAttachmentFile = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentFile))

Endlich. Ich habe alle an den Bildschirm gesendeten Nachrichten mit Write-Host entfernt. Es macht keinen Sinn, diese Meldungen auszugeben, da es keinen Bildschirm gibt, auf dem sie angezeigt werden können, wenn Code in einem Runbook ausgeführt wird.

Die Nachrichten kommen an

Und das ist es. Der Prozess ist nicht schwierig, sobald die vorbereitenden Arbeiten abgeschlossen sind. Der Code wird ausgeführt, weil alle erforderlichen Module im Konto verfügbar sind und das Konto über die richtigen Graph-Berechtigungen verfügt, sodass E-Mails in die Postfächer neuer Benutzer fließen (Abbildung 4).

Sie können eine Kopie des vollständigen Skripts, das ich verwendet habe, von GitHub herunterladen.

Automatisierung ist schön

Das Schöne an der Verwendung von Azure Automation ist, dass Sie das Skript veröffentlichen und es dann so planen können, dass es wöchentlich ausgeführt wird, um Willkommensnachrichten an Benutzer zu senden, die in der Vorwoche beigetreten sind. Mit ein paar Klicks erleben neue Mitarbeiter Wellen des Glücks. Und die gleiche Technik zum Erstellen und Versenden von E-Mails kann zur Verteilung von Informationen verwendet werden, die bei vielen anderen Jobs generiert werden. Ist das nicht eine schöne Sache?