PowerShell и Microsoft Graph API: автоматизация Microsoft 365

Microsoft Graph — единая точка входа для всех сервисов Microsoft 365: Azure AD, Exchange Online, SharePoint, Teams, OneDrive, Intune. Вместо десятка разных модулей PowerShell (MSOnline, AzureAD, ExchangeOnlineManagement) можно использовать один универсальный SDK.

Преимущества Microsoft Graph перед устаревшими модулями:

• Единый API — один модуль для всех сервисов M365
• Активная разработка — модули MSOnline и AzureAD объявлены deprecated
• Гранулярные разрешения — можно запросить только нужные права
• REST API — можно вызывать напрямую через Invoke-RestMethod
• Поддержка приложений — автоматизация без интерактивного входа

Установите модуль Microsoft Graph PowerShell SDK:

Install-Module Microsoft.Graph -Scope CurrentUser

# Или установите только нужные подмодули
Install-Module Microsoft.Graph.Users
Install-Module Microsoft.Graph.Groups
Install-Module Microsoft.Graph.Mail
Install-Module Microsoft.Graph.Teams

Graph API поддерживает два режима аутентификации: делегированный (от имени пользователя) и серверный (от имени приложения).

Интерактивная аутентификация (для ручных скриптов):

Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All","Mail.Send"

# Проверка подключения
Get-MgContext | Format-List Account, TenantId, Scopes

Аутентификация приложения (для автоматизации без участия пользователя):

1. Зарегистрируйте приложение в Azure AD → App registrations
2. Создайте Client Secret или загрузите сертификат
3. Назначьте Application permissions (не Delegated)
4. Подтвердите Admin consent

$TenantId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$ClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$ClientSecret = ConvertTo-SecureString "секрет" -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential($ClientId, $ClientSecret)

Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $Credential

Основные операции с пользователями Azure AD через Graph:

# Получить всех пользователей
$Users = Get-MgUser -All -Property DisplayName, Mail, UserPrincipalName, AccountEnabled
$Users | Format-Table DisplayName, Mail, AccountEnabled

# Найти пользователя
$User = Get-MgUser -Filter "userPrincipalName eq 'ivanov@company.ru'"

# Создать нового пользователя
$PasswordProfile = @{
    Password = "TempP@ss2024!"
    ForceChangePasswordNextSignIn = $true
}

New-MgUser -DisplayName "Петров Иван" `
    -UserPrincipalName "petrov@company.ru" `
    -MailNickname "petrov" `
    -PasswordProfile $PasswordProfile `
    -AccountEnabled:$true `
    -UsageLocation "RU" `
    -Department "IT" `
    -JobTitle "Системный администратор"

Массовое обновление пользователей из CSV:

Import-Csv "C:\users-update.csv" -Encoding UTF8 | ForEach-Object {
    Update-MgUser -UserId $_.UPN `
        -Department $_.Department `
        -JobTitle $_.JobTitle `
        -OfficeLocation $_.Office
    Write-Host "Обновлён: $($_.UPN)"
}

Работа с группами безопасности и Microsoft 365:

# Создание группы безопасности
New-MgGroup -DisplayName "IT-Admins" `
    -MailEnabled:$false `
    -MailNickname "it-admins" `
    -SecurityEnabled:$true `
    -Description "Группа ИТ-администраторов"

# Создание группы Microsoft 365 (с почтой и SharePoint)
New-MgGroup -DisplayName "Проект Альфа" `
    -MailEnabled:$true `
    -MailNickname "project-alpha" `
    -SecurityEnabled:$false `
    -GroupTypes @("Unified") `
    -Description "Рабочая группа проекта"

# Добавление участников
$GroupId = (Get-MgGroup -Filter "displayName eq 'IT-Admins'").Id
$UserId = (Get-MgUser -Filter "userPrincipalName eq 'ivanov@company.ru'").Id

New-MgGroupMember -GroupId $GroupId `
    -DirectoryObjectId $UserId

Аудит членства в группах:

# Все участники группы с должностями
Get-MgGroupMember -GroupId $GroupId -All | ForEach-Object {
    $User = Get-MgUser -UserId $_.Id -Property DisplayName, JobTitle, Department
    [PSCustomObject]@{
        Name       = $User.DisplayName
        Title      = $User.JobTitle
        Department = $User.Department
    }
} | Format-Table

Microsoft Graph заменяет модуль ExchangeOnlineManagement для базовых операций с почтой:

# Отправка письма от имени пользователя (delegated permission)
$Message = @{
    Subject = "Отчёт за неделю"
    Body = @{
        ContentType = "HTML"
        Content = "<h2>Еженедельный отчёт</h2><p>Все системы работают штатно.</p>"
    }
    ToRecipients = @(
        @{ EmailAddress = @{ Address = "director@company.ru" } }
    )
}

Send-MgUserMail -UserId "admin@company.ru" -Message $Message

# Чтение почтового ящика
$Messages = Get-MgUserMessage -UserId "admin@company.ru" -Top 10 `
    -OrderBy "receivedDateTime desc" `
    -Property Subject, From, ReceivedDateTime

$Messages | Format-Table Subject, @{N='From';E={$_.From.EmailAddress.Address}}, ReceivedDateTime

Для серверных сценариев (Application permission: Mail.Send) используйте -UserId для отправки от имени любого ящика без интерактивной аутентификации.

Автоматизация назначения и отзыва лицензий M365:

# Получить доступные лицензии (SKU)
Get-MgSubscribedSku | Format-Table SkuPartNumber, `
    @{N='Total';E={$_.PrepaidUnits.Enabled}}, `
    @{N='Used';E={$_.ConsumedUnits}}, `
    @{N='Free';E={$_.PrepaidUnits.Enabled - $_.ConsumedUnits}}

# Назначить лицензию пользователю
$SkuId = (Get-MgSubscribedSku | Where-Object SkuPartNumber -eq "O365_BUSINESS_PREMIUM").SkuId

Set-MgUserLicense -UserId "petrov@company.ru" `
    -AddLicenses @(@{SkuId = $SkuId}) `
    -RemoveLicenses @()

# Массовое назначение из группы AD
$GroupMembers = Get-MgGroupMember -GroupId $GroupId -All
foreach ($Member in $GroupMembers) {
    $CurrentLicenses = (Get-MgUserLicenseDetail -UserId $Member.Id).SkuId
    if ($SkuId -notin $CurrentLicenses) {
        Set-MgUserLicense -UserId $Member.Id `
            -AddLicenses @(@{SkuId = $SkuId}) `
            -RemoveLicenses @()
        Write-Host "Лицензия назначена: $($Member.Id)"
    }
}

Для группового назначения лицензий (Group-based licensing) удобнее настроить автоматическое назначение через Azure AD группы в портале Azure.

Graph API предоставляет богатые отчёты по использованию M365:

# Отчёт о входах пользователей (требует AuditLog.Read.All)
$SignIns = Get-MgAuditLogSignIn -Top 100 -Filter "status/errorCode ne 0" `
    -OrderBy "createdDateTime desc"

$SignIns | Select-Object UserDisplayName, AppDisplayName, `
    @{N='Error';E={$_.Status.FailureReason}}, `
    CreatedDateTime, IPAddress | Format-Table

# Неактивные пользователи (не входили более 90 дней)
$Threshold = (Get-Date).AddDays(-90).ToString("yyyy-MM-ddTHH:mm:ssZ")
$Inactive = Get-MgUser -All -Property DisplayName, UserPrincipalName, SignInActivity | 
    Where-Object {
        $_.SignInActivity.LastSignInDateTime -lt $Threshold -or 
        $null -eq $_.SignInActivity.LastSignInDateTime
    }

$Inactive | Select-Object DisplayName, UserPrincipalName, `
    @{N='LastSignIn';E={$_.SignInActivity.LastSignInDateTime}} | 
    Export-Csv "C:\inactive-users.csv" -NoTypeInformation -Encoding UTF8

Используйте эти отчёты для оптимизации лицензий: отзывайте лицензии у неактивных пользователей, экономя до 20–30% бюджета M365.