Go to Qiita Advent Calendar 2024 Top
LoginSignup
139
129

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

@massie_g(がねこ まさし)

訳あってMicrosoft Graph API調べてみた

Last updated at Posted at 2019-11-06

はじめに

最近Microsoft Graph APIについて調べる機会がありました。この記事はその中から一般的な範囲についてまとめたものです。
AzureもAD(Aictive Directory)もGraph APIも詳しくないので誤りがあるかもしれません。間違いを発見されたらコメントや編集リクエストをお待ちしています。

Microsoft Graph APIとは

ざっくり言うと、Officie 365 や Azure ADなどの情報を検索、更新できるWeb API。例えば次のようなリソースにアクセス可能（許可を与えれば）

  • ユーザー
  • グループ
  • ディレクトリ(AD)
  • デバイス情報
  • カレンダー
  • メール
  • チャット
  • ファイル
  • 通知
  • チーム
  • 場所

今回はユーザー情報にターゲットを絞る。

Graph API の種別

  • (A) ユーザーの代わりにアクセスを取得（ユーザーが対話的に許可を与える）
    • ブラウザなどで、利用者本人がアプリのアクセスを許可する
    • GUI アプリケーションで利用
  • (B) ユーザーなしでアクセスを取得（あらかじめ管理者が許可を与えれば、ユーザ操作なしで動く）
    • 管理コンソールで、管理者が許可を与える
    • バッチ的なアプリケーションで利用

(A)の認証画面の例
user_permission.png

Graph API 利用までの準備

  • Azureへのサインアップ
  • アプリの登録
  • APIアクセス許可の付与
  • 管理者の同意
  • クライアントシークレットの生成

Azureへのサインアップ

  • Azure にサインアップ ... 今回は12ヶ月の無料体験でスタート
  • Azureポータルにログイン https://portal.azure.com
  • Azure Active Directory のページに移動
    • ホームからアイコンをクリック
    • または、左上のメニューから選択
azure_ad.png

※この時[規定のディレクトリ - 概要]で「ロール」が「グローバル管理者」になっていることを確認。

azure_ad_user_role.png
  • 「ロール」が「ユーザー」の場合は、この後でアプリにWrite権限を与えることができない（最初それでハマった）
    • ロールが「ユーザー」の場合は、ログアウト→再ログインでロールが変わる（？）

アプリの登録

azure_add_app.png
  • Active Directoryのページで、メニューから「アプリの登録」を選択
    • もし「ディレクトリに登録」か「個人アカウントに関連付ける」を聞かれたら前者を選択
    • （そうしないと、この後でアプリにWrite権限を与えることができない）
  • [新規登録]からアプリを登録
    • 名前
    • 種類（シングルテナント/マルチテナント/マルチテナント+個人）
      • シングルテナント or マルチテナント を選択
    • リダイレクト先のURI
  • アプリの情報を確認
    • アプリケーションID(client_id)
    • ディレクトリID(tenant ID)

アプリ登録中の画面

azure_new_app.png

アプリ登録後の表示

azure_app_info.png

APIアクセス許可の付与

  • アプリの概要のページから、左のメニューの[APIのアクセス許可]を選択
azure_app_api_permission.png
  • [+アクセス許可の追加]をクリックし、付与したいAPIを選択
    • 今回はGraph APIを使って、ユーザー情報の読み書きを行う
    • [Microsoft Grap API]を選択
      • [委任されたアクセス許可] ... (A) 対話的にユーザーが許可を与える
      • [アプリケーションの許可] ... (B) あらかじめ管理者が許可を与え、ユーザ操作なしで動く
      • ※バッチ的に動かすには(B)を選択。
        • この時「個人アカウントに関連付ける」では、Write許可が与えられない様子
    • その中で [User.ReadWrite.All]を選択
    • [アクセス許可の追加]をクリック
azure_api_graph.png azure_graph_with_or_without_user.png azure_api_user.png

管理者の同意

  • [規定のディレクトリに管理者の同意を与えます]をクリック
    • 先のアクセス権の追加だけでなく、管理者の同意を与えて、初めてAPIのアクセス権が有効になる
    • ※ポータルにログインしているユーザのロールが「グローバル管理者」になっていないと、同意ができない
azure_api_admin_ok.png

クライアントシークレットを生成

  • 登録したアプリを表示し、左の[証明書とシークレット]を選択
  • [新しいクライアントシークレット]をクリック
    • 名前と期間を指定して生成
  • 生成されたシークレットの値を確認
azure_api_client_secret.png

Graph APIを使う

ここでは「ユーザーなしでアクセスを取得」のケースを記載

アクセストークンの取得

  • POSTでアクセストークンを取得
    • アプリのクライアントID, テナントID, クライアントシークレットを利用

curlコマンドでPOST実行し、token.jsonに保存する例

curlの実行例
curl -d "client_id={クライアントID}" \
 -d "scope=https%3A%2F%2Fgraph.microsoft.com%2F.default" \
 -d "client_secret={クライアントシークレット}" \
 -d "grant_type=client_credentials" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -X POST https://login.microsoftonline.com/{テナントID}/oauth2/v2.0/token  > token.json

取得結果(token.json)の例

token取得結果
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "ext_expires_in": 3600,
  "access_token": "xxxxxxxxxxx......."
}

→ 以後、取得したaccess_tokenの値を利用する

トークンを使って情報取得

GETでユーザーの情報を取得

  • 先ほどのアクセストークンの値と、取得するユーザーのオブジェクトIDを指定する
curlで取得してファイルに保存する例
curl -H "Authorization: Bearer {access_tokenの値}" \
 https://graph.microsoft.com/v1.0/users/{取得するユーザーのオブジェクトID} > user.json
ユーザー情報の例
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
  "businessPhones": [],
  "displayName": "Joe Test",
  "givenName": null,
  "jobTitle": null,
  "mail": null,
  "mobilePhone": null,
  "officeLocation": null,
  "preferredLanguage": null,
  "surname": null,
  "userPrincipalName": "joe@xxxxxxxxx.onmicrosoft.com",
  "id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

トークンを使って情報の更新

PATCHで部分的に属性を更新可能

  • アクセストークンの値と、更新するユーザーのオブジェクトIDを指定する
  • ボディ部分にjsonで更新する属性、値を指定する
curlでPATCHを実行
curl --request PATCH https://graph.microsoft.com/v1.0/users/{更新するユーザーのオブジェクトID} \
 -H "Authorization: Bearer {access_tokenの値}" \
 -H "Content-Type: application/json" \
 -d '{ "jobTitle": "test user"}'

APIのアクセス許可が適切に追加できていれば、指定した属性のみ更新される

Graph API「ユーザーの代わりにアクセスを取得する」場合

ユーザによる許可

アクセストークンの取得

POSTでアクセストークンを取得

curlを使った例
curl -d "client_id={クライアントID}}" \
 -d "scope=user.read mail.read" \
 -d "code={ユーザーによる許可で得られたcode}" \
 -d "redirect_uri={リダイレクトURIのエンコード表記}" \
 -d "grant_type=authorization_code" \
 -d "client_secret={クライアントシークレット}" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -X POST https://login.microsoftonline.com/common/oauth2/v2.0/token
トークン取得結果の例
{
  "token_type": "Bearer",
  "scope": "User.Read Mail.Read",
  "expires_in": 3600,
  "ext_expires_in": 3600,
  "access_token": "xxxxxxxxxxxxxx...",
  "refresh_token": "xxxxxxxxxxxxxxx..."
}

情報の取得

自分の情報の取得
curl -H "Authorization: Bearer {アクセストークンの値}" https://graph.microsoft.com/v1.0/me
ユーザーを指定して情報を取得
curl -H "Authorization: Bearer {アクセストークンの値}" \
 https://graph.microsoft.com/v1.0/users/{ユーザーID}

その他

  • 有効期間内なら refresh_token を使ってアクセストークンを再取得できる
  • 情報の更新は「権限不足」で失敗
    • 試したのが個人向けアプリだったため？ 原因は未追求

おまけ

POSTとPUTとPATCH

今回初めてPATCHメソッドの存在を知った。

  • POST ... リソースの新規追加
  • PUT ... リソースの更新（置換）
  • PATCH ... リソースの部分更新（アップデート）

カスタム属性の利用

ユーザーの情報としてカスタム属性を利用する場合には、「Azure AD B2C ディレクトリ」を利用する必要がある。 （無料体験のライセンスでは利用できない）

Graph API beta の利用（2019.11.16追記)

ここまでは v1.0 を利用していたが、beta ではより多くの属性が扱えることが判明したので使ってみた。

  • アクセストークンの取得まではv1.0と同じ

betaでのユーザー情報の取得

v1.0と同様に、GETでユーザーの情報を取得。URLの「v1.0」の箇所を「beta」にするのが違い。

  • 先ほどのアクセストークンの値と、取得するユーザーのオブジェクトIDを指定する
curlで取得してファイルに保存する例
curl -H "Authorization: Bearer {access_tokenの値}" \
 https://graph.microsoft.com/beta/users/{取得するユーザーのオブジェクトID} > user_beta.json
betaのユーザー情報の例
{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
  "id": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "deletedDateTime": null,
  "accountEnabled": true,
  "ageGroup": null,
  "businessPhones": [],
  "city": null,
  "createdDateTime": "2019-11-03T09:34:59Z",
  "creationType": null,
  "companyName": "GOOD COMPANY",
  "consentProvidedForMinor": null,
  "country": null,
  "department": null,
  "displayName": "Joe Test",
  "employeeId": null,
  "faxNumber": null,
  "givenName": null,
  "imAddresses": [],
  "isResourceAccount": null,
  "jobTitle": "test user",
  "legalAgeGroupClassification": null,
  "mail": null,
  "mailNickname": "joe",
  "mobilePhone": null,
  "onPremisesDistinguishedName": null,
  "officeLocation": null,
  "onPremisesDomainName": null,
  "onPremisesImmutableId": null,
  "onPremisesLastSyncDateTime": null,
  "onPremisesSecurityIdentifier": null,
  "onPremisesSamAccountName": null,
  "onPremisesSyncEnabled": null,
  "onPremisesUserPrincipalName": null,
  "otherMails": [],
  "passwordPolicies": null,
  "postalCode": null,
  "preferredDataLocation": null,
  "preferredLanguage": null,
  "proxyAddresses": [],
  "refreshTokensValidFromDateTime": "2019-11-03T09:34:58Z",
  "showInAddressList": null,
  "signInSessionsValidFromDateTime": "2019-11-03T09:34:58Z",
  "state": null,
  "streetAddress": null,
  "surname": null,
  "usageLocation": null,
  "userPrincipalName": "joe@xxxxxxx.onmicrosoft.com",
  "externalUserState": null,
  "externalUserStateChangeDateTime": null,
  "userType": "Member",
  "assignedLicenses": [],
  "assignedPlans": [],
  "deviceKeys": [],
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuer": "xxxxxxxxx.onmicrosoft.com",
      "issuerAssignedId": "joe@mxxxxxx.onmicrosoft.com"
    }
  ],
  "onPremisesExtensionAttributes": {
    "extensionAttribute1": null,
    "extensionAttribute2": null,
    "extensionAttribute3": null,
    "extensionAttribute4": null,
    "extensionAttribute5": null,
    "extensionAttribute6": null,
    "extensionAttribute7": null,
    "extensionAttribute8": null,
    "extensionAttribute9": null,
    "extensionAttribute10": null,
    "extensionAttribute11": null,
    "extensionAttribute12": null,
    "extensionAttribute13": null,
    "extensionAttribute14": null,
    "extensionAttribute15": null
  },
  "onPremisesProvisioningErrors": [],
  "passwordProfile": {
    "password": null,
    "forceChangePasswordNextSignIn": true,
    "forceChangePasswordNextSignInWithMfa": false
  },
  "provisionedPlans": []
}

v1.0と比べて、取得できる属性がかなり多い。

v1.0ユーザー情報の例
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
  "businessPhones": [],
  "displayName": "Joe Test",
  "givenName": null,
  "jobTitle": null,
  "mail": null,
  "mobilePhone": null,
  "officeLocation": null,
  "preferredLanguage": null,
  "surname": null,
  "userPrincipalName": "joe@xxxxxxxxx.onmicrosoft.com",
  "id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

betaでのユーザー情報の一部更新

betaで増えた属性の更新もURLの「v1.0」の箇所を「beta」にするとできる。

curl --request PATCH https://graph.microsoft.com/beta/users/{更新するユーザーのオブジェクトID} \
 -H "Authorization: Bearer {access_tokenの値}" \
 -H "Content-Type: application/json" \
 -d '{ "jobTitle": "beta test user", "onPremisesExtensionAttributes": {"extensionAttribute2": "extra attribute test"} }'

更新後に再度ユーザー情報を取得すれば、指定した属性が更新されている。カスタム属性を使わなくても、extensionAttribute1 〜 extensionAttribute15 が利用できるので情報を追加で保持するのに使えそう。

139
129
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
139
129

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?