Изучение и использование Graph API для AzureAD

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

В этой статье мы узнаем, как исследовать и использовать Microsoft GraphAPI для Azure AD.

Предпосылки

Вы должны выполнить несколько предварительных условий, прежде чем мы сможем начать. Прежде чем приступить к действиям, описанным в этой статье, убедитесь, что вы соответствуете или имеете следующее:

Регистрация приложения в AzureAD со следующими разрешениями GraphAPI:
- Directory.Read.All
- Directory.ReadWrite.All
С этим покончено — давайте научимся исследовать GraphAPI.
Читать документацию

Microsoft GraphAPI хорошо задокументирован, и при изучении того, как использовать новую функцию, лучше всего начать со справочной документации по Microsoft Graph API.
Это указывает, как использовать конкретную функцию и какие разрешения вам нужны для ее использования. В настоящее время существует две версии GraphAPI: v1.0 и бета-API. На первый взгляд они могут выглядеть одинаково, но бета-API содержит множество новых функций, которые еще не выпущены. Также имейте в виду, что функции в бета-версии API могут быть изменены в любое время.
Разрешения
Разрешения являются важной частью изучения и использования разрешений Graph API — к счастью, все разрешения, необходимые для выполнения определенного действия, указаны в справочной документации по этой функции.
На следующем снимке экрана показано разрешение, необходимое для использования функции getDirectoryObject. А поскольку вы будете обращаться к нему как к приложению, вам потребуется разрешение Directory.ReadAll.
Теперь, когда у вас есть основы, давайте начнем с запроса токена доступа — временного секрета, который мы будем использовать для доступа к Microsoft Graph API.
Запрос токена доступа
Токен доступа — это секрет, который вы можете запросить с помощью нашего идентификатора клиента и секрета клиента. Именно этот токен вы должны использовать в запросах к GraphAPI.
Чтобы запросить токен доступа, вам необходимо авторизоваться в конечной точке oauth2 клиента, опубликовав свой идентификатор приложения и секрет приложения.
Отредактируйте следующий сценарий, заменив AppId, AppSecret и имя клиента, и запустите его в PowerShell, чтобы запросить маркер доступа:
```
Add-Type -AssemblyName System.Web

$AppId = 'CHANGEME'
$AppSecret = 'CHANGEME'
$Scope = "https://graph.microsoft.com/.default"
$TenantName = "CHANGEME.onmicrosoft.com"

$Url = "https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token"

$Body = @{
  client_id = $AppId
	client_secret = $AppSecret
	scope = $Scope
	grant_type = 'client_credentials'
}

$PostSplat = @{
    ContentType = 'application/x-www-form-urlencoded'
    Method = 'POST'
    Body = $Body
    Uri = $Url
}

# Request the token!
$Request = Invoke-RestMethod @PostSplat
```
Теперь, если вы посмотрите на переменную $Request, вы увидите, что она содержит наш токен доступа, а также тип и срок действия.
```
PS51> $Request

token_type expires_in ext_expires_in access_token                                                                                                      
---------- ---------- -------------- ------------                                                                                                      
Bearer           3599           3599 eyJ...............
```
expires_in указывается в секундах, что означает, что вы должны запросить новый токен в течение часа, иначе он перестанет работать.

Давайте сохраним токен доступа в переменной для будущего использования, а затем начнем делать запросы к GraphApi:
```
PS51> $AccessToken = $Request.access_token
```
Ваш первый запрос GraphAPI
Пришло время для вашего первого запроса графика! Простейшими запросами для начала являются запросы, использующие HTTP GET. Команды GET предназначены только для получения информации, поэтому вам не нужно беспокоиться о том, чтобы что-то испортить.
Мы начнем с простого запроса со списком доменов, привязанных к нашему арендатору. И помните — читайте документацию. Вся информация о том, как использовать функции GraphAPI, есть в документации.
В документации к команде List Domains вы могли заметить, что ее можно вызывать с помощью HTTP GET — метода по умолчанию при использовании Invoke-RestMethod:
Имея эту информацию, вы можете приступить к созданию запроса. Для этого нам нужно создать Заголовок авторизации, содержащий «Bearer », и использовать его, чтобы сделать запрос GET к URL-адресу, показанному на рисунке выше:
```
$Headers = @{
    Authorization = "Bearer $AccessToken"
}

$Uri = "https://graph.microsoft.com/v1.0/domains"

$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
```
Теперь у вас есть список доменов в переменной $Result, но попытка вывести значение переменной $Result приведет к следующему результату:
```
PS51> $Result

@odata.context                                     value                                                                                               
--------------                                     -----                                                                                               
<https://graph.microsoft.com/v1.0/$metadata#domains> {@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
```
Результат запроса обычно находится в свойстве value результата. Вы можете получить весь результат, просто выведя вместо этого это свойство:
```
PS51> $Result.value

authenticationType               : Managed
availabilityStatus               : 
id                               : contoso.com
isAdminManaged                   : True
isDefault                        : True
isInitial                        : False
isRoot                           : True
isVerified                       : True
supportedServices                : {Email, Intune}
state                            : 
passwordValidityPeriodInDays     : 2147483647
passwordNotificationWindowInDays : 14

authenticationType               : Managed
availabilityStatus               : 
id                               : contoso.onmicrosoft.com
isAdminManaged                   : True
isDefault                        : False
isInitial                        : True
isRoot                           : True
isVerified                       : True
supportedServices                : {Email, OfficeCommunicationsOnline}
state                            : 
passwordValidityPeriodInDays     : 2147483647
passwordNotificationWindowInDays : 14
```
Теперь, когда вы изучили основы получения информации с помощью GraphAPI, пришло время научиться использовать фильтры.
Использование фильтров
Замечательно иметь возможность получать все доступные данные. И хотя это может работать, это ужасно неэффективно. Хорошей практикой является запрос только тех данных, которые вам нужны. Чтобы добиться этого в GraphAPI, мы можем использовать фильтры.
Хорошим кандидатом для опробования фильтров является выборка пользователей. У них много общих имен атрибутов с локальной Active Directory, и у вас обычно есть по крайней мере несколько из них.

URI для получения всех пользователей — *https://graph.microsoft.com/v1.0/users*, но мы хотим отфильтровать этот запрос. Это можно сделать, добавив параметр $filter= в URI.
Фильтр (обычно) состоит из оператора свойства и такого значения:
```
property operator 'value'
```
Если теперь вы хотите получить всех пользователей с givenName «John», следует использовать следующий URI:
```
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
```
Итак, если вы хотите использовать PowerShell для выполнения этого запроса, код должен выглядеть примерно так:
```
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
```
Обратите внимание на обратную кавычку перед $filter — это экранирование знака доллара, иначе PowerShell интерпретировал бы его как переменную.
Взгляните на свойство value, и вы увидите всех пользователей с заданным именем «John» в Azure Active Directory:
```
PS51> $Result.value

businessPhones    : {5554012}
displayName       : John Doe
givenName         : John
jobTitle          : 
mail              : jdoe@contoso.com
mobilePhone       : 
officeLocation    : 
preferredLanguage : en
surname           : Doe
userPrincipalName : jdoe@contoso.com
id                : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
```
«EQ» — не единственный оператор, у вас есть не (ne), соответствие, содержит, меньше/больше, чем (lt/gt) и многое другое. Хотя это выходит за рамки этой статьи, дополнительная информация об операторах доступна в документации. Кроме того, более подробная документация о различных свойствах фильтра доступна в документации по свойствам для каждого типа объекта.
Создание пользователя
Теперь, когда вы разобрались с основами, давайте выполним операцию записи и создадим пользователя. Для этого вам нужно знать, как создавать данные и где их размещать. Вы можете увидеть пример того, как это сделать, перейдя к документации Microsoft Graph API и посмотрев «Создать пользователя»:
Вы можете видеть, что вам нужно отправить данные в виде запроса POST и что тип содержимого должен быть application/json. Вы также можете увидеть представление данных в формате JSON — цель здесь — создайте объект PowerShell, который создает этот JSON, когда на нем используется ConvertTo-Json.
Давайте попробуем:
```
$Body = [PSCustomObject]@{
    accountEnabled = $True
    displayName = "Jane Doe"
    mailNickname = "janedoe"
    userPrincipalName = "jane.doe@automativity.com"
    passwordProfile = @{
        forceChangePasswordNextSignIn = $True
        password = "Hunter221!"
    }
}
```
Запуск $Body | ConvertTo-Json приведет к JSON, аналогичному тому, который отображается в документации. Теперь осталось преобразовать его в JSON и отправить в URI GraphAPI с правильным типом контента:
```
$Body = [PSCustomObject]@{
    accountEnabled = $True
    displayName = "Jane Doe"
    mailNickname = "janedoe"
    userPrincipalName = "jane.doe@contoso.com"
    passwordProfile = @{
        forceChangePasswordNextSignIn = $True
        password = "Hunter221!"
    }
}

$BodyJson = $Body | ConvertTo-Json
$Uri = "https://graph.microsoft.com/v1.0/users"

Invoke-RestMethod -Uri $Uri -Headers $Headers -Method POST -ContentType application/json -Body $BodyJson
```
Если вы сейчас перейдете в нашу консоль Azure Active Directory и посмотрите, вы найдете только что созданного пользователя:
Вы создали своего первого пользователя с помощью GraphAPI!
Заключение
Microsoft GraphAPI — это мощный инструмент, который позволит вам еще больше автоматизировать вашу среду. И не только когда речь идет об Azure Active Directory, но и о большинстве служб SaaS, которые предлагает Microsoft.
Кроме того, учитывая «бессерверное» перемещение с использованием функций Azure или AWS Lambda в событии, можно создавать минималистичные и управляемые событиями функции для максимальной автоматизации в вашей среде. И все это без необходимости включать большие библиотеки в ваши функции.

Изучение и использование Graph API для AzureAD

Предпосылки

Читать документацию

Разрешения

Запрос токена доступа

Ваш первый запрос GraphAPI

Использование фильтров

Создание пользователя

Заключение