PowerShell 7.x (zalecany, Windows 11 24H2/25H2)

Install-Module Microsoft.Graph -Scope CurrentUser

Tylko potrzebne podmoduły (oszczędność miejsca)

Install-Module Microsoft.Graph.Users, Microsoft.Graph.Groups, Microsoft.Graph.Identity.DirectoryManagement

### Krok 3: Mapowanie cmdletów i przepisanie skryptów

Dla każdego starego cmdletu znajdź odpowiednik w Graph SDK. Kluczowe różnice:
- `Get-AzureADUser -ObjectId x` → `Get-MgUser -UserId x` (parametr nazywa się inaczej)
- `Get-MsolUser -All` → `Get-MgUser -All` (to samo, ale obiekt wynikowy ma inne właściwości)
- `Set-MsolUserLicense` → `Set-MgUserLicense` (inna składnia parametrów `-AddLicenses`)
- `Connect-AzureAD` → `Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"` (jawne definiowanie scope'ów)

**Przykład migracji skryptu** — pobranie wszystkich nieaktywnych użytkowników i wyłączenie ich kont:

```powershell
# STARY KOD (AzureAD + MSOnline — NIE DZIAŁA)
Connect-AzureAD
$inactiveUsers = Get-AzureADUser -All | Where-Object { $_.AccountEnabled -and $_.LastDirSyncTime -eq $null }

# NOWY KOD (Microsoft Graph)
Connect-MgGraph -Scopes "User.ReadWrite.All"
$inactiveUsers = Get-MgUser -All -Filter "accountEnabled eq true" -Property "signInActivity"

Krok 4: Wdrożenie app-only authentication dla skryptów nienadzorowanych

Stare moduły praktycznie nie wspierały app-only auth (certyfikatami) — wszystko opierało się na interaktywnym logowaniu, co blokowało automatyzację w harmonogramach zadań (Task Scheduler), Azure Automation i CI/CD pipelines. W Graph SDK to priorytetowy scenariusz:

# App-only auth z certyfikatem
Connect-MgGraph -ClientId "00000000-0000-0000-0000-000000000000" `
    -TenantId "twojtenant.onmicrosoft.com" `
    -CertificateThumbprint "ABCD1234..."

Krok 5: Testy i walidacja

Uruchom przepisane skrypty w środowisku testowym z flagą -WhatIf (dostępną tylko w Remove-Mg* i Set-Mg*), sprawdź logi Get-MgAuditLogDirectoryAudit dla nieoczekiwanych zmian i porównaj wyniki ze starym wykonaniem.

Microsoft dostarczył narzędzie Microsoft Graph PowerShell Migration Analyzer jako część modułu Microsoft.Graph.Tools, które automatycznie skanuje skrypty i generuje raport z rekomendacjami zmiany każdego cmdletu.

Automatyzacja zarządzania użytkownikami i licencjami przez PowerShell

To najbardziej dochodowy scenariusz w administracji M365 — firma z 500 użytkownikami, która ręcznie klika onboard/offboard, traci średnio 4 godziny tygodniowo na powtarzalne czynności. PowerShell z Microsoft Graph automatyzuje ten proces do zera.

Scenariusz: automatyczny onboarding nowego pracownika

# 1. Utwórz użytkownika
$user = New-MgUser -DisplayName "Anna Nowak" `
    -MailNickname "anna.nowak" `
    -UserPrincipalName "anna.nowak@firma.pl" `
    -PasswordProfile @{ Password = "TempPass123!"; ForceChangePasswordNextSignIn = $true } `
    -AccountEnabled:$true `
    -UsageLocation "PL"

# 2. Przypisz licencję Microsoft 365 Business Premium
$sku = Get-MgSubscribedSku | Where-Object SkuPartNumber -eq "SPB"
Set-MgUserLicense -UserId $user.Id -AddLicenses @{ SkuId = $sku.SkuId } `
    -RemoveLicenses @()

# 3. Dodaj do grup działowych
$grupaIT = Get-MgGroup -Filter "displayName eq 'Dział IT'"
Add-MgGroupMember -GroupId $grupaIT.Id -DirectoryObjectId $user.Id

# 4. Wyślij powiadomienie do przełożonego (przez Teams webhook lub Exchange Online)

Scenariusz: masowe odnowienie licencji subskrypcyjnych

Przy subskrypcjach rocznych (np. Microsoft 365 Business Standard czy Exchange Online Plan 2 zakupione przez KluczeSoft.pl z fakturą VAT 23%) masz ograniczoną pulę licencji i musisz mieć pełną kontrolę nad ich przydziałem:

$licenses = Get-MgSubscribedSku
$license | Select-Object SkuPartNumber, ConsumedUnits, @{N="Available";E={$_.PrepaidUnits.Enabled - $_.ConsumedUnits}}

Bezpieczeństwo i raportowanie przez PowerShell

W 2026 roku Microsoft Graph PowerShell jest podstawowym narzędziem audytu bezpieczeństwa w środowiskach M365. Pięć kluczowych scenariuszy:

1. Analiza logów logowania (Sign-In Logs)

Get-MgAuditLogSignIn -Filter "createdDateTime ge 2026-05-01" `
    -Property "userPrincipalName,ipAddress,status,riskDetail" `
    -All | Where-Object { $_.Status.ErrorCode -ne 0 } `
    | Select-Object UserPrincipalName, IpAddress, Status, CreatedDateTime

2. Detekcja użytkowników bez MFA

$users = Get-MgUser -All -Property "id,userPrincipalName"
foreach ($u in $users) {
    $authMethods = Get-MgUserAuthenticationMethod -UserId $u.Id
    if ($authMethods.Count -eq 0) {
        Write-Warning "Brak MFA: $($u.UserPrincipalName)"
    }
}

3. Audyt przypisań ról uprzywilejowanych

Get-MgRoleManagementDirectoryRoleAssignment -All `
    -Filter "roleDefinitionId eq '62e90394-69f5-4237-9190-012177145e10'" # Global Admin

4. Wymuszenie rotacji certyfikatów aplikacji

$apps = Get-MgApplication -All
$apps | Where-Object { $_.KeyCredentials } | ForEach-Object {
    $_.KeyCredentials | Where-Object { $_.EndDateTime -lt (Get-Date).AddDays(30) } | ForEach-Object {
        Write-Warning "Certyfikat wygasa: $($_.DisplayName) — $($_.EndDateTime)"
    }
}

5. Sprawdzanie zgodności z Conditional Access

Get-MgPolicyConditionalAccessPolicy | Select-Object DisplayName, State, CreatedDateTime, ModifiedDateTime

Typowe problemy i pułapki

Administratorzy migrujący na Microsoft Graph PowerShell regularnie wpadają w te same problemy. Oto lista pięciu najczęstszych i ich rozwiązania:

1. Insufficient privileges mimo roli Global Admin — Graph SDK wymaga jawnego zdefiniowania scope'ów przy Connect-MgGraph. Rola Global Admin nie daje automatycznie wszystkich uprawnień aplikacji. Rozwiązanie: Connect-MgGraph -Scopes "User.ReadWrite.All", "Group.ReadWrite.All", "Directory.ReadWrite.All".

2. TooManyRequests (HTTP 429) przy dużych zapytaniach — Graph API nakłada limit 10 000 żądań na minutę na aplikację i 100 żądań na minutę na użytkownika. Rozwiązanie: używaj -PageSize 50 zamiast domyślnych 100, dodaj Start-Sleep -Milliseconds 500 między batchami, a dla krytycznych operacji użyj Invoke-MgGraphRequest z własną retry-logic.

3. Parametr -Filter nie działa zgodnie z oczekiwaniami — Graph obsługuje tylko ograniczony podzbiór operatorów OData w zależności od endpointu. -Filter "startswith(displayName,'A')" działa w /users, ale nie w /groups. Rozwiązanie: sprawdź dokumentację konkretnego endpointu w Graph API reference, nie zakładaj pełnego OData.

4. Nieoczekiwane usunięcie właściwości przez Update-MgUser — Update-MgUser nadpisuje cały obiekt. Jeśli przekażesz tylko -City "Warszawa", wszystkie pozostałe pola zostaną wyczyszczone. Rozwiązanie: zawsze pobierz obiekt przez Get-MgUser, zmodyfikuj tylko potrzebne pola i przekaż go z powrotem, albo użyj -BodyParameter z hashtable zawierającym tylko zmieniane właściwości.

5. App-only authentication nie działa mimo poprawnych uprawnień — Uprawnienia API (Application permissions) wymagają admin consent. W Azure Portal przejdź do API Permissions aplikacji, kliknij Grant admin consent for <tenant>. Bez tego Connect-MgGraph z certyfikatem zwróci Authorization_RequestDenied.

Częste pytania

Czy Microsoft Graph PowerShell jest darmowy?

Tak. Sam moduł PowerShell i Microsoft Graph API są darmowe — płacisz wyłącznie za licencje Microsoft 365, którymi zarządzasz (np. Business Basic, E3, E5). Nie ma dodatkowych opłat za używanie Graph API przez PowerShell.

Jaka wersja PowerShell jest wymagana?

Microsoft Graph PowerShell SDK działa na PowerShell 5.1 (wbudowany w Windows 10 i Windows 11) oraz PowerShell 7.x (zalecany). PowerShell 7.4 to wersja LTS (Long Term Support) rekomendowana przez Microsoft na 2026 rok i preinstalowana w Windows 11 24H2 i 25H2.

Czy muszę od razu migrować wszystkie skrypty?

Tak — stare moduły przestały działać 30 marca 2024 roku, gdy Microsoft wyłączył Azure AD Graph API. Jeśli masz skrypty, które nie były uruchamiane od tamtego czasu, rzucą błędem autoryzacji przy pierwszej próbie wykonania. Nie ma okresu przejściowego — migracja jest obowiązkowa.

Jak mapować stare cmdlety na nowe?

Microsoft Graph PowerShell SDK zawiera wbudowaną komendę Find-MgGraphCommand, która pozwala wyszukiwać cmdlety po słowach kluczowych. Find-MgGraphCommand -Command Get-AzureADUser podpowie Get-MgUser. Dodatkowo migracyjny przewodnik Microsoft zawiera tabelę mapowania dla 80 najczęstszych cmdletów.

Jakie uprawnienia Graph API są potrzebne do codziennej administracji?

Minimalny zestaw scope'ów dla administratora M365: User.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All, Organization.Read.All, RoleManagement.ReadWrite.Directory, AuditLog.Read.All. Dla operacji tylko-do-odczytu (raporty, monitoring) wystarczą odpowiedniki .Read.All.

Czy Graph PowerShell obsługuje Exchange Online?

Tak — od 2026 roku zalecanym podejściem jest korzystanie z modułu ExchangeOnlineManagement V3, który wewnętrznie używa REST API (Graph), ale zachowuje znane cmdlety Exchange (Get-Mailbox, Set-Mailbox). Nie ma potrzeby przepisywania skryptów Exchange, wystarczy zaktualizować moduł do wersji 3.x.

Jak wydajnie pobrać wszystkich użytkowników w tenancie 50 000+ osób?

Użyj Get-MgUser -All -PageSize 50 z selekcją tylko potrzebnych pól (-Property "id,displayName,userPrincipalName"). Bez -Property Graph zwraca domyślny zestaw ~15 pól, co przy dużych tenantach generuje zbędny transfer i wydłuża wykonanie. Dla ekstremalnie dużych katalogów (100 000+) rozważ eksport przez Get-MgReport zamiast iterowania po użytkownikach.

Jak diagnozować błędy Graph API?

Włącz szczegółowe logowanie: Get-MgGraphRequest -Debug lub ustaw $DebugPreference = "Continue". Pełny komunikat błędu Graph API jest zawsze w $Error[0].ErrorDetails.Message jako JSON — parsuj go przez $_.Exception.Response dla uzyskania kodu błędu i korelacji request-id.

Czy mogę używać Graph PowerShell na serwerach bez GUI (Windows Server 2025 Core)?

Tak — Microsoft Graph PowerShell SDK działa w pełni na Windows Server 2025 Server Core i w kontenerach Windows. App-only authentication z certyfikatem jest wymagane, bo device code flow (fallback interaktywny) nie działa na headless.

Czy PowerShell Graph zastępuje portal admin.microsoft.com?

Nie w pełni. Graph PowerShell pokrywa ~95% operacji administracyjnych, ale niektóre zaawansowane konfiguracje (np. Microsoft Purview eDiscovery Premium, Teams Phone policies, zaawansowane reguły Microsoft Defender for Office 365) wciąż wymagają GUI. W codziennej administracji użytkownikami, grupami i licencjami Graph w pełni zastępuje portal.

Administratorzy Microsoft 365, którzy automatyzują zarządzanie przez PowerShell, oszczędzają średnio 15-20 godzin miesięcznie. Jeśli Twój zespół dopiero buduje kompetencje w tym obszarze, zacznij od środowiska deweloperskiego — każda subskrypcja Microsoft 365 Business Premium czy Microsoft 365 E5 zawiera deweloperski tenant testowy. Legalne klucze subskrypcyjne do wersji Business Standard, Business Premium i Enterprise znajdziesz w KluczeSoft.pl — z fakturą VAT 23%, automatycznym KSeF i dostawą e-mail w 1-3 minuty.