A Microsoft Graph SDK for PowerShell használata az Azure Automation szolgáltatással

A Runbookoktól az e-mailig

Az Azure Automation-fiókok és runbookok Exchange Online-felügyeleti PowerShell-modullal való használatáról szóló korábbi cikkben, abban a cikkben azt is elmagyaráztam, hogyan használhatja a Graph API-lekérdezéseket egy runbookban végrehajtott PowerShell-szkriptben. A természetes következő kérdés az, hogy megkérdezzük, hogy a Microsoft Graph PowerShell SDK támogatja-e a runbookokat. Jelenthetem, hogy az SDK használható az Azure Automationnal tanúsítványalapú hitelesítés vagy felügyelt identitások használatával. Természetesen egy egyszerű kijelentés sok bonyolultságot rejthet, ezért nézzük meg a részleteket.

A lehetséges gyakorlati példájaként ebben a cikkben úgy alakítom át a szkriptet, hogy e-maileket küldjön az itt leírt új postafiókokba, hogy a futtatható egy runbookban futhasson.

Azure Automation Setup

Amint azt az előző cikkben tárgyaltuk, egy Azure Automation-fiókot használunk (amely egy Azure-előfizetéshez van kötve) a szkript futtatásához egy sandbox-kiszolgálón. Az Azure Automation támogatja a felügyelt identitásokat, és egy későbbi cikkben kitérek erre a témára. Egyelőre a jól bevált technika teszi a dolgát.

Frissítés: Az Azure Automation már nem támogatja a Runbook-fiókokat. Használjon helyette felügyelt identitást. További információért tekintse meg ezt a cikket. A modulok automatizálási fiókba való betöltésére és a Graph engedélyek automatizálási fiókokhoz való hozzárendelésére vonatkozó itt ismertetett elvek továbbra is érvényesek.

Grafikonmodulok importálása

A RunAs-fióknak van egy egyszerű szolgáltatása és egy Azure által kezelt tanúsítványa. Ezek a hitelesítéshez használt kulcselemek. A hitelesítés azonban csak a kezdet. Ahhoz, hogy a Microsoft Graph PowerShell SDK elérhetővé váljon egy runbook számára, megosztott erőforrásként importálnunk kell a moduljait az automatizálási fiókba.

Észreveheti, hogy modulokat használtam, nem modult. Ha letölti a Microsoft Graph PowerShell SDK-t a PowerShell galériából, és telepíti egy munkaállomásra, egyetlen modult sem kap. Ehelyett az SDK számos különböző modulra oszlik, amelyek mindegyike a teljes Graph-környezet egy kis részét képezi. Amikor az SDK-t automatizálási fiókba importálja, importálnia kell a parancsfájlhoz szükséges modulokat. Az első feladat az, hogy ellenőrizze a használni kívánt parancsmagok dokumentációját, hogy megtudja, melyik modulban találhatók az egyes parancsmagok.

Tegyük fel például, hogy a szkript a Get-MgOrganization parancsmagot használja a bérlő adatainak visszaadásához. A Microsoft dokumentációja szerint a parancsmag a Microsoft.Graph.Identity.DirectoryManagement modulhoz tartozik (1. ábra).

Mellékesen hadd mondjam el, hogy az SDK-parancsmagok dokumentációja borzasztó példa arra, hogy a mesterséges intelligencia néha miért nem működik olyan jól, amikor forráskódon alapuló dokumentációt készítenek. A dokumentáció javítása segítené az embereket az SDK-parancsmagok jobb megértésében, és ösztönözné azok használatát. Egyelőre alapos értelmezésre és nagy türelemre van szükség.

SDK-modulok betöltése az Azure Automation-fiókba

Miután ellenőriztem a szkriptet, hogy megtaláljam az összes SDK-parancsmagot, végül négy modult importáltam (2. ábra):

Microsoft.Graph.Authentication: a Graphon való hitelesítéshez.
Microsoft.Graph.Users.Action: üzenet küldése.
Microsoft.Graph.Mail: az e-mail üzenetek eléréséhez.
Microsoft.Graph.Identity.Management: a szervezeti adatok lekéréséhez.

Grafikon engedélyek hozzárendelése

Az SDK-modulok betöltése a grafikonnal való interakcióhoz elindít minket: az ehhez szükséges engedélyekkel teljes a kör. Ha a Connect-MgGraph parancsmag használatával csatlakozik, a létrehozott munkamenet bizonyos Graph-engedélyeket használhat. Ez a munkamenet hatóköre. Ebben az esetben a szkriptnek hozzá kell férnie a felhasználó postafiókjához, hogy üzenetet hozzon létre, mielőtt elküldi azt az üzenet címzettjeinek, így a hitelesítéshez használt entitásnak rendelkeznie kell a Graph alkalmazás engedélyével, amely szükséges ezen műveletek végrehajtásához. Az entitás a RunAs-fiók egyszerű szolgáltatása. Mielőtt a szkript e-mailt küldhetne, a rendszergazdának beleegyezését kell adnia ahhoz, hogy a szolgáltatás vezetője Mail.Send és Mail.ReadWrite engedélyekkel rendelkezzen.

Az engedélyek hozzárendelése a RunAs-fiók egyszerű szolgáltatásához ugyanaz, mint egy regisztrált alkalmazáshoz való engedélyek hozzárendelése. Nyissa meg az Azure AD felügyeleti központot, keresse meg a szolgáltatás egyszerű nevét a regisztrált alkalmazások készletében, adja hozzá a szükséges engedélyeket, és adja meg a hozzájárulást a szervezet nevében. A 3. ábrához hasonlót kell kapnia. Két extra Graph-engedély van jelen, mert az előző cikkben ezt a szolgáltatási tagot használtam.

Ügyeljen arra, hogy ne hozzon létre egyszerű szolgáltatást túl sok Graph-engedéllyel. A Microsoft Graph PowerShell SDK-val folytatott interaktív munkamenetekhez használt egyszerű szolgáltatáshoz hasonlóan az egyszerű szolgáltatási tagok is könnyen halmozhatnak engedélyeket az idő múlásával, ha több feladathoz használják. A gyártás során fontolja meg külön automatizálási fiókok használatát a különböző munkákhoz.

A PowerShell kód módosítása

Mostantól rendelkezünk egy RunAs fiókkal a megfelelő jogosultságokkal és hozzáféréssel a szükséges modulokhoz, így ideje írni egy kódot. Egy működő szkript áll rendelkezésre kiindulási pontként, de módosítani kell, hogy a runbookban működjön. Íme, amit csináltam:

Először is hozzáadtam egy új hitelesítési részt, hogy megkapjam a tanúsítvány ujjlenyomatát az automatizálási fiókból. A tanúsítvány ezután hitelesíti a kapcsolatot a Microsoft Graphhoz.

$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

Ezután lekértem a bérlői szolgáltatási tartományt, és ugyanazzal a tanúsítvány ujjlenyomatával együtt használtam az Exchange Online-hoz való csatlakozáshoz (a nemrég hozzáadott postafiókok lekéréséhez).

$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

Ne feledje, hogy az automatizálási fióknak bizonyos engedélyekre van szüksége az Exchange Online-hoz való csatlakozáshoz. Ezeket az engedélyeket előző cikkemben ismertetem.

Ezután meghatároztam, hogy kitől származik az üzenet (a postafiók, amelyet használni akarok). Amikor interaktívan futtatom a szkriptet, lekérem ezeket az információkat a jelenleg a PowerShellhez csatlakoztatott fiókból, de ez nem működik RunAs-fiók esetén, ezért meg kell határoznunk a fiók SMTP-címét egy változóban.

$MsgFrom = "WelcomeNewUsers@Office365itpros.com"

A szkriptem egy helyi meghajtón tárolt üdvözlő levelet csatol. Nyilvánvaló, hogy egy homokozóban futó szkript nem fér hozzá a helyi meghajtómhoz, ezért ehelyett letöltöm az üdvözlőlevelet egy webhelyről, és egy helyi mappában tárolom. A szkript ezután kódolja a tartalmat, hogy lehetővé tegye a fájl csatolását az üzenethez.

$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))

Végül. A Write-Host segítségével eltávolítottam a képernyőre küldött üzeneteket. Nincs értelme ezeket az üzeneteket kiadni, mert nincs olyan képernyő, amelyen megjelennének, amikor a kód fut egy runbookban.

Megérkeznek az üzenetek

És ennyi. Az előkészítő munka elvégzése után a folyamat nem nehéz. A kód lefut, mert az összes szükséges modul elérhető a fiókban, és a fiók rendelkezik a megfelelő Graph jogosultságokkal, így a levelek az új felhasználók postafiókjaiba áramlanak (4. ábra).

Letöltheti az általam használt teljes szkript másolatát a GitHubról.

Szép az automatizálás

Az Azure Automation használatában az a szép dolog, hogy közzéteheti a szkriptet, majd ütemezheti heti futtatását, hogy üdvözlő üzeneteket küldjön azoknak a felhasználóknak, akik az előző héten csatlakoztak. Néhány kattintással az új csatlakozók boldogsághullámokat kapnak. Az e-mailek létrehozásának és küldésének ugyanaz a technikája pedig sok más munka által generált információ terjesztésére is használható. nem szép dolog?