Powershell i zapytania do GraphAPI

W poprzednich wpisach poruszałem temat jak wzbogacić skrypty Powershella o interfejs graficzny. W tym wpisie skupie się na pokazaniu w jaki sposób odczytywać, czy modyfikować dane z chmury Microsoft 365 za pośrednictwem Graph API.

Zanim jednak przejdziemy do mięsa warto w kilku słowach napisać co to jest ten cały Microsoft Graph API. Jest to nic innego jak interfejs programowania aplikacji, który umożliwia dostęp do danych i funkcji w ekosystemie chmurowym Microsoft (np. Entra ID, Outlook, Teams, OneDrive, Sharepoint, itp.). Domyślnym klientem umożliwiającym dostęp do GraphAPI jest Graph Explorer, dostępny tutaj.

Domyślnie po wejściu na stronę pracujemy na tenancie testowym, po zalogowaniu można wykonywać działania na „swoich” danych. Jest to dobra opcja na start do nauki i obycia się z tym narzędziem. Po lewej stronie mamy dostęp do przykładowych zapytań z różnych kategorii.

Przejdźmy zatem do Powershella. W tym wpisie pokażę 2 metody, z użyciem dedykowanego modułu, oraz w jaki sposób można sobie poradzić bez niego.

Dedykowany moduł Microsoft.Graph

W pierwszej kolejności zainstalujemy moduł Microsoft.Graph za pośrednictwem polecenia

Install-Module Microsoft.Graph

Po instalacji wystarczy nawiązać połączenie z usługą GraphAPI za pomocą polecenia

Connect-MgGraph

Zalogować się do konta Entra ID

I po poprawnym logowaniu, możemy korzystać z możliwości GraphAPI.

Korzystając z dedykowanego modułu mamy zasadniczo dwie opcje:

• Korzystać w wbudowanych poleceń, np. Get-MgUser – do odczytania danych o użytkownikach
• Lub użyć uniwersalnego polecenia – Invoke-MgGraphRequest, jednak po tym musimy samodzielnie uzupełnić to polecenie o adres uri oraz metodę.

Aby osiągnąć taki sam efekt za pomocą obu sposobów polecenia wyglądają następująco:

Get-MgUser -All

(Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/v1.0/users").Value

Uwaga! Korzystanie z tego dodatku jest konfigurowalne (przypisanie użytkowników, uprawnienia) z dedykowanej aplikacji dla przedsiębiorstw w Entra ID: Microsoft Graph Command Line Tools.

Domyślne polecenie Invoke-WebRequest

Czyli jak użyć GraphAPI bez konieczności instalowania modułu. I w tym przypadku trzeba wykonać kilka kroków przygotowawczych, aby dojść do tego samego efektu, co w metodzie powyżej. Ze względu, że w tej metodzie nie można użyć wieloskładnikowego logowania, ba nawet modern authentication, które jest wymagane do autentykacji w GraphAPI. Aby zatem się poprawnie zalogować, użyje tokenu.

W tym celu trzeba zarejestrować nową aplikację i wygenerować Client Secret (po polsku przetłumaczone jako tajny wpis klienta 😊 )

Po rejestracji aplikacji potrzebne będzie parametr Application (client) ID

Następnie przechodząc do menu Certificates and Secrets, wygenerujmy nowy Secret

Wszystko gotowe, przejdźmy zatem do Powershella i oto kawałek skryptu, który jest odpowiedzialny za generowanie tokenu

$body = @{
    client_id = "d1cf1181-7cf4-42cb-b04a-b024e475e2c7"
    client_secret = "VPk*************************************"
    scope = "https://graph.microsoft.com/.default"
    grant_type = "client_credentials"
}

$token = Invoke-WebRequest -Uri "https://login.microsoftonline.com/3df45973-ceda-4187-9d42-b3e6e88898a3/oauth2/v2.0/token" -Body $body -ContentType "application/x-www-form-urlencoded" -Method Post -UseBasicParsing

$access_token = ($token.Content | ConvertFrom-Json).access_token

No i na dokładkę, aby uzyskać podobny efekt z modułu powyżej

$header = @{
    Authorization = "Bearer $access_token"
}

$request = Invoke-WebRequest -Uri "https://graph.microsoft.com/v1.0/users" -Method Get -Headers $header #-ContentType "application/json"

($request.content | ConvertFrom-Json).Value

Podsumowując oba sposoby łączenia się z użyciem Powershella do GraphAPI to każda w innych zastosowaniach sprawdza się lepiej. Użycie dedykowanego modułu i jego komend sprawdza się do użycia w kontekście interaktywnej pracy, a znowu logowanie tokenem będzie wygodniejsze w momencie pisania automatycznych skryptów, które działają w sposób nienadzorowany.