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

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

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

Предпосылки

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

• Регистрация приложения в 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:

С помощью этой информации вы можете начать составление запроса. Для этого нам нужно создать Заголовок авторизации который содержит «Носитель »И используйте это, чтобы сделать запрос 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                                                                                               
--------------                                     -----                                                                                               
 {@{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*, но мы хотим отфильтровать этот запрос. Вы можете сделать это, добавив $ фильтр = параметр для URI.

Фильтр (обычно) состоит из оператора свойства и такого значения:

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 в событии, можно создавать минималистичные и управляемые событиями функции для максимально возможной автоматизации в вашей среде. Все без необходимости включать большие библиотеки в ваши функции.