Сервис Microsoft Graph API позволяет получать доступ к любым объектам в облаке Azure (Microsoft 365) через единую точку REST API (https://graph.microsoft.com). Скорее всего вы подумаете, что это должно быть интересно только веб программистам, но это не так. Доступ к некоторым данным, объектам или свойствам в Microsoft 365 можно получить только через Microsoft Graph. Администратору Azure для сбора аналитики, статистики и другой информации также периодически приходится использовать Microsoft Graph.

В этой статье мы покажем, как зарегистрировать свое приложение в Azure AD, получить токен для аутентификации, подключаться к различным ресурсам Microsoft 365 (Azure AD, Office 365, Intune, SharePoint, Teams, OneNote и т.д.) через RESTful из PowerShell с помощью командлета Invoke-RestMethod . Microsoft Graph можно использовать как для получения данных, так и для управления объектами в Azure.

Регистрация приложения Azure для Microsoft Graph

Для доступа к ресурсам в вашем тенанте Azure через Microsoft Graph нужно создать новое приложение Azure и разрешить ему получать доступ к различным объектам Azure.

1. Авторизуйтесь на https://portal.azure.com/ ;
2. Перейдите в раздел Azure Active Directory -> App registration ;
3. Создайте новое приложение ( New registration );
4. Укажите имя вашего приложения: azGraphPowerShellApp ; выберите кому можно использовать данное приложение: Accounts in this organizational directory only (tenantname only - Single tenant) , и нажмите Register ;
5. Теперь вам нужно определить к каким ресурсам Azure разрешено подключаться вашему приложению. Перейдите в раздел API permissions ;
6. По-умолчанию приложению разрешено читать данные только о текущем пользователей AzureAD (User.Read). Мы предоставим приложению права на чтение всех свойства пользователей и групп Microsoft 365;
7. Нажмите на кнопку Add a permissions , выберите Microsoft Graph ;
8. Есть два базовых типа разрешений в Microsoft Graph ( Delegated permission – когда действия выполняются от имени пользователя, запустившего приложение; Application Permission – когда приложение вызывается через внешний скрипт). Выберите Application Permission ;
9. В появившемся списке вы можете выбрать, какие разрешения назначить вашему приложению для доступа к разделам и объектам Azure. В моем примере я добавил такие разрешения: Group -> Group.Read.All, GroupMember -> GroupMember.Read.All, User -> User.Read.All (если вы хотите, чтобы приложение могло читать любые данные в вашем тенанте, выберите Directory.Read.All);
10. Нажмите на кнопку Grant admin consent для предоставления доступа от имени администратора;

Для выполнения аутентификации в приложении можно использовать сертификат или секрет. Секрет представляет собой по сути автоматически генерируемый пароль, а имя пользователя — это идентфикатор приложения. Создадим секрет для нашего приложения.

1. Перейдите в Certificates & secrets -> New client secrets ;
2. Укажите название ключа и срок его действия (я указал 12 месяцев);
3. Скопируйте значение из поля Value (это и будет ваш пароль для доступа к приложению). Сохраните пароль в Azure Key Vault или свою хранилку паролей, так как после выхода из приложения его значение станет скрытым (придется пересоздавать секрет);
4. Затем скопируйте ID вашего приложения (Application client ID) и ID тенанта Azure (Directory tenant ID).

Вставьте свои значения в переменные PowerShell

$ApplicationID = "46692ad-f8a0-123f-8cca-432102de3bcf"
$TenatDomainName = "26216542-465a-407e-a17d-2bb4c3e3313b"
$AccessSecret = "d-8jM3ZUG87du-syZd32k01q.gkssa3mH3v"

Подключение к Microsoft Graph из PowerShell

Для использования Microsoft Graph API из PowerShell не нужно устанавливать отдельные PowerShell модули (типа Azure AD ). Взаимодействие выполняется с помощью встроенного командлета Invoke-RestMethod .

Для подключения к GraphApi нужно получить токен доступа. Следующий скрипт PowerShell позволяет аутенртфицироваться в вашем приложении и получить токен доступа к Microsoft Graph API.

$ApplicationID = "46692ad-f8a0-123f-8cca-432102de3bcf"
$TenatDomainName = "26216542-465a-407e-a17d-2bb4c3e3313b"
$AccessSecret = "d-8jM3ZUG87du-syZd32k01q.gkssa3mH3v"
$Body = @{
Grant_Type    = "client_credentials"
Scope         = "https://graph.microsoft.com/.default"
client_Id     = $ApplicationID
Client_Secret = $AccessSecret
}
$ConnectGraph = Invoke-RestMethod -Uri https://login.microsoftonline.com/$TenatDomainName/oauth2/v2.0/token -Method POST -Body $Body
$token = $ConnectGraph.access_token

С этим токеном можно выполнять различные запросы к вашему тенанту Azure через GraphAPI.

Например, следующий скрипт позволяет вывести список всех групп в вашей Azure AD:

$GrapGroupUrl = 'https://graph.microsoft.com/v1.0/Groups/'
(Invoke-RestMethod -Headers @{Authorization = "Bearer $($token)"} -Uri $GrapGroupUrl -Method Get).value.displayName

Можно вывести дату создания группы в Azure AD :

$GrapGroupUrl = 'https://graph.microsoft.com/v1.0/Groups/'
$Groups=(Invoke-RestMethod -Headers @{Authorization = "Bearer $($token)"} -Uri $GrapGroupUrl -Method Get).value
$Groups | select displayName,createdDateTime

Вывести имя, UPN и email адрес пользователя:

$GrapUserUrl = 'https://graph.microsoft.com/v1.0/users'
$users=(Invoke-RestMethod -Headers @{Authorization = "Bearer $($token)"} -Uri $GrapUserUrl -Method Get).value
$users | select displayName,userprincipalname,mail

The remote server returned an error: (403) Forbidden.

В рассмотренных примерах мы только читали данные из Azure AD с помощью метода GET. Но вы можете использовать методы POST, PUT, PATCH и DELETE для внесения измененияй. Например, можно создать пользователя в Azure AD, сбросить его пароль, изменить описание и т.д.

Для просмотра доступных свойства и методов Microsoft Graph API через браузер можно использовать Graph Explorer ( https://developer.microsoft.com/en-us/graph/graph-explorer ).