0. はじめに
公開情報 を見れば良いのですが、 わかりにくく感じる方や、細々と読むのがめんどくさい方、これから Graph API を使う方向けに個人的に解説してみました。
本記事では、なるべくシンプルに Graph API を利用するために事前に用意するものや認証方法について大雑把に触れ、API の テストツールである POSTMAN で Graph API を利用できるところまでを解説します。なお、本記事の"2. Graph API の事前準備 (Azure AD 側)" まではどのプラットフォーム / 言語 でもだいたい手順は共通であるため参考にはなるかと思います。
1. Graph API の認証の流れ
ざっくりとは以下のような流れになります。
上述の図における ① では、Azure AD アプリ (API 用のアカウントのようなもの) を使って Azure AD から Graph API にアクセスに必要なアクセストークンをクライアントが取得します。アクセストークン取得後、クライアントは改めて上述の図 ③の段階で本丸の Graph API をリクエストします。
このような認証の流れとなるため、Graph API を利用するにはまず 事前に Azure AD へのアプリ登録や設定が必要になります。
2. Graph API の事前準備 (Azure AD 側)
2.1. Azure AD へのアプリ登録
それでは Azure AD へのアプリ登録から始めてみましょう。
Azure Portal へアクセスし [Azure Active Directory] > [アプリの登録] をクリックします。
[+ 新規登録ボタン] をクリックし、 "名前" に任意の文字を入力したら登録をクリックします。
※リダイレクト URI は Graph API で利用するプラットフォームや言語によっては入力する必要があります。今回は特に登録する必要がないので割愛します。
2.2.Azure AD のアプリに権限を付与する
さてここからはこの アプリに実行を許可するGraph API を指定していきます。
何を言っているかというと Graph API リファレンス に記載されている通り、Graph API にはたくさんの API があります。その API の中で利用したい特定の API だけに実行権限を付与する作業になります。
[Azure Active Directory] > [アプリの登録] > "先程作成したアプリ" > [API のアクセス許可] へ移動し、[アクセス許可の追加] をクリックします。
[Microsoft Graph] を選択し、 [アプリケーションの許可] をクリックし必要な API の権限にチェックを入れ最後に [アクセス許可の追加] をクリックします。
最後に、[xx に管理者の同意を与えます]をクリックします。
※補足 1: どの API の権限にチェックを入れたらよいかわからない方へ
Graph API リファレンス を見るとわかります。なぜならリファレンスのカテゴリーと [API のアクセス許可の要求]のページに表示されるカテゴリーは大体一致しているためです。
例えばユーザー情報の読み取り権限だけを与えたい場合、リファレンスを参照するとカテゴリーが "User" となっているので、"API アクセス許可の要求" のページにて [User] を選択すると、[User.Read.All] があるためこれにチェックを入れれば良いといった感じにわかります。
※補足 2: 認可されたアクセス許可について
主にWeb アプリなどで使います。ユーザーにアプリが xx の情報にアクセスします。同意しますかとポップアップが出てくるやつです
※補足 3: アプリケーションの許可について
主に自動化などで使います。Web アプリなどと違ってユーザーにアプリが xx の情報にアクセスします。同意しますかというポップアップが出ませんが代わりに Azure AD で事前に同意を行って置きます。
※補足 4: なぜ Graph API は Azure AD のアプリ登録を使うのか
これは私個人の意見ですが、従来の Rest API に対する課題を解決する方法として Azure AD のアプリ登録の機能を利用していると考えています。従来の Rest API の場合 API 毎にその利用の可否を制限するといった考え方がなく、すべての実行権限を保有する API キーを払い出すだけであり、API を使って連携する外部のアプリに過剰な権限を与えてしまうという課題がありました。
そのため Graph API では、Azure AD へアプリとして登録することで Azure AD によって API の実行権限を細かく制御、管理できるようにする狙いがあると考えています。より正確には OAuth や Open ID Connect という仕組みを利用するために Azure AD を使っているのですが、長くなるので割愛します。OAuth や Open ID Connect に興味のある方は別途調べてみてください。
2.3. Azure AD のアプリのシークレットクライアントを生成する
さてこの節で Azure AD へのアプリ登録の最後となります。
ここではクライアントが Azure AD のアプリへアクセストークンを要求するときに必要なクライアントシークレット (パスワードのようなもの) を生成します。
[Azure Active Directory] > [アプリの登録] > "先程作成したアプリ" > [証明書とシークレット] に移動します。
次に、[新しいクライアント シークレット] をクリックし、任意で "説明" に文字列を入力し、 "有効期限" にも設定し、[追加] をクリックします。
※ Azure Portal からは 1 年,2 年, なし のみの選択可能ですが Power Shell コマンド を利用することで任意の期間を指定できます。
"クライアント シークレット" の値をコピーしメモしておきます。
更に、[Azure Active Directory] > [アプリの登録] > [概要]に移動して、"アプリケーション (クライアント) ID", "ディレクトリ (テナント) ID" の値をコピーしメモしておきます。
3. クライアント (POSTMAN) 側の設定
ここからは POST MAN 側の設定を行っていきます。別プラットフォームの場合は公開情報を参照してください。
また POSTMAN の設定自体もMicrosoft の公開情報に記載されていますが、折角なので解説しておきます。
まだ POSTMAN をインストールしていない場合はここから ダウンロードします。
次に POSTMAN を起動し、[File] > [Import...] > [Import from Link] を選択します。
以下の 2 つの URL をそれぞれ入力し、 [Import] をクリックします。
https://raw.githubusercontent.com/microsoftgraph/microsoftgraph-postman-collections/master/Microsoft%20Graph.postman_collection.json
https://raw.githubusercontent.com/microsoftgraph/microsoftgraph-postman-collections/master/Microsoft%20Graph.postman_environment.json
右上隅の [No Enviroment] ドロップダウンを選択し、[Microsoft Graph 環境] を選択します。
右の 目のアイコンを選択し、[編集] を選択します。
前節で2.3. でメモしておいた クライアント ID、クライアントシークレット、テナント IDを "Current Value" に入力し、[Update] を選択します。
4. POST MAN で Graph API をテストしてみる
4.1. アクセストークンを取得する
左側にある [MicrosoftGraph] > [Application] > [Get App-only Access Token] を選択します。
すると アクセストークンが以下のキャプチャのように取得できます。
4.2. Graph API をリクエストする
いよいよ、Graph API を使っていきます。本記事ではユーザー情報の一覧取得の APIを使ってみます。
左側にある [MicrosoftGraph] > [User] > [Get Users] を選択し、[Send] をクリックします。
このような形で POSTMAN を利用すれば特にコーディングを必要とすることなく Graph API を利用することができます。
5. おまけアクセストークンの中身を見てみる
取得したアクセストークンは、 JWT 形式で記述されているため、 Base 64 でデコードすればどこでも見れるのですが、以下のサイトを使うと見やすいです
https://jwt.ms/
上記サイトでデコードすると以下のような形で情報を見ることができます。
このアクセストークンには有効期限や許可されている API や権限などが記載されています。
Graph API はこのアクセストークンをつけてリクエストすることで Azure AD に認証してもらってます。
普段はあまり意識することはないかもしれませんがトラブルシュートの際には役立つ情報です。