Microsoft Graph API利用手順忘備録
はじめに
Microsoft Graph API(以下、Graph)を触る機会が増えたので利用手順をまとめました。
Graph Exploler
Microsoft公式のGUIベースのWebアプリケーションです。
検証時にGraphを利用したい場合に便利です。
サンプルリクエストも豊富
ただし、ユーザーサインインとGraph Explolerの利用に承諾(OAuth)する必要があるのでAzure ADのサービスプリンシパルを利用する場合は不向きです。
意外と便利な機能が実行したリクエストをMicrosoft Graph PowerShell SDKを利用する場合のコマンドやアダプティブカードのJSONテンプレートを提供する機能です。
Azure ADのユーザーアカウントに付与されている権限内の利用が可能なので、一般ユーザーも活用できます。(User.Readなど)
一般ユーザーへGraph Explolerなどのマルチテナントアプリケーションにアクセス許可を与えないようにしたり承認制にするための手順はJapan Azure Identity Support Blogにまとめられています。
PowerShell
管理者の資格情報
Microsoft.Graph.Authenticationモジュールが最低限必要です。
ユーザーを作成するといった目的に応じてMicrosoft.Graph.UsersやMicrosoft.Graph.Groupsモジュールをインストールしてください。
Install-Module Microsoft.Graph.Authentication
Install-Module Microsoft.Graph.Users
# Micosoft Graph PowerShell SDKログイン
Connect-MgGraph -scopes User.ReadWrite.All
# ユーザーの作成
$bodyParam=@"
{
"accountEnabled": true,
"displayName": "Adele Vance",
"mailNickname": "AdeleV",
"userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
"passwordProfile" : {
"forceChangePasswordNextSignIn": true,
"password": "xWwvJ]6NMw+bWH-d"
}
}
"@
# どれでも同じ結果に
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $bodyParam
Invoke-MgRestMethod -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $bodyParam
New-Mguser -BodyParameter $bodyParam
Microsoftの有志の方たちのブログでも紹介されていますが、Invoke-MgRestMethodはInvoke-MgGraphRequestのエイリアスだったんですね。。
サービスプリンシパル(OAuth2.0 Client Credentials Grant)
Azure ADで作成したサービスプリンシパルのクライアントシークレットを利用する方法です。
# アプリケーション情報の入力
$tenantId = "Azure ADのテナントID"
$clientId = "Azure ADで作成したサービスプリンシパルのクライアントID"
$clientSecret = "クライアントシークレット"
# アクセストークン取得のリクエストパラメーターを作成
$accessTokenRequestParam = @{
Uri = "https://login.microsoftonline.com/$($tenantId)/oauth2/v2.0/token"
Method = "POST"
Headers = @{
"Content-Type" = "application/x-www-form-urlencoded"
}
Body = @{
grant_type = "client_credentials"
client_id = $clientId
client_secret = $clientSecret
scope = "https://graph.microsoft.com/.default"
}
}
# アクセストークンを取得
$BearerToken = Invoke-RestMethod @accessTokenRequestParam
# ユーザー情報を取得するリクエストパラメーターの作成
$createUserParam = @{
Uri = "https://graph.microsoft.com/v1.0/users/"
Method = "POST"
Headers = @{
Authorization = "Bearer $($BearerToken.access_token)"
"Content-Type" = "application/json"
}
Body = @"
{
"accountEnabled": true,
"displayName": "Adele Vance",
"mailNickname": "AdeleV",
"userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
"passwordProfile" : {
"forceChangePasswordNextSignIn": true,
"password": "xWwvJ]6NMw+bWH-d"
}
}
"@
}
# ユーザー情報を取得
Invoke-RestMethod @createUserParam
Bodyの値をJSONファイルから取得する場合
Get-Content "JSONファイルのパス" -Raw
サービスプリンシパル(証明書)
Japan Azure Identity Support BlogやMicrosoftの有志の方たちのブログにまとめられています。
Power Automate
基本的にはAzure ADで作成したサービスプリンシパルを利用します。
クライアントシークレットをよりセキュアにしたい場合はAzure Key Vaultでクライアントシークレットを管理しPower Automateで利用できます。(参考)
アクセストークン
- Azure ADでサービスプリンシパルを作成し権限を付与
-
HTTPリクエストのアクションでアクセストークンを取得。
※要プレミアムライセンス
- レスポンスをJSONの解析アクションで変数として利用可能に
- HTTPリクエストで認証を未加工 で取得したアクセストークンを利用
Barerとアクセストークンの変数の間にスペースがあります
{
"type": "object",
"properties": {
"token_type": {
"type": "string"
},
"expires_in": {
"type": "integer"
},
"ext_expires_in": {
"type": "integer"
},
"access_token": {
"type": "string"
}
}
}
これらのAzure ADに登録されたアプリのクライアントシークレットの有効期限が近付くとメールを送信してくれるフローの記事がすごく勉強になります。
レスポンス数が多いときの処理の仕方も解説してくれています。
クライアントシークレットを直接
HTTPリクエストのアクションで認証をActive Directory OAuth でクライアントシークレットのIDと値を設定
1回限りのリクエストだとこっちのほうが楽だったり
プレミアムライセンスを使わない
今回は2つ調べてみましたが、紹介するアクションにはユーザーサインインが必要なのでフロー用のアカウントを作成するかどうかといった考慮事項が必要です。
Miyakeさんのブログによると、プレビュー機能ですがOffice 365 Outlookコネクタの「HTTP 要求を送信する (プレビュー)」アクションを利用すれば、Graphを一部利用できるようです。
利用できるスコープは限られておりIT部門の運用の自動化という観点では不向きかなという印象ですが、一般ユーザーにとっては有益だと思います。
Microsoft Graph REST API リクエストを作成し呼び出します。 次のセグメントがサポートされています: 第 1 セグメント: /me、/users/ 第 2 セグメント: messages、mailFolders、events、calendar、calendars、outlook、inferenceClassification。
https://learn.microsoft.com/ja-jp/connectors/office365/#actions
また、Graphとは少し異なりますが、Power AutomateにはAzure ADコネクタが用意されており基本的なユーザー/グループ操作を行うことができます。
のりじさんのブログにユーザー作成のアクションの検証がまとめられています。
おわりに
Graphと早く仲良くなりたいです。
Discussion