Изучение и использование API Graph для AzureAD – CloudSavvy IT
Microsoft GraphAPI – это мощный инструмент для работы. Мы можем не только использовать его для создания инструментов для автоматизации наших рабочих нагрузок, но и раньше получать доступ к новым функциям.
В этой статье мы узнаем, как исследовать и использовать Microsoft GraphAPI для Azure AD.
Предпосылки
Вы должны выполнить несколько предварительных условий, прежде чем мы сможем начать. Прежде чем начать с шагами, описанными в этой статье, убедитесь, что вы встречаете или имеете следующее:
Программы для Windows, мобильные приложения, игры - ВСЁ БЕСПЛАТНО, в нашем закрытом телеграмм канале - Подписывайтесь:)
- Регистрация приложения в AzureAD со следующими разрешениями GraphAPI:
- Directory.Read.All
- Directory.ReadWrite.All
- Идентификатор приложения (client-id) и client-secret для вышеуказанной регистрации приложения
- Ваше имя арендатора
- Компьютер с PowerShell версии 5.1 или выше
С этим из пути – давайте узнаем, как исследовать GraphAPI.
Читать документацию
Microsoft GraphAPI хорошо документирован, и лучше всего начинать с изучения того, как использовать новую функцию, – начать с справочная документация Microsoft Graph API.
Здесь указывается, как использовать конкретную функцию и какие разрешения вам нужны для ее использования. В настоящее время существует две версии GraphAPI: v1.0 и бета-версия API. Сначала они могут выглядеть одинаково, но бета-API содержит много новых функций, которые еще не выпущены. Также следует помнить, что функции в бета-версии API могут быть изменены в любое время.
права доступа
Разрешения являются важной частью изучения и использования разрешений Graph API – к счастью, все разрешения, необходимые для выполнения определенного действия, указаны в справочная документация этой функции.
На следующем снимке экрана показано разрешение, необходимое для использования getDirectoryObject функция. И поскольку вы будете обращаться к нему как к приложению, вам потребуется Directory.ReadAll разрешение.
Теперь, когда у вас есть основы, давайте начнем с запроса токена доступа – временного секрета, который мы будем использовать для доступа к Microsoft Graph API.
Запрос токена доступа
Маркер доступа – это секрет, который вы можете запросить с помощью нашего client-id и client-secret. Именно этот токен вы должны указывать в запросах к GraphAPI.
Чтобы запросить токен доступа, вам необходимо авторизоваться против конечной точки oauth2 арендатора, опубликовав свой идентификатор приложения и секрет приложения.
Отредактируйте следующий скрипт, заменив AppId, AppSecret и Tenant name, и запустите его в 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...............
истекает в секундах, что означает, что вы должны запросить новый токен в течение часа, иначе он перестанет работать.
Давайте сохраним токен доступа в переменной для будущего использования, а затем начнем делать запросы к GraphApi:
PS51> $AccessToken = $Request.access_token
Ваш первый запрос GraphAPI
Настало время для вашего первого запроса графика! Простейшие запросы для начала – это запросы, использующие HTTP GET. Команды GET предназначены только для извлечения информации, поэтому вам не нужно беспокоиться о том, чтобы что-то испортить.
Мы начнем с простого запроса со списком доменов, связанных с нашим арендатором. И помни – читай документацию. Вся информация о том, как использовать функции GraphAPI, находится в документация,
Вы могли заметить в документации для Список доменов команда, которую вы можете вызвать с помощью HTTP GET – метод по умолчанию при использовании Invoke-RestMethod:
С помощью этой информации вы можете начать составление запроса. Для этого нам нужно создать Заголовок авторизации который содержит «Носитель
$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
-------------- -----
{@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Результат запроса обычно находится в ценность свойство результата. Вы можете получить весь результат, просто выведя это свойство:
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*, но мы хотим отфильтровать этот запрос. Вы можете сделать это, добавив $ фильтр =
Фильтр (обычно) состоит из оператора свойства и такого значения:
property operator 'value'
Если вы сейчас хотите получить всех пользователей с собственное имя «Джон», следует использовать следующий 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, и вы увидите всех пользователей с заданным именем «Джон» в 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, и что тип контента должен быть применение / 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 в событии, можно создавать минималистичные и управляемые событиями функции для максимально возможной автоматизации в вашей среде. Все без необходимости включать большие библиотеки в ваши функции.
Программы для Windows, мобильные приложения, игры - ВСЁ БЕСПЛАТНО, в нашем закрытом телеграмм канале - Подписывайтесь:)
