Microsoft Graph (Office365) APIの、管理者トークンの取得と使い方に関するメモです。
きっかけ
Azure Active Directoryのユーザー・グループの追加・削除を、APIを使って行おうとしました。
Azure Active DirectoryのAPIは、Microsoft Graph (Office365) APIに統合されていて、Microsoft Graph APIを使うことになりました。
Microsoft Graph APIに関する説明
調べると色々なドキュメントがでてきて、かなり混乱したので、ザックリとまとめておこうと思います。
Microsoft Graph (Office365) APIとは？
Microsoft Graph (Office365) APIとは、Office365を操作できるAPIです。
Outlookメールの送受信や、ExcelオンラインのExcelファイルの編集など、クラウドのOffice365の様々な操作ができます。
Office365のユーザー・グループは、Azure Active Directoryを使っているため、前述の通り、Azure Active Directoryの操作もできます。
今回は、Azure Active Directoryの操作目的で使用しました。
ユーザーあり・なし、委任・アプリケーションの違い
Graph APIのドキュメントを見ると、トークンには
- ユーザーの代わりにアクセスを取得
- ユーザーなしでアクセスを取得
- 委任されたアクセス許可
- アプリケーションの許可
などの複数の呼び方がでてきて混乱しました。
色んな呼び方があるのですが、要は、APIで誰のOffice365を操作できるかを考えると分かります。
ユーザーの代わりにアクセスを取得
GoogleやFacebook認証などでよく見かける、リンクをクリックするとログインページが開いて、ログインすると同意画面が出て…。という流れで取得するトークンです。
ログインして同意した人のOffice365を操作できるトークンが発行されています。
なので、そのトークンを使ってメールを取得する場合、取得できるメールは、同意した人の受信トレイに届いたメールになります。
つまり、同意した人の代わりとなるトークンのため「ユーザーの代わりにアクセスを取得」や 「委任されたアクセス許可」といった呼ばれ方がされます。
ユーザーなしでアクセスを取得
最初、「ユーザーなし」ってAPI全部ユーザー無しじゃないか？…と思って混乱したのですが、要は「対象ユーザーが無い」、つまり、ユーザー同意のフローを踏まない、「管理者権限」のアクセスのことでした。
以上をまとめると、Graph APIは大きく分けて、「同意したユーザー権限での操作」と、「対象ユーザーのいない、管理者権限での操作」の２つになります。
今回は、Azure Active Directoryのユーザー・グループの管理をしたかったので、管理者権限のトークンを取得して使うことになります。
ユーザーが管理者だった場合、ユーザー同意で、自分のOffice365の操作だけでなく、管理者権限の操作ができるトークンを取得することもできます。
しかし、ユーザー同意によるトークン取得は煩雑なため、また、プログラムからの管理作業用途だったため、今回は「対象ユーザーのいない、管理者権限での操作」でトークンを取得することにしました。
以下、Microsoft Graph (Office365) APIの、対象ユーザーがいない、管理者権限のトークンの取得・使用手順になります。
手順
公式ドキュメントを参考に進めました。
ここでは自分がハマった点を中心に解説を加えて手順を記載しました。
アプリ登録
ユーザー権限・管理者権限どちらにせよ、まずAzure Active Directoryにアプリを登録します。
このあたりの手順は、以前、ユーザー権限トークンを取得した時の下記記事に記載しました。
以下手順は、Azure Active Directoryに登録した、各アプリ内での設定になります。
APIのアクセス許可の追加
Graph APIは、様々な操作ができるのですが、どんな操作をできるようにするかを設定します。
[APIのアクセス許可]-[+アクセス許可の追加]
色んなAPIが出てくるのですが、ここでは「Microsoft Graph」を選択します。
次に、「委任されたアクセス許可」と「アプリケーションの許可」が表示されます。
実はこれが前述の、ユーザーありか？なしか？のことで、ユーザーのいない「アプリケーションの許可」の方を選択します。
すると、管理者権限が必要なスコープ一覧が出てくるので、選択します。
例えばAzure Active Directoryのグループを取得する場合は[Group]-[Group.Read.All]を選択します。
APIの管理者同意
「管理者権限」のスコープを追加させただけではまだ使えず、管理者の同意が必要です。
管理者の同意は、管理者アカウントで下記をクリックします。
[Active[APIのアクセス許可]-[xxxxに管理者の同意を与えます]
クライアントシークレット発行
管理者権限のトークンは、クライアントシークレットを事前に発行し、そのクライアントシークレットで指定のURLにアクセスすると取得できます。
クライアントシークレットの発行は下記で行います。
[証明書とシークレット]-[+新しいクライアントシークレット]
トークン取得
アプリに関する情報を、トークン取得URLにPOSTで送ると、応答としてトークンが返ってきます。
下記のアプリに関する情報を、Azure Active Directoryからメモしておきます。
- テナントID
[概要]-[アプリケーション(クライアント)ID]
- アプリケーションID
[概要]-[アプリケーション(クライアント)ID]
- クライアントシークレット
- 前述の通り
トークン取得URLは下記に記載されています。
[クイックスタート]-[エンドポイント ビュー]-[OAuth2.0 トークンエンドポイント(v2)]
管理者トークン取得は下記のようになります。
import axios from 'axios'; const querystring: any = require('querystring'); const TENANT_ID = 'xxxx' const CLIENT_ID = 'xxxx'; const CLIENT_SECRET = 'xxxx'; (async () => { const qs = querystring.stringify({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, scope: 'https://graph.microsoft.com/.default', grant_type: 'client_credentials' }); const url = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token`; const result = await axios.request({ url, method: "POST", data: qs }); const access_token = result.data.access_token; console.log(access_token); })();
トークン使用
後は取得したトークンを使って、Graph APIを呼び出します。
Graph APIのドキュメントはこちらを参照しました。
ドキュメントだけだと分からない事も多く、実際に色々試してみるのがいいかと思います。
例えば、Azure Active Directoryのグループ一覧は下記で取得できます。
import axios from 'axios'; const ACCESS_TOKEN = 'xxxx'; (async () => { const itemList = []; const url = 'https://graph.microsoft.com/v1.0/groups'; let page = url; do { const result = await axios.request({ headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` }, url: page, method: "GET" }); itemList.push(...result.data.value); page = result.data["@odata.nextLink"]; } while (page); console.log(itemList); })();
感想など
Azure Active DirectoryのAPIは「Azure Active Directory Graph」と「Microsoft Graph」の２種類があり、Microsoft Graph APIのアクセストークン取得には「v1」と「v2」の２種類があります。
検索するとそれらの情報がごちゃまぜで、かつ同時にやってくるので、情報整理して概要を把握するのに時間がかかりました。
これまでオンプレで閉じていたActive DirectoryとOfficeは、今ではクラウド上にAzure Active DirecotyrとOffice365という形で構成するようになっています。
また、ユーザーIDは、企業ユーザー（Azure Active Directory）と個人ユーザー（Microsoft アカウント）でベースのプラットフォームが統合されていて、両者をまたいでユニークとなります。
また、Azure Active Directoryで、Office365のユーザー・グループが構成されていて、Office365とAzure Active Directoryも統合されています。
それらの壮大な統合がいつの間にかされてたんですね。すごいなぁ。
統合の過渡期に複数のAPI、エンドポイントが登場して、その名残が残っているのですが、この統合の流れからすると、アクセストークン取得は企業ユーザー・個人ユーザー関係なく、「v2」エンドポイントで一本化し、APIは「Microsoft Graph」で何でもできるようにする。というのが今後の主流になりそうですね。
となると、絶好調のAzureも統合していこう！となっていくんでしょうね。
