Zaawansowane wykorzystanie przepływu tożsamości zarządzanej w PowerShell i Microsoft Graph

By Mirko Peters · 2026-08-28

Witamy ponownie na blogu do podcastu! Jeśli kiedykolwiek irytowało Cię wpisywanie haseł na sztywno, zarządzanie uciążliwymi kluczami tajnymi klienta albo martwienie się o wyciek poświadczeń w skryptach…

Automatically translated with AI from the original post. Read the English original

Witamy ponownie na blogu do podcastu! Jeśli kiedykolwiek irytowało Cię wpisywanie haseł na sztywno, zarządzanie uciążliwymi kluczami tajnymi klienta albo obawy o wyciek poświadczeń w skryptach automatyzacji, trafiłeś we właściwe miejsce. Automatyzacja w chmurze wymaga zmiany sposobu myślenia o bezpieczeństwie. Minęły czasy, gdy administratorzy mogli spokojnie przechowywać poświadczenia w plikach konfiguracyjnych w postaci jawnego tekstu albo w zmiennych środowiskowych, nie oglądając się przez ramię. Dziś zagłębimy się w świat uwierzytelniania natywnego dla chmury i pokażemy, jak w skryptach PowerShell wykorzystać tożsamości zarządzane platformy Azure do bezpiecznego uwierzytelniania w Microsoft Graph bez przechowywania wrażliwych poświadczeń.

Automatyzacja środowiska Microsoft 365 nie jest już tylko przydatną umiejętnością, lecz absolutną koniecznością operacyjną. Połączenie PowerShell z interfejsem Microsoft Graph API potrafi jednak przypominać labirynt monitów o uprawnienia, limitów przepustowości i złożonych przepływów pobierania tokenów. Dzięki przyjęciu nowoczesnego, opartego na tożsamości podejścia możemy całkowicie wyeliminować zarządzanie poświadczeniami dla obciążeń działających w platformie Azure. W tym wpisie omówimy podstawowe składniki uwierzytelniania natywnego dla chmury, prowadząc Cię przez wymagania wstępne, rejestracje aplikacji w Azure AD, przepływy pobierania tokenów oraz optymalizację skryptów. Jeśli chcesz zgłębić ten konkretny przepływ pracy, koniecznie posłuchaj naszego towarzyszącego odcinka podcastu: Use Managed Identity with PowerShell for Microsoft Graph.

Wymagania wstępne dla PowerShell i Graph API

Zanim zaczniesz automatyzować zadania Microsoft 365 za pomocą PowerShell i Graph API, musisz odpowiednio przygotować system i środowisko. Ta preparacja zapewnia płynne wykonywanie i bezpieczny dostęp do zasobów Microsoft Graph.

Instalacja modułów PowerShell

Aby współpracować z interfejsem Microsoft Graph API, musisz zainstalować odpowiednie moduły PowerShell. Zestaw Microsoft Graph PowerShell SDK udostępnia wszystkie niezbędne cmdlet-y do tej integracji. Aby uniknąć błędów, sprawdź, czy Twój system spełnia następujące minimalne wymagania:

Możesz zaktualizować PowerShellGet, uruchamiając polecenie Install-Module PowerShellGet -Force, a zasady wykonywania ustawić poleceniem Set-ExecutionPolicy RemoteSigned. Następnie zainstaluj moduł Microsoft Graph za pomocą:

Install-Module Microsoft.Graph -Scope CurrentUser

To polecenie pobiera najnowszą stabilną wersję modułu, co pozwala łatwo wywoływać punkty końcowe Microsoft Graph.

Konfiguracja środowiska Microsoft 365

Prawidłowa konfiguracja środowiska Microsoft 365 ma kluczowe znaczenie dla automatyzacji. Aby rozpocząć, wykonaj następujące kroki:

1. Upewnij się, że system spełnia wymagania: PowerShell 7.2 lub nowszy, .NET Framework 4.7.2 lub nowszy oraz najnowszy moduł PowerShellGet.
2. Zainstaluj moduł Microsoft Graph PowerShell, jak pokazano powyżej.
3. Połącz się z dzierżawą Microsoft 365, importując moduł i uwierzytelniając się z wymaganymi zakresami. Na przykład:

Connect-MgGraph -Scopes "User.ReadWrite.All","Directory.ReadWrite.All"

To polecenie wyświetla monit o zalogowanie się i przyznaje Twojej sesji uprawnienia do odczytu i zapisu danych użytkowników oraz katalogu. Zakresy możesz dostosować do potrzeb swojej automatyzacji.

Zrozumienie uprawnień i zakresów

Uprawnienia i zakresy określają, do czego Twoje skrypty mogą uzyskać dostęp lub co mogą modyfikować w Microsoft 365. Interfejs Microsoft Graph API wykorzystuje dwa główne typy uprawnień:

• Uprawnienia delegowane: Mają zastosowanie, gdy skrypty działają w imieniu zalogowanego użytkownika. Ograniczają dostęp do danych, których użytkownik jest właścicielem lub do których ma dostęp.
• Uprawnienia aplikacji: Pozwalają aplikacji lub skryptowi uzyskać dostęp do danych w całej organizacji bez zalogowanego użytkownika, co jest typowe dla zautomatyzowanych procesów działających w tle oraz przepływów z wykorzystaniem tożsamości zarządzanej.

Do często spotykanych uprawnień należą *.Read.All, zapewniające dostęp tylko do odczytu, oraz *.ReadWrite.All, dające pełne możliwości odczytu i zapisu. Na przykład SecurityActions.Read.All pozwala wyświetlać działania zabezpieczające, a SecurityActions.ReadWrite.All umożliwia ich modyfikowanie.

Uprawnienia aplikacji wymagają zgody administratora. Administrator dzierżawy musi zatwierdzić te uprawnienia, aby zapewnić bezpieczeństwo. Ponadto użytkownicy potrzebują odpowiednich ról w Microsoft Entra, takich jak Czytelnik zabezpieczeń, aby uzyskać dostęp do danych wrażliwych. Ten dostęp oparty na rolach stanowi dodatkową warstwę zabezpieczeń.

Podczas łączenia się za pomocą zestawu Microsoft Graph PowerShell SDK określ tylko te zakresy, których potrzebuje skrypt. Takie podejście jest zgodne z zasadą najmniejszych uprawnień i zmniejsza ryzyko bezpieczeństwa. Pamiętaj, że uprawnienia przyznane Twojej aplikacji dotyczą wszystkich użytkowników tej aplikacji, dlatego regularnie je przeglądaj i zarządzaj nimi.

Tożsamość aplikacji w Azure AD

Rejestrowanie nowej aplikacji

Aby zautomatyzować zadania Microsoft 365 za pomocą PowerShell i interfejsu Graph API, najpierw musisz zarejestrować aplikację w Azure Active Directory (Azure AD). Ta aplikacja działa jako tożsamość, której Twoje skrypty używają do bezpiecznego dostępu do Microsoft Graph. Wykonaj poniższe kroki, aby zarejestrować aplikację:

1. Otwórz portal Azure i przejdź do Azure Active Directory > Rejestracje aplikacji > Nowa rejestracja.
2. Nadaj aplikacji znaczącą nazwę, na przykład "My Graph Automation App".
3. Wybierz obsługiwane typy kont:
   • Dzierżawa jednego podmiotu: Logować się mogą tylko użytkownicy z Twojej dzierżawy Azure AD.
   • Wiele dzierżaw: Logować się mogą użytkownicy z dowolnej dzierżawy Azure AD.
   • Wiele dzierżaw i konta osobiste: Obejmuje użytkowników Azure AD oraz osobiste konta Microsoft.
4. Ustaw identyfikator URI przekierowania w zależności od typu aplikacji:
   • W przypadku aplikacji internetowych użyj adresu URL w rodzaju https://yourapp.com/auth/callback.
   • W przypadku aplikacji jednostronicowych użyj https://yourapp.com.
   • W przypadku aplikacji mobilnych lub desktopowych użyj https://login.microsoftonline.com/common/oauth2/nativeclient.
5. Kliknij Zarejestruj, aby utworzyć aplikację.

Ten proces tworzy unikalną tożsamość aplikacji w Twojej dzierżawie. Będziesz jej używać do żądania tokenów i wywoływania interfejsu Microsoft Graph API.

Konfigurowanie uprawnień interfejsu API

Po zarejestrowaniu aplikacji musisz skonfigurować uprawnienia interfejsu API, których ona potrzebuje. Te uprawnienia określają, co aplikacja może odczytywać lub modyfikować w Microsoft 365. Aby ustawić uprawnienia:

1. W rejestracji aplikacji przejdź do Uprawnienia interfejsu API > Dodaj uprawnienie > Microsoft Graph.
2. Wybierz Uprawnienia aplikacji, jeśli skrypt działa bez interfejsu użytkownika lub w kontekście tożsamości zarządzanej, albo Uprawnienia delegowane, jeśli działa interaktywnie.
3. Wybierz konkretne uprawnienia potrzebne aplikacji, na przykład User.Read.All lub Directory.Read.All.
4. Kliknij Dodaj uprawnienia, aby je zastosować.

⚠️ Zawsze stosuj zasadę najmniejszych uprawnień. Przypisuj tylko te uprawnienia, których aplikacja rzeczywiście potrzebuje, aby ograniczyć ryzyko bezpieczeństwa.

Niektóre uprawnienia wymagają zgody administratora, zanim aplikacja będzie mogła z nich korzystać. Zgodę możesz udzielić, klikając Udziel zgody administratora dla [nazwa dzierżawy] w portalu Azure. Regularnie przeglądaj uprawnienia, aby nie przydzielać aplikacji nadmiernych uprawnień.

Generowanie klucza tajnego klienta lub certyfikatu

Twoja aplikacja potrzebuje poświadczeń, aby bezpiecznie uwierzytelniać się w usłudze Azure AD, jeśli nie korzysta z tożsamości zarządzanej. Możesz użyć wpisu tajnego klienta lub certyfikatu. Obie metody potwierdzają tożsamość Twojej aplikacji podczas żądania tokenów.

Aby utworzyć wpis tajny klienta, przejdź do sekcji Certyfikaty i wpisy tajne w rejestracji aplikacji, wybierz Nowy wpis tajny klienta, dodaj opis i ustaw okres ważności. W przypadku certyfikatów prześlij prawidłowy plik certyfikatu w tej samej sekcji.

Pozyskiwanie tokenów dostępu

Zrozumienie OAuth 2.0

OAuth 2.0 odgrywa kluczową rolę w zabezpieczaniu dostępu do interfejsu API Microsoft Graph podczas korzystania z PowerShell + Graph API. Działa jak zaufany strażnik, który pozwala Twoim aplikacjom bezpiecznie się uwierzytelniać i uzyskiwać tokeny dostępu. Tokeny te służą jako cyfrowe klucze, dając skryptom uprawnienia do wywoływania punktów końcowych Microsoft Graph bez bezpośredniego ujawniania poświadczeń.

Aby korzystać z OAuth 2.0, najpierw musisz zarejestrować aplikację w Azure Active Directory (Azure AD). Rejestracja udostępnia poświadczenia klienta, takie jak identyfikator aplikacji oraz wpis tajny lub certyfikat. Gdy skrypt żąda tokenu dostępu, przedstawia te poświadczenia usłudze Azure AD. Azure AD weryfikuje wtedy tożsamość i wydaje token o krótkim czasie ważności. Skrypt dołącza ten token do żądań API, aby potwierdzić, że ma prawo dostępu do żądanych zasobów.

Proces ten zapewnia bezpieczny, kontrolowany dostęp do danych Microsoft 365. Obsługuje także szczegółowe uprawnienia, dzięki czemu skrypty otrzymują wyłącznie niezbędny dostęp. Stosując standardy OAuth 2.0, chronisz swoje środowisko przed nieautoryzowanym dostępem, jednocześnie umożliwiając zaawansowaną automatyzację z PowerShell + Graph API.

Używanie PowerShell do żądań tokenów

Tokeny dostępu można pozyskać, korzystając z kilku przepływów uwierzytelniania dostosowanych do różnych scenariuszy. Każdy przepływ inaczej równoważy bezpieczeństwo i wygodę użytkowania. Interfejs API Microsoft Graph obsługuje następujące popularne przepływy:

• Przepływ kodu urządzenia: idealny dla urządzeń lub skryptów bez przeglądarki i możliwości wprowadzania danych. Uwierzytelniasz się na osobnym urządzeniu, dzięki czemu jest to bezpieczne i przyjazne dla użytkownika.
• Przepływ oparty na certyfikacie: przeznaczony do automatyzacji bez interfejsu użytkownika; zamiast haseł wykorzystuje certyfikaty, zwiększając bezpieczeństwo skryptów działających bez nadzoru.
• Przepływ tożsamości zarządzanej: najlepszy w środowiskach chmurowych, takich jak Azure Functions czy maszyny wirtualne. Ten przepływ wykorzystuje tożsamości zarządzane platformy Azure do uzyskiwania tokenów bez przechowywania wpisów tajnych.

Przepływ kodu urządzenia

Przepływ kodu urządzenia dobrze sprawdza się, gdy uruchamiasz skrypty lokalnie lub na urządzeniach bez wygodnych opcji wprowadzania danych. Pozwala uwierzytelnić się interaktywnie na innym urządzeniu, na przykład w przeglądarce telefonu lub komputera.

Oto, jak możesz użyć przepływu kodu urządzenia w PowerShell:

1. Uruchom poniższe polecenie, aby rozpocząć uwierzytelnianie kodem urządzenia:

   Connect-MgGraph -Scopes "User.Read.All" -DeviceCode

2. PowerShell wyświetla kod i adres URL. Otwórz adres URL w przeglądarce na dowolnym urządzeniu.
3. Wprowadź kod wyświetlony w PowerShell i zaloguj się na swoje konto Microsoft 365.
4. Po pomyślnym uwierzytelnieniu PowerShell uzyskuje token dostępu i łączy sesję.

💡 Przepływ kodu urządzenia równoważy bezpieczeństwo i wygodę. Pozwala uniknąć osadzania poświadczeń w skryptach i sprawdza się przy zadaniach ręcznych lub częściowo zautomatyzowanych.

Przepływ oparty na certyfikacie

Przepływ oparty na certyfikacie najlepiej nadaje się do zautomatyzowanych skryptów działających bez interakcji z użytkownikiem. Zamiast wpisu tajnego klienta używasz certyfikatu, aby potwierdzić tożsamość aplikacji. Ta metoda ogranicza ryzyko związane z wyciekiem wpisów tajnych.

Aby skorzystać z tego przepływu, wykonaj następujące kroki:

1. Zarejestruj aplikację w Azure AD i prześlij certyfikat w sekcji Certyfikaty i wpisy tajne.
2. Przechowuj certyfikat w bezpieczny sposób na komputerze, na którym działa skrypt.
3. Użyj PowerShell, aby zażądać tokenu, podając odcisk certyfikatu, identyfikator klienta i identyfikator dzierżawy.

Poniżej prosty przykład pobrania tokenu z użyciem certyfikatu w PowerShell:

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$certThumbprint = "YOUR_CERT_THUMBPRINT"
$cert = Get-Item Cert:\CurrentUser\My\$certThumbprint
$body = @{
    grant_type = "client_credentials"
    client_id = $clientId
    scope = "https://graph.microsoft.com/.default"
    client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    client_assertion = New-JwtToken -Certificate $cert -TenantId $tenantId -ClientId $clientId
}
$tokenResponse = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -Body $body
$accessToken = $tokenResponse.access_token

⚠️ Zarządzanie certyfikatami wymaga ostrożności. Chroń klucze prywatne i regularnie rotuj certyfikaty, aby utrzymać bezpieczeństwo.

Przepływ z tożsamością zarządzaną

Przepływ z tożsamością zarządzaną sprawdza się najlepiej, gdy uruchamiasz skrypty PowerShell i Graph API w usługach Azure, takich jak Azure Virtual Machines, Azure Functions czy Azure Automation. Azure automatycznie przypisuje tożsamość do zasobu, dzięki czemu nie musisz ręcznie zarządzać poświadczeniami.

Aby uzyskać token dostępu przy użyciu tożsamości zarządzanej, wykonaj następujące kroki:

1. Włącz tożsamość zarządzaną (przypisaną systemowo lub przypisaną przez użytkownika) w swoim zasobie Azure.
2. Przypisz niezbędne uprawnienia Microsoft Graph API do tej tożsamości w Azure AD, używając Microsoft Graph PowerShell lub Graph Explorer.
3. Użyj PowerShell, aby zażądać tokenu z lokalnej usługi Azure Instance Metadata Service (IMDS).

Przykładowy fragment kodu PowerShell do pobrania tokenu za pomocą tożsamości zarządzanej:

$resource = "https://graph.microsoft.com"
$tokenAuthUri = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource"
$headers = @{ Metadata = "true" }
$response = Invoke-RestMethod -Method Get -Uri $tokenAuthUri -Headers $headers
$accessToken = $response.access_token

🔐 Przepływ z tożsamością zarządzaną eliminuje potrzebę przechowywania sekretów w skryptach. Zapewnia bezpieczne, bezproblemowe uwierzytelnianie w środowiskach Azure.

Wykonywanie wywołań API za pomocą PowerShell i Graph API

Wykonywanie wywołań API za pomocą PowerShell i Graph API pozwala efektywnie współpracować z usługami Microsoft 365. Zrozumienie, jak konstruować żądania HTTP, jest niezbędne do skutecznej komunikacji z API.

Konstruowanie żądań HTTP

Podczas pracy z Microsoft Graph API musisz poprawnie konstruować żądania HTTP. Oto kluczowe elementy żądania HTTP:

• Pobieranie tokenu dostępu: Użyj uzyskanego tokenu w nagłówku.
• Konfiguracja nagłówków: Ustaw niezbędne nagłówki, w tym Content-Type: application/json oraz Authorization: Bearer $accessToken.
• Żądanie GET/POST: Wyślij jawne żądanie do wybranego punktu końcowego Microsoft Graph API.

Korzystanie z Invoke-RestMethod

Cmdlet Invoke-RestMethod upraszcza komunikację z Microsoft Graph API. Pozwala wysyłać żądania HTTP i otrzymywać odpowiedzi w prosty sposób. Oto krótki przegląd jego działania i ograniczeń:

Popularne punkty końcowe API

Kilka punktów końcowych Microsoft Graph API jest często używanych do zadań administracyjnych Microsoft 365. Oto niektóre z najczęstszych:

Zarządzanie danymi wyjściowymi API

Zrozumienie odpowiedzi JSON

Podczas pracy z Microsoft Graph API dane są zwracane w formacie JSON. JSON (JavaScript Object Notation) jest lekki i łatwy do odczytania. Zrozumienie odpowiedzi JSON jest kluczowe dla skutecznego przetwarzania danych. Typowa odpowiedź JSON wygląda następująco:

{
  "id": "1",
  "displayName": "John Doe",
  "mail": "john.doe@example.com"
}

Konwersja JSON na obiekty PowerShell

Aby pracować z danymi JSON w PowerShell, musisz przekonwertować je na obiekty PowerShell. Ta konwersja pozwala łatwo manipulować danymi. Do tego celu możesz użyć cmdletu ConvertFrom-Json. Oto jak to działa:

$jsonData = '{"id": "1", "displayName": "John Doe", "mail": "john.doe@example.com"}'
$powerShellObject = $jsonData | ConvertFrom-Json

Teraz $powerShellObject zawiera właściwości, do których możesz uzyskać dostęp bezpośrednio, na przykład $powerShellObject.displayName.

Filtrowanie i formatowanie danych

Gdy dane znajdą się w obiektach PowerShell, możesz je filtrować i formatować zgodnie z własnymi wymaganiami. PowerShell udostępnia różne techniki pozwalające doprecyzować wynik. Na przykład podczas wywołań API możesz użyć parametrów zapytania OData, aby filtrować wyniki bezpośrednio w interfejsie Microsoft Graph API.

Eksportowanie wyników

Eksportowanie wyników ze skryptów PowerShell jest kluczowe dla skutecznego zarządzania danymi. Wynik możesz zapisać w różnych formatach, na przykład CSV, JSON lub XML. Na przykład szczegóły użytkowników możesz wyeksportować w następujący sposób:

$users = Get-MgUser -All
$users | Select-Object DisplayName, Mail | Export-Csv -Path "Users.csv" -NoTypeInformation

Najlepsze praktyki i rozwiązywanie problemów

Obsługa błędów i limitów API

Podczas pracy z Microsoft Graph API błędy często wynikają z ustawień specyficznych dla dzierżawy lub problemów z uprawnieniami. Wielu użytkowników uruchamia skrypty pobrane z internetu bez dostosowania ich do własnego środowiska, co prowadzi do błędów. Ponadto Microsoft Graph stosuje limity żądań, aby chronić swoje usługi. Jeśli skrypt wysyła zbyt wiele żądań w krótkim czasie, API zwraca kod stanu 429. Powinieneś uwzględnić nagłówek Retry-After i przed ponowieniem żądania odczekać sugerowany czas.

Zabezpieczanie poświadczeń

Ochrona poświadczeń ma kluczowe znaczenie podczas automatyzacji zadań w Microsoft 365. Użyj rejestracji aplikacji i tożsamości zarządzanych, aby utworzyć bezpieczne tożsamości dla swoich aplikacji. Jeśli to możliwe, unikaj przechowywania sekretów klienta w postaci jawnego tekstu wewnątrz skryptów.

Optymalizacja skryptów

Wydajne skrypty oszczędzają czas i ograniczają zużycie zasobów. Pobieraj tylko potrzebne właściwości, stosując parametr zapytania $select, wykorzystuj mechanizmy grupowania żądań i projektuj pętle automatyzacji z przejrzystą obsługą stronicowania.

Opanowanie przepływów z tożsamością zarządzaną w PowerShell i Microsoft Graph API zasadniczo zmienia podejście do automatyzacji w chmurze. Dzięki rezygnacji ze statycznych sekretów i wykorzystaniu tożsamości natywnych dla chmury budujesz odporne, wysoko bezpieczne przepływy pracy, które chronią całe przedsiębiorstwo. Aby dowiedzieć się więcej o tych strategiach i posłuchać praktycznych dyskusji o nowoczesnej administracji chmurą, koniecznie zajrzyj do powiązanego odcinka: Use Managed Identity with PowerShell for Microsoft Graph. Wypróbuj te przykłady w swojej piaskownicy już dziś i przenieś swoje środowisko automatyzacji na wyższy poziom!

Często zadawane pytania

Czym jest PowerShell?

PowerShell to platforma do automatyzacji zadań firmy Microsoft, łącząca powłokę wiersza poleceń z językiem skryptowym, która usprawnia zarządzanie systemami i operacje w chmurze.

Czym jest Microsoft Graph API?

Microsoft Graph API to ujednolicony interfejs RESTful umożliwiający dostęp do danych i usług w Microsoft 365, w tym do użytkowników, grup, poczty i konfiguracji katalogu.

Jak zainstalować moduł Microsoft Graph PowerShell?

Moduł możesz zainstalować, uruchamiając polecenie Install-Module Microsoft.Graph -Scope CurrentUser w środowisku PowerShell 7.

Czym są uprawnienia delegowane i uprawnienia aplikacji?

Uprawnienia delegowane pozwalają aplikacji działać w imieniu zalogowanego użytkownika, natomiast uprawnienia aplikacji umożliwiają wykonywanie zadań w tle bez aktywnego kontekstu użytkownika.

Jak obsługiwać limity żądań API?

Zawsze sprawdzaj wartość Retry-After w nagłówkach odpowiedzi, gdy otrzymujesz kod stanu 429, i zaimplementuj w swoich skryptach logikę ponawiania z wykładniczym wycofywaniem (exponential backoff).

Czym jest OAuth 2.0?

OAuth 2.0 to platforma autoryzacji, która pozwala aplikacjom bezpiecznie uzyskiwać tokeny dostępu do wywoływania chronionych interfejsów API bez ujawniania poświadczeń użytkownika.

Czy mogę używać PowerShell w systemie Linux?

Tak! PowerShell jest w pełni wieloplatformowy i działa natywnie w systemach Windows, macOS i Linux.

Jak wyeksportować dane z PowerShell?

Dane o strukturze możesz łatwo wyeksportować za pomocą cmdletów, takich jak Export-Csv lub ConvertTo-Json, w zależności od wymagań dotyczących formatu raportowania.