ユーザーなしでアクセスを取得
Microsoft Graph を呼び出すには、アプリがMicrosoft ID プラットフォームからアクセス トークンを取得する必要があります。 このアクセス トークンには、サインインしているユーザーの代わりに Microsoft Graph にアクセスするアプリが承認されているか、独自の ID でアクセスできるかに関する情報が含まれます。 この記事では、アプリが独自の ID (アプリ専用アクセスとも呼ばれます) を使用して Microsoft Graph にアクセスする方法に関するガイダンスを提供します。
この記事では、 OAuth 2.0 クライアント資格情報付与フローと呼ばれる一般的なフローを使用して、アプリが独自の ID で Microsoft Graph を呼び出すために必要な生の HTTP 要求について詳しく説明します。 または、未加工の HTTP 要求を書き込まないようにし、これらの詳細の多くを処理し、アクセス トークンを取得して Microsoft Graph を呼び出すのに役立つ Microsoft ビルドまたはサポートされている認証ライブラリを使用することもできます。 詳細については、「 Microsoft 認証ライブラリ (MSAL) を使用する」を参照してください。
前提条件
この記事の手順に進む前に、次の手順を実行してください。
- Microsoft ID プラットフォームの認証と承認の概念について説明します。 詳細については、「 認証と承認の基本」を参照してください。
- Microsoft Entra ID でアプリを登録します。 詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照してください。
認証および承認の手順
アプリがクライアント資格情報フローを使用して Microsoft Graph への承認とアクセスを取得するには、次の 5 つの手順に従う必要があります。
- Microsoft Entra ID でアプリを登録します。
- アプリに対する Microsoft Graph アプリケーションのアクセス許可を構成します。
- 管理者の同意を要求します。
- アクセス トークンを要求します。
- アクセス トークンを使用して Microsoft Graph を呼び出します。
1. アプリを登録する
アプリでMicrosoft ID プラットフォーム エンドポイントを使用したり、Microsoft Graph を呼び出したりする前に、適切に登録する必要があります。 Microsoft Entra管理センターにアプリを登録する手順に従います。
アプリの登録から、次の値を保存します。
- アプリ登録ポータルによって割り当てられたアプリケーション ID (Microsoft Entra 管理センターのオブジェクト ID と呼ばれます)。
- クライアント シークレット (アプリケーション パスワード)、証明書、またはフェデレーション ID 資格情報。
- Microsoft Entra ID からトークン応答を受信するアプリのリダイレクト URI。
- アプリが管理者の同意を要求する機能を実装している場合に管理者の同意応答を受け取るサービスのリダイレクト URI。
2.Microsoft Graph のアクセス許可を構成する
Microsoft Graph は、独自の ID で Microsoft Graph を呼び出すアプリに対する アプリケーションのアクセス許可 を公開します。 これらのアクセス許可には常に管理者の同意が必要です。
アプリを登録するときにアプリに必要なアプリケーションのアクセス許可を事前に構成します。 管理者は、organizationにアプリをインストールするときにMicrosoft Entra管理センターを使用するか、アプリでサインアップ エクスペリエンスを提供して、管理者が構成したアクセス許可に同意することができます。 ID Microsoft Entra管理者の同意が記録されると、アプリはもう一度同意を要求しなくてもトークンを要求できます。
Azure アプリ登録ポータルでアプリのアプリケーションのアクセス許可を構成するには、次の手順に従います。
- アプリケーションの [API アクセス許可 ] ページで、[ アクセス許可の追加] を選択します。
- [Microsoft Graph] を選択します。
- [アプリケーションのアクセス許可] を選択します。
- [ アクセス許可の選択 ] ダイアログで、アプリに構成するアクセス許可を選択します。
次のスクリーンショットは、Microsoft Graph のアプリケーションのアクセス許可に対する [アクセス許可の選択] ダイアログ ボックスを示しています。
重要
アプリに必要な最小限の権限セットを常に構成します。 詳細については、「 Microsoft Graph のアクセス許可を使用するためのベスト プラクティス」を参照してください。
3. 管理者の同意を要求する
管理者は、Microsoft Entra管理センターでアプリに必要なアクセス許可を付与できます。 ただし、Microsoft Entra管理センターにアクセスできない場合は、Microsoft ID プラットフォーム /adminconsent
エンドポイントを使用して管理者にサインアップ エクスペリエンスを提供できます。
重要
構成済みのアクセス許可を変更する場合は、管理者の同意プロセスも繰り返す必要があります。 アプリ登録ポータルで行われた変更は、グローバル管理者などの承認された管理者がアプリに再同意するまで反映されません。
要求
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions HTTP/1.1
パラメーター | 条件 | 説明 |
---|---|---|
tenant | 必須 | アクセス許可の要求元のディレクトリ テナント。 値は GUID またはフレンドリ名形式にすることができます。 ユーザーが属しているテナントがわからない場合に、任意のテナントでサインインできるようにする場合は、 を使用 common します。 |
client_id | 必須 | Azure アプリ登録ポータルがアプリに割り当てたアプリケーション ID。 |
redirect_uri | 必須 | アプリで処理する応答を送信するリダイレクト URI。 ポータルに登録したリダイレクト URI のいずれかと一致する必要があります。 URL でエンコードする必要があり、追加のパス セグメントを含めることができます。 |
state | 推奨 | トークン応答にも返される要求に含まれる値。 任意のコンテンツの文字列を指定できます。 状態は、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードするために使用されます。 |
管理者の同意エクスペリエンス
エンドポイントへの/adminconsent
要求では、Microsoft Entra ID によって、承認された管理者のみがサインインして要求を完了できるようになります。 管理者は、アプリ登録ポータルでアプリに対して要求したすべてのアプリケーションアクセス許可を承認するように求められます。
次のスクリーンショットは、MICROSOFT ENTRA ID が管理者に提示する同意ダイアログの例です。
応答
管理者がアプリケーションのアクセス許可を承認した場合、成功応答は次のようになります。
// Line breaks are for legibility only.
https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#
パラメーター | 説明 |
---|---|
tenant | 要求されたアクセス許可をアプリケーションに付与したディレクトリ テナント (GUID 形式)。 |
state | トークン応答にも返される要求に含まれる値。 任意のコンテンツの文字列を指定できます。 状態は、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードするために使用されます。 |
admin_consent | True に設定 します。 |
試す: ブラウザーに次の要求を貼り付けることで、自分で試すことができます。 Microsoft Entra テナントのグローバル管理者としてサインインすると、アプリの [管理者の同意] ダイアログ ボックスが表示されます。
4. アクセス トークンを要求する
OAuth 2.0 クライアント資格情報の付与フローでは、アプリの登録時に保存したアプリケーション ID とクライアント シークレットの値を使用して、Microsoft ID プラットフォーム/token
のエンドポイントからアクセス トークンを直接要求します。
トークン要求で パラメーターの値scope
として渡https://graph.microsoft.com/.default
すことによって、事前に構成されたアクセス許可を指定します。
トークン要求
アクセス トークンを取得するために /token
、ID プラットフォーム エンドポイントに POST 要求を送信します。 この要求では、クライアントはクライアント シークレットを使用します。
// Line breaks are for legibility only.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
パラメーター | 条件 | 説明 |
---|---|---|
tenant | 必須 | アクセス許可の要求元のディレクトリ テナント。 値は GUID またはフレンドリ名形式にすることができます。 |
client_id | 必須 | アプリの登録時に Azure アプリ登録ポータルが割り当てたアプリケーション ID。 |
スコープ | 必須 | この要求で スコープ パラメーターに渡される値は、必要なリソースの識別子 (アプリ ID URI) で、 .default サフィックスが付加されている必要があります。 たとえば、Microsoft Graph リソース アプリ ID URI は https://graph.microsoft.com/ です。 したがって、Microsoft Graphの場合、スコープの値は https://graph.microsoft.com/.default になります。 この値は、管理者が同意したすべてのアプリレベルのアクセス許可をアクセス トークンに含めるように Microsoft ID プラットフォームのエンドポイントに通知します。 |
client_secret | 必須 | アプリ登録ポータルでアプリ用に生成したクライアント シークレット。 URL でエンコードされていることを確認します。 |
grant_type | 必須 | client_credentials である必要があります。 |
トークンの応答
成功応答は、次のようになります。
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in":3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
パラメーター | 説明 |
---|---|
access_token | 要求されたアクセス トークン。 アプリでは、Microsoft Graph の呼び出しでこのトークンを使用できます。 |
expires_in | アクセス トークンの有効期間 (秒単位)。 |
ext_expires_in | アクセス トークンの有効期間の延長を示し、トークン発行サービスが応答しない場合の回復性をサポートするために使用されます。 |
token_type | トークンの種類の値を示します。 MICROSOFT ENTRA ID でサポートされる型は Bearer のみです。 |
5.アクセス トークンを使用して、Microsoft Graph を呼び出す
アクセス トークンを取得した後、アプリはそれを使用して、アクセス トークンを ベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチすることで Microsoft Graph を呼び出します。 次の要求は、テナント内のすべてのユーザーを取得します。 この API を呼び出すには、アプリに User.Read.All アクセス許可が必要です。
GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
成功した応答は次のようになります (一部の応答ヘッダーが削除されました)。
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
"value": [
{
"businessPhones": [],
"displayName": "Conf Room Adams",
"givenName": null,
"jobTitle": null,
"mail": "Adams@Contoso.com",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"userPrincipalName": "Adams@Contoso.com",
"id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
},
{
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@Contoso.com",
"mobilePhone": null,
"officeLocation": "18/2111",
"preferredLanguage": null,
"surname": "Vance",
"userPrincipalName": "AdeleV@Contoso.com",
"id": "59bb3898-0621-4414-ac61-74f9d7201355"
}
]
}
サポートされているアプリのシナリオとリソース
独自の ID で Microsoft Graph を呼び出すアプリは、次に示す 2 つのカテゴリのいずれかに分類されます。
- サインインしたユーザーが存在しないサーバーで実行されるバックグラウンド サービス (デーモン)。
- サインインしているユーザーが存在するが、独自の ID で Microsoft Graph を呼び出すアプリ。 たとえば、ユーザーが持つよりも高い昇格された特権を必要とする機能を使用する場合です。
この記事では、アプリが資格情報としてクライアント シークレットを使用しました。 必要に応じて、証明書またはフェデレーション ID 資格情報を構成できます。
独自の ID で Microsoft Graph を呼び出し、クライアント資格情報フローを使用するアプリの詳細については、「 認証フローとアプリケーション シナリオ: デーモンの名前で Web API を呼び出すデーモン アプリ」を参照してください。
Microsoft 認証ライブラリ (MSAL) を使用する
この記事では、通常、クライアント資格情報フローを実行するために生の HTTP 要求を手動で作成して発行する場合にのみ必要な低レベルのプロトコルの詳細について説明しました。 運用アプリでは、Microsoft 認証ライブラリ (MSAL) などの Microsoft ビルドまたはサポートされている認証ライブラリを使用して、セキュリティ トークンを取得し、Microsoft Graph などの保護された Web API を呼び出します。
MSAL やその他のサポートされている認証ライブラリは、検証、Cookie 処理、トークン キャッシュ、セキュリティで保護された接続などの詳細を処理することで、アプリケーションの機能に集中できるため、プロセスを簡略化します。
Microsoft では、Microsoft ID プラットフォームでサポートされている認証ライブラリの使用方法を示すさまざまなコード サンプルを構築および管理しています。 これらのコード サンプルにアクセスするには、「 次の手順」を参照してください。
次の手順
この記事は、Microsoft ID プラットフォームによる Microsoft Graph の認証と承認に関する次の一連の記事の一部です。
- 第 1 条 認証と承認の基本
- 第2条 アプリケーションをMicrosoft ID プラットフォームに登録する
- 記事 3: ユーザーの代わりにアクセスを取得する
- 記事 4: ユーザーなしでアクセスを取得する
次に、Microsoft によってビルドおよび保守されているコード サンプルから選択して、サポートされている認証ライブラリを使用するカスタム アプリを実行し、独自の ID で Microsoft Graph を呼び出します。