どのAPIをたたくのか？
「誰がAPIを使うのか？」を扱ったM365アプリ登録入門の続編。Resource URLがAPIごとに違う理由と、アプリ登録からアクセストークンを使ってAPIを呼ぶまでの流れを整理する。
どのAPIをたたくのか？
前回の「M365アプリ登録入門」では、なぜアプリにもIDが必要なのか、ユーザー委任なのかアプリ単独なのか、つまり「誰がAPIを呼ぶか」に集中しました。今回は、その次に意識したい「どのAPIをたたくのか」です。トークンをどのAPI向けに取り、実際にどこへ要求を送るのか。その入り口としてresourceとscopeを整理します。
Learnで突然出てきたResource URL
質問の出発点は、Learnのカスタムコネクタ手順です。セキュリティ設定で突然「リソースURLにはhttps://management.core.windows.net/を、末尾のスラッシュまで正確に入力」と言われます。しかし普段このURLへAPI要求を送るわけではなく、なぜ必要なのか説明もありません。さらに調べると、Graphならgraph.microsoft.com、Azure AI Searchならsearch.azure.comのようにAPIごとに別の値が出てきます。この値は何を表し、どう選べばよいのか。それが今回の質問です。
APIごとに決められたトークンの宛先名
最初に答えます。Resource URLはHTTP送信先を指定する項目ではなく、Entra IDへ「どのAPI向けのアクセストークンが欲しいか」を伝えるresource identifierです。値がendpointと一致する場合も、異なる場合もあります。そのためARM、Graph、Searchで値が変わります。APIの提供側が定義するため、利用者はendpointから推測せず、対象APIとクラウドに対応する公式ドキュメントの値を使います。
前回のMicrosoft Graph例につなぐ
前回のメール取得では、サインインした本人の代理でMicrosoft Graphを呼び、Mail.Readの許可を使いました。scope=https://graph.microsoft.com/Mail.Readのうち、graph.microsoft.comがトークンの対象APIを示す部分です。そのトークンを付けて、実際にはhttps://graph.microsoft.com/v1.0/me/messagesへ要求を送ります。Graphは識別子とendpointのホスト名が同じなので気づきにくいだけで、前回も「どのAPI向けのトークンか」は決まっていました。
トークンの対象とHTTP送信先は別
resource、またはscopeのresource部分は、トークンをどのAPI向けに発行するかを示す識別子です。scope全体にはMail.Readなどのpermission名も含まれるため、scope全体がaudienceになるわけではありません。endpointはBearer tokenを付けて実際にHTTP要求を送る入口です。Resource URLはトークンの相手、endpointは通信先という別の役割なので、一致する場合も違う場合もあります。
Graph・ARM・Searchを対応表で見る
ここはAzure public cloudの具体例です。Microsoft Graphのresource identifierはgraph.microsoft.com、質問元のPower Platformカスタムコネクタ手順ではARM向けにmanagement.core.windows.net、Azure AI Searchのdata planeではsearch.azure.comです。トークンの対象を示す識別子と実際のHTTP送信先を横に並べます。値はendpointから推測せず、対象APIの公式ドキュメントに書かれたものをそのまま使います。
Entra ID認証からAPIを呼ぶまで
最後に全体を一本につなぎます。まずアプリをEntra IDへ登録します。次に使うAPIと必要な権限を指定します。今回のResource URLは、トークンをどのAPI向けにするかを示す部分です。必要なConsentまたは権限付与を行います。誰が承認するか、いつ同意画面が出るか、RBACを使うかはAPIと権限方式によって異なります。アプリが動き、必要ならユーザーがサインインして、対象APIを指定したトークン要求をEntra IDへ送ります。Entra IDから受け取るアクセストークンの主要な情報には、対象APIを検証するaud、発行元とテナントのiss、ユーザートークンだけに入る委任scopeのscp、client credentialsのアプリケーショントークンで使われる権限のroles、有効期限のexpなどがあります。最後にアプリがAuthorizationヘッダーへトークンを付けて実際のAPI endpointへ送ります。APIは署名、発行元、有効期限、aud、権限を検証し、audが自分と一致しないトークンを拒否します。クライアントはMicrosoft API向けアクセストークンの中身へ依存せず、API側が検証します。
もっと体系的に、順番に学びたい方へ
最後にご案内です。難しいITを体系的に学びたい方向けに、Ebi Studyで動画講座を公開しています。詳しくはebistudy.netをご覧ください。YouTubeのチャンネル登録もよろしくお願いします。撮影モードでは、このあと専用の締め画面が続きます。