Automatizace skriptů PnP PowerShell – Azure Automation

Miroslav Šraga — Mon, 22 Apr 2024 15:04:50 +0000

Dnes mám pro vás kompletní návod, jak zprovoznit automatické spouštění skriptů v rámci PnP PowerShellu (PnP.PowerShell module), bez nutnosti přihlašování konkrétního uživatele. Co k tomu bude potřeba?

Předplatné Microsoft Azure
Automation Account
Managed Identity
PnP PowerShell nainstalovaný lokálně ve vašem počítači

Proč Azure Automation a ne lokální skripty

Dovedu si představit, že nikdo nechce provádět reporty ručně. Důvodů, proč takovou věc automatizovat vidím hned několik:

Nechci se o spouštění reportů starat a nebo delegovat to na jiné uživatele
Nechci uživatelům udělovat oprávnění a vytvářet prostor pro chybu nebo zneužití
Chci si hlídat úroveň oprávnění, kteoru jednotlivým úkonům uděluji, pokud skript pracuje jen se SharePointem, nechci udělovat oprávnění na jinou komponentu systému, třeba na Planner a podobně
Chci mít nad systémem kontrolu a chci mít přehled o tom, jak jednotlivé úlohy dopadly. Nechci spoléhat na to, že delegovaný uživatel daný úkon provede
S ohledem na přechozí body, nechci takovou věc obecně vůbec spouštět v kontextu uživatele, který má uživatelské jméno a heslo a lze se k němu jednouše přihásit, chci nějakou formu systémového účtu

Ruční spouštění skriptů je dobré tam, kde potřebujete jednorázový export nebo report. Pokud ale potřebujete reporty pravidelně, dříve či později se budete snažit skripty automatizovat. První, o co se budete pokoušet, jak skript spustit pomocí plánovače, třeba Task Scheduleru a jak jej spustit pod oprávněním konkrétního uživatele, nejprve to budete zkoušet pod svým účtem, později možná, v lepším případě, vytvoříte servisní účet, kterému třeba i budete muset pořídit licenci. A když nemáte rozpočet, skončí to tak, že skrip, pokud se to vůbec podaří nasadit, bude běžet pod vaším účtem do doby, než z organizace odejdete a možná i po té.

Z výše uvedeného plyne, že daleko rozumnější je použít „nějakou formu“ účtu, který není uživatelem. Ve světe Microsoftu se tomu říká Managed Identity. A pokud se tato identita dá rovnou zkombinovat s procesem, který bude skritpy pravidelně spouštět (Automation Accounts), tak máte pohodlné a bezpečené řešení.

Azure Automation Account je služba, poskytovaná prostřednictvím Microsot Azure, která umožňuje automatizovat a plánovat různé úkoly a procesy v rámci vašeho prostředí Azure a ale mimo něj.

Vytvoření Azure Automation Account

Na portále pro správu Microsoft Azure si najděte (1) službu Automation Accounts (2) a zvolte vytvořit nový účet (3).

(4) Vyberte, do kterého předplatného chcete automatizaci nasadit. Toto je důležité, protože se jedná o sice levnou, ale zpoplatněnou službu.

(5) Zvolte, do jaké skupiny prostředků chcete službu přiřadit nebo vytvořte novou Resource group. Já vytvářím novou Resource Group s názvem „automation-rg“ a do této skupiny budu do budoucna dávat všechny prostředky, které se týkají automatizace.

(6) Zvolte název pro automatizační účet. Tady pozor, budeme vytvářed také takzvadnou Spravovanou Identitu, která je v Entra ID reprezetována jako Enteprise aplikace s tímto názvem, tak zvolte takový název, abyste se v tom potom vyznali. Já dávám na konec názvu suffix „aa“ jako automation account.

(7) Jako region vyberu West Europe, ale vy si samozřejmě zvolte region dle vašich preferencí. Teď je hodně populární třeba Polsko.

Pokračujte kliknutím na tlačítko Next.

V dalším kroku se průvodce ptá, za chci vytvořit Managed Identity a mám na výběr System assigned a User Assigned.

V tomto případě zvolím System assigned (8) a jdu na další kroky.

Azure Managed Identity je služba, která poskytuje automaticky (systémem) spravovanou identitu v Microsoft Entra ID pro aplikace, které se používají pro připojení k prostředkům, které podporují autentizaci vůči Microsoft Entra. Výhodou je, že nemusíte nijak spravovat hesla, pověření, certifikáty nebo klíče, které se jinak používají k zabezpečení komunikace mezi službami. Funguje to tak, že Aplikace využije tuto Managed Identity k získání tokenu Microsoft Entra bez nutnosti řešit jakékoliv pověření. Velmi jednoduše řečeno, jedná se o systémový účet.

Následující krok se týká Networkingu. Máte možnost zvolit si, zda li chcete k prostředkům přistupovat privátně (z vnitřní sítě) nebo pomocí veřejného internetu.

Privátní přístup – tato možnost poskytuje Automation Accountu privátní koncový bod (Private endpoint), který používá privátní IP adresu z vaší virtuální sítě. Povolením privátního koncového bodu přenesete službu do své virtuální sítě. Jedná se o doporučenou konfiguraci z hlediska zabezpečení; vyžaduje však konfiguraci Hybrid Runbook Worker připojeného k virtuální síti Azure a v současné době nepodporuje cloudové úlohy.

V mém případš tedy zvolím Public access a přejdu na další krok.

V produkčním prostředí doporučuju věnovat pozornout Tagům a pro přeheldnost tagy používat. Já osobně do tagů běžně dávám tyto informace:

Prostředí: produkční / testovací
Business owner – kdo konzumuje výslednou službu
Technical owner – kdo se o službu stará technicky
Nekdy případně ještě třeba středisko, oddělení, nákladové středisko apod.

Pokračuji dál na poslední část průvodce a to je Validace.

Pokud validace prošla, klikněte na tlačítko Vytvořit, pokud neprošla, opravte chyby.

Je potřeba počkat, než se celá služba nasadí. Až bude hotovo, lze přejít na detail služby.

Instalace PowerShell modulu: Pnp.PowerShell

Protože potřebujeme pracovat s PnP Powershell Modulem, musíme jej do automatizace nejprve přidat, protože není její nativní součástí.

V levém menu přejděte do sekce Modules (9) a klikněte na tlačítko Přidat modul (10)

PnP.Powershell sice není nativní součástí Automation Accounts, ale je k dispozici v Galerii, takže vyberte Browse fom gallery (11) a otevřete galerii pomocí odkazu Click here to browse from gallery (12).

Do vyhledávcího okna zadejte „PnP„. Těch modulů, které se nabízí je hned několik.

Klikněte na ten s názvem PnP.PowerShell (13).

V dalším okně jen potvrďte výběr modulu, kliknutím na tlačítko Select (14).

Systém vás vrátí do původního okna. Pro správný chod modulu, zvolte Runtime version: 7.2 (15).

Pokračujte kliknutím na tlačítko Import (16).

Teď nastává chvíle čekání, protože je potřeba počkat, až se modul naimportuje, což může trvat klidně i 10 minut. Tento proces nejde urychlit a musí se vyčekat.

Ze začátku ten modul vůbec nebude vidět v seznamu, pak se objeví se stavem Importing a nakonec se jeho stav změní na Available.

Managed Identity / Entra ID Enterprise application

Když je PowerShell modul naimportovaný, lze přejít do sekce Identity.

Zkontrolujte, že je u System Assigned identity stav „Zapnuto“ a rovnou si můžete zkopírovat Object ID, což je zároveň Client ID Enterprise aplikace, které se zaregistrovala v Entře.

Ještě si pro kontrolu otevřete entra.microsoft.com a přejděte do Enterpeise Applications (19) a upravte si filtr zobrazení, případně použijte vyhledávání (20).

Měla by se nabídnout aplikace, kterí bude mít stejný název, jako nově vytvořený Automation Account.

Pokud jste instalovali také lokální modul PnP PowerShellu a udělili jste této aplikaci tzv. Consent, tak uvidíte v seznamui také aplikaci, která se jmenuje PnP Management Shell. To je aplikace, kterou jsem zaregistroval automaticky při instalaci PnP modulu do svého počítače.

Když aplikaci otevřete a přejdete do sekce Permissions (21), uvidíte, že aplikace zatím nemá žádná oprávnění. Stránka s přidělenými oprávněními, je prázdná.

Udělení oprávnění pro Managed Identity (Enterprise application)

Azure Portál a Entra ID necháme chvíli stranou.

Teď je potřeba vytvořené identitě, která je reprezentovaná v Entra ID prostřednictvím Enterprise aplikace, přidělit oprávnění.

K zamyšlení doporučuji, se nejprve zamyslet, jaká práva je potřeba té aplikaci udělit.

Pokud registrujete aplikace na svém počítačí při instalaci PnP modulu, tak tento modul si udělí sám veškerá potřebná oprávnění (po schválení Globálním správcem). My jsme ale v situaci, kdy nechceme, aby náš automatizovaný skript, měl práva úplně na vše, ale jen na konkrétní úkony. Třeba jen pro práci s Plannerem, nebo s Entrou nebo se SharePointem a třeba jen ke čtení.

Abych mohl práva přidělit, musím vědět, co má skript dělat, kam potřebuje sahat a také, jak ta oprávnění identifikovat v systému.

Nyní je tedy potřeba se přesunout do lokálního prostředí a spustit si prostředí PowerShell verze 7.

Předpokládejme, že víte, co má Váš automatizovaný skript dělat a jaká potřebuje oprávnění, ale nevíte, jak oprávnění fakticky přidělit.

K tomu zde mám sadu několika příkazů, kterými si lze trochu pomoci.

1. Nejprve se připojde k PnP pomocí příkazu Connect-PnPOnline

Já už rovnou přidávám i parametru -Url, protože se chci připojik ke konkrétní knihovně, nad kterou mohu dělat další testy.

Connect-PnPOnline -Url "https://sragacz.sharepoint.com/sites/Kvalitaabazpenost" -Interactive

2. Pomocí příkazů níže, lze identifikovat, jaká konkrétní oprávnění lze Enteprise Aplikaci udělit. Parametr -BuiltInType identifikuje, o jakou komponentu nebo službu se jedná, například MicrosoftGraph nebo SharePointOnline. Analogicky si lze vypsat dostupná oprávnění pro jakoukoliv komponentu ekosystému Microsoft 365.

Get-PnPAzureADServicePrincipal -BuiltInType MicrosoftGraph | Get-PnPAzureADServicePrincipalAvailableAppRole
Get-PnPAzureADServicePrincipal -BuiltInType SharePointOnline | Get-PnPAzureADServicePrincipalAvailableAppRole

Výstupem z uvedených příkazů je seznam dostupných oprávnění pro danou komponentu. Přičemž důležité jsou tyto hodnoty:

Value – identifikátor daného oprávnění. Tato hodnota se používá v dalších příkazech
DisplayName – název oprávnění, který je reprezentován zejména v Entra ID v sekci Permissions
Description – popis toho, co dané oprávnění umožňuje

Pokud umíte identifikovat všechna potřebná oprávnění, je na čase oprávnění udělit.

Budete potřebovat Object ID vytvořené Enterprise aplikace. Toto získáte v sekci Identity v detailu Automation Accountu (krok 18) a nebo v detailu Enterprise aplikace.

Pro udělení oprávnění požijte příkaz Add-PnPAzureADServicePrincipalAppRole

Add-PnPAzureADServicePrincipalAppRole -Principal "4e9d609b-f963-xxxx-xxxx-f03bf038ec4d" -AppRole "User.ReadWrite.All" -BuiltInType MicrosoftGraph
Add-PnPAzureADServicePrincipalAppRole -Principal "4e9d609b-f963-xxxx-xxxx-f03bf038ec4d" -AppRole "Sites.FullControl.All" -BuiltInType SharePointOnline

Parametr AppRole obsahuje hodnotu Value, kterou jsme získali pomocí předchozího příkazu (identifikátor oprávnění)

Parametr BuiltInType identifikute danou komponentu / službu.

Parametr Principal obsahuje Object ID Enterprise aplikace, nebo její název, doporučuji ale používat Object ID.

Výsledek operace lze snadno zkontrolovat v Entra ID, konkrétně v detailu Enterprise aplikace, v sekci Permissions. V detailu aplikace by měla být vidět jen tak oprávnění, která byla udělena v předchozích krocích.

Vytvoření skriptu [Runbooks]

Řekněme, že máme rámcově přidělená oprávnění, která pro skript potřebjeme. Zbývá tedy vůbec ten skript vytvořit. A k tomu použijeme tzv. Runbook.

Runbooks Rubbooky jsou knihovny, založené na prostředí Windows PowerShell (nebo Python, ale o tom jindy). Kód runbooku můžete upravovat přímo pomocí textového editoru na Azure portálu. Můžete také použít libovolný offline textový editor a skripty do Azure Automation importovat.

Vraťte se na Azure portál a v detailu Automation Accountu přejděte do nabídky Runbooks (22). Pro vytvoření nového Runbooku klikněte na tlačítko „Create a Rubnook“ (23).

Runbooky jsou vlastně skripty, nebo knihovy skriptů, které chci spouštět, ať už ručně nebo automaticky.

V následující kroku vyplňte všechna povinná pole (24).

Jako typ zvolte: Powershell
Runtive version: 7.2
Description: doporučuji používat popisy, aby se ve skriptech vyznali i ti, kteří přijdou po vás.

Pokud jste vše vyplnili správně, Vytvořte runbook (25).

Runbook je vytvořený. Nyní můžete vytvořit Váš skript (24).

Jakmile máte skript připravený, můžete jej otestovat kliknutím na tlačítko Test pane (25).

V následující okně je potřeba skript ještě spustit pomocí tlačítka Start (26).

Po té, co sktipt doběhne, zobrazí se informace „Completed“ a v okne budou zobrazeny výstupy skriptu. Pokud skript žádné výstupy nemá, bude okno prázdné.

Po dokončení testování je možné okno zavřít křížkem v pravé horní části okna.

Všechny úpravy je potřeba vždy uložit kliknutím na tlačítko Publish. Pokud změny tzv. nepublikujete, bude platná vždy předchozí verze skriptu.

Pokud se s prostředím Azure a PnP teprve seznamujete, chcete si výstupy vyzkoušet a ještě nemáte vlastní skripty, můžete použít příkazy níže, které jsou zcela nezávadné.

První příkaz načte informace o SharePoint webu a další dva se postarají o výpis administrátorů Site Collection. Pro ověření funkčnosti Automation Accountu a pochopení principů to stačí.

Upozornění Všimněte si, že u příkazi Connect-PnPOnline je použit parametr -ManagedIdentity, ktežto když spouštíte stejný příkaz lokálně z počítače, používáte parametr -Interactive

Connect-PnPOnline -Url "https://sragacz.sharepoint.com/sites/Kvalitaabazpenost" -ManagedIdentity

$Web = Get-PnPWeb 
$Web 

$SiteAdmins = Get-PnPSiteCollectionAdmin 
$SiteAdmins 

$SiteCollectionAdmins = ($SiteAdmins | Select -ExpandProperty Title) -join "," 
$SiteCollectionAdmins

Pravidelné spouštění skriptů (runbooků)

Když jsou skripty funkční, zbývý poslední fáze. Určitě chcete, aby se skript spouštěl pravidělně. Takže v levém menu přejděte na Schedules (27) a přidejte nový časový plán (28).

V dalším okně je potřeba „napárovat“ daný Rubnook na časový plán. Klikněte na Link a schedule to your runbook (29).

Pozn.: Lze jít také cestou, že si nejprve vytvoříte časové plány na úrovni Automation Accountu a nikoliv zde v detailu Rubnooku.

Přidejte nový časový plán (30)

V pravém okně vyplňte (31) název časového plánu, já mám v příkladu „Denně“, protože pro ukázku nastavím opakující se denní spouštění skriptu. Určitě opět doporučuji vyplňit také popis.

Zvolte datum a čas prvního spuštění a také časovou zónu, pro kterou jsou časy platné.

Pro pravidelné opakování přepněte přepínač Recurrence (32) do polohy Recurring.

Následně zvolte četnost opakování a případný konec opakování (Set expiration).

Pokud jsou všechny údaje v pořádku, klikněte na tlačítko Vytvořit (33).

Systém na pozadí vytvoří časový plán. V tomto kroku stačí potvrdit napárování Rubnooku na právě vytvořený časový plán, kliknutím na tlačítko OK.

Vytvořený časový plán se zobrazí v seznamu Schedules v detailu Runbooku.

Pokud si chcete prohlédnout historii spuštění rubnooku, přejděte v levém menu do sekce Jobs. Zobrazí se seznam všech spuštění, jejich stav a poslední aktivita. Po rozkliknutí konkrétního jobu jsou také k dispozici servisní informace, výstupy sktiptu a logy.

Managed Identity – Miroslav Šraga