ユーザーの代わりにアクセスを取得
Microsoft Graph を呼び出すには、アプリがMicrosoft ID プラットフォームからアクセス トークンを取得する必要があります。 このアクセス トークンには、サインインしているユーザーの代わりに Microsoft Graph にアクセスするアプリが承認されているか、独自の ID でアクセスできるかに関する情報が含まれます。 この記事では、アプリが ユーザーの代わりに Microsoft Graph にアクセスする方法 ( 委任されたアクセスとも呼ばれます) に関するガイダンスを提供します。
この記事では、 OAuth 2.0 承認コード付与フローと呼ばれる一般的なフローを使用して、アプリがユーザーに代わってアクセスするために必要な生の HTTP 要求について詳しく説明します。 または、未加工の HTTP 要求を書き込まないようにし、これらの詳細の多くを処理し、アクセス トークンを取得して Microsoft Graph を呼び出すのに役立つ Microsoft ビルドまたはサポートされている認証ライブラリを使用することもできます。 詳細については、「 Microsoft 認証ライブラリ (MSAL) を使用する」を参照してください。
この記事では、OAuth 2.0 承認コード付与フローの使用に関する次の手順を実行します。
- 承認を要求します。
- アクセス トークンを要求します。
- アクセス トークンを使用して、Microsoft Graph を呼び出す。
- [省略可能]更新トークンを使用して、期限切れのアクセス トークンを更新します。
前提条件
この記事の手順に進む前に、次の手順を実行してください。
- Microsoft ID プラットフォームの認証と承認の概念について説明します。 詳細については、「 認証と承認の基本」を参照してください。
- アプリをMicrosoft Entra IDに登録します。 詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照してください。 アプリの登録から次の値を保存します。
- アプリケーション ID (Microsoft Entra 管理センターのオブジェクト ID と呼ばれます)。
- クライアント シークレット (アプリケーション パスワード)、証明書、またはフェデレーション ID 資格情報。 このプロパティは、ネイティブ、モバイル、シングル ページ アプリケーションなどのパブリック クライアントには必要ありません。
- Microsoft Entra IDからトークン応答を受け取るためのアプリのリダイレクト URI。
手順 1: 承認を要求する
承認コード フローの最初の手順は、ユーザーがアプリに代わって動作することを承認することです。
フローでは、アプリはユーザーを Microsoft ID プラットフォーム /authorize エンドポイントにリダイレクトします。 このエンドポイントを通じて、Microsoft Entra IDはユーザーをサインインさせ、アプリが要求するアクセス許可に対する同意を要求します。 同意が得られた後、Microsoft Entra IDは承認コードをアプリに返します。 アプリは、Microsoft ID プラットフォーム /token エンドポイントでこのコードをアクセス トークンに引き換えることができます。
承認要求
次の例は、 /authorize エンドポイントへの要求を示しています。
要求 URL で、 /authorize エンドポイントを呼び出し、必要なプロパティと推奨されるプロパティをクエリ パラメーターとして指定します。
次の例では、アプリは User.Read および Mail.Read Microsoft Graph のアクセス許可を要求します。これにより、アプリはサインインしているユーザーのプロファイルとメールをそれぞれ読み取ります。 offline_accessアクセス許可は、アプリが更新トークンを取得できるように要求される標準 OIDC スコープです。 アプリは、更新トークンを使用して、現在のアクセス トークンの有効期限が切れたときに新しいアクセス トークンを取得できます。
// Line breaks for legibility only
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345 HTTP/1.1
パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| tenant | 必須 | 要求のパスで {tenant} 値を使用して、アプリケーションにサインインできるユーザーを制御できます。 以下のいずれかの値を指定できます。common は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。organizationsconsumers詳細については、「プロトコルの基本情報」を参照してください。 |
| client_id | 必須 | 登録ポータルがアプリに割り当てたアプリケーション (クライアント) ID。 Microsoft Graph アプリケーションおよびサービス プリンシパル オブジェクトでは appId とも呼ばれます。 |
| response_type | 必須 | OAuth 2.0 承認コード フローの code を含める必要があります。 |
| redirect_uri | 推奨 | 認証応答がアプリとの間で送受信されるアプリのリダイレクト URI。 URL エンコードする必要がある点を除き、アプリ登録ポータルで登録したリダイレクト URI のいずれかと完全に一致する必要があります。 ネイティブとモバイル アプリの場合は、既定値の https://login.microsoftonline.com/common/oauth2/nativeclient を使用する必要があります。 |
| スコープ | 必須 | ユーザーが同意する必要がある Microsoft Graph のアクセス許可をスペースで区切った一覧。 これらのアクセス許可には、 User.Read や Mail.Read などのリソースのアクセス許可や、 offline_accessなどの OIDC スコープを含めることができます。これは、アプリがリソースへの有効期間の長いアクセスに更新トークンを必要とすることを示します。 |
| response_mode | 推奨 | 結果のトークンをアプリに送信するために使用するメソッドを指定します。 または query になります。form_post |
| state | 推奨 | トークン応答にも返される要求に含まれる値。 任意のコンテンツの文字列にすることができます。 ランダムに生成された一意の値は、通常、クロスサイト リクエスト フォージェリ攻撃を防止するために使用されます。 このプロパティは、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードするためにも使用されます。 |
ユーザーの同意エクスペリエンス
アプリが承認要求を送信すると、ユーザーは Microsoft で認証するための資格情報の入力を求められます。 Microsoft ID プラットフォーム v2.0 エンドポイントは、ユーザーが scope クエリ パラメーターに示されているアクセス許可に同意したことを確認します。 ユーザーまたは管理者が同意していないアクセス許可がある場合は、必要なアクセス許可に同意するように求められます。 Microsoft Entra同意エクスペリエンスの詳細については、「アプリケーションの同意エクスペリエンス」と「アクセス許可と同意の概要」を参照してください。
次のスクリーンショットは Microsoft アカウント ユーザーの同意ダイアログ ボックスの例です。
承認応答
ユーザーがアプリが要求したアクセス許可に同意した場合、応答には code パラメーターに承認コードが含まれます。 前の要求に対する正常な応答の例を次に示します。 要求の response_mode パラメーターが query に設定されているため、応答はリダイレクト URL のクエリ文字列で返されます。
HTTP/1.1 200 OK
https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#
クエリ パラメーター
| パラメーター | 説明 |
|---|---|
| code | アプリが要求した承認コード。 アプリは、承認コードを使用して、ターゲット リソースのアクセス トークンを要求します。 承認コードは有効期間が短く、通常は約 10 分後に有効期限が切れます。 |
| state | state パラメーターが要求に含まれている場合は、同じ値が応答に表示されます。 アプリは要求と応答の state 値が同じであることを確認する必要があります。 このチェックは、クライアントに対するクロスサイト 要求フォージェリ (CSRF) 攻撃を検出するのに役立ちます。 |
| session_state | 現在のユーザー セッションを識別する一意の値。 この値は GUID ですが、検査なしで渡される不透明な値として扱う必要があります。 |
手順 2: アクセス トークンを要求する
アプリは、前の手順で受け取った承認codeを使用して、/token エンドポイントにPOST要求を送信してアクセス トークンを要求します。
トークン要求
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=HF8Q~Krjqh4r... // NOTE: Only required for web apps
パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| tenant | 必須 | 要求のパスで {tenant} 値を使用して、アプリケーションにサインインできるユーザーを制御できます。 以下のいずれかの値を指定できます。common は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。organizationsconsumers詳細については、「プロトコルの基本情報」を参照してください。 |
| client_id | 必須 | 登録ポータルがアプリに割り当てたアプリケーション (クライアント) ID。 Microsoft Graph アプリケーションおよびサービス プリンシパル オブジェクトでは appId とも呼ばれます。 |
| grant_type | 必須 | 認可コードのフローの authorization_code になる必要があります。 |
| scope | 必須 | スコープのスペースで区切られた一覧。 このレッグでアプリが要求するスコープは、手順 2 の承認区間で要求したスコープと同等か、そのスコープのサブセットである必要があります。 この要求で指定されたスコープが複数のリソース サーバーにまたがる場合、v2.0 エンドポイントは、最初のスコープで指定されたリソースのトークンを返します。 |
| code | 必須 | 手順 2 の承認レッグで取得した承認 コード 。 |
| redirect_uri | 必須 | 手順 2 で承認 コード を取得するために使用されたのと同じリダイレクト URI 値。 |
| client_secret | Web アプリに必須 | アプリのアプリ登録ポータルで作成したクライアント シークレット。 クライアント シークレットをデバイスに確実に格納できないため、ネイティブ アプリでは使用しないでください。 Web アプリと Web API に必須。これには、サーバー側に client_secret を安全に保存する機能があります。 |
トークンの応答
アクセス トークンには、 scope パラメーターでアクセス トークンが適しているアクセス許可の一覧が含まれています。 応答は次の例のようになります。
HTTP/1.1 200 OK
Content-type: application/json
{
"token_type": "Bearer",
"scope": "Mail.Read User.Read",
"expires_in": 3736,
"ext_expires_in": 3736,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
応答本文のプロパティ
| パラメーター | 説明 |
|---|---|
| token_type | トークンの種類の値を示します。 Microsoft Entra IDがサポートする型はBearerのみです。 |
| スコープ | アクセス トークンが有効な Microsoft Graph アクセス許可のスペース区切りリスト。 |
| expires_in | アクセス トークンの有効期間 (秒単位)。 |
| ext_expires_in | アクセス トークンの有効期間 (秒単位) を示し、トークン発行サービスが応答しない場合の回復性をサポートするために使用されます。 |
| access_token | 要求されたアクセス トークン。 アプリでは、このトークンを使用して Microsoft Graph を呼び出すことができます。 |
| refresh_token | OAuth 2.0 の更新トークン。 アプリでは、現在のアクセス トークンの有効期限が切れた後に、このトークンを使用して追加のアクセス トークンを取得できます。 更新トークンは有効期限が長く、長期間にわたってリソースへのアクセスを保持するために使用できます。 更新トークンは、 offline_access が scope パラメーターとして含まれている場合にのみ返されます。 詳細については、 v2.0 トークンリファレンスを参照してください。 |
手順 3: アクセス トークンを使用して Microsoft Graph を呼び出す
アクセス トークンを取得した後、アプリはそれを使用して、アクセス トークンを ベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチすることで Microsoft Graph を呼び出します。 次の要求は、サインインしたユーザーのプロファイルを取得します。
要求
GET https://graph.microsoft.com/v1.0/me 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
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"businessPhones": [
"425-555-0100"
],
"displayName": "MOD Administrator",
"givenName": "MOD",
"jobTitle": null,
"mail": "admin@contoso.com",
"mobilePhone": "425-555-0101",
"officeLocation": null,
"preferredLanguage": "en-US",
"surname": "Administrator",
"userPrincipalName": "admin@contoso.com",
"id": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
}
手順 4: 更新トークンを使用して、期限切れのアクセス トークンを更新する
アクセス トークンは有効期間が短く、リソースへのアクセスを継続するには、有効期限が切れた後にアプリを更新する必要があります。 アプリは、/token エンドポイントに別のPOST要求を送信することで行われます。今回は次のようになります。
- 要求本文でコードの代わりに
refresh_tokenを指定する -
authorization_codeではなく、refresh_tokenをgrant_typeとして指定します。
要求
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=jXoM3iz... // NOTE: Only required for web apps
パラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
| tenant | 必須 | 要求のパスで {tenant} 値を使用して、アプリケーションにサインインできるユーザーを制御できます。 以下のいずれかの値を指定できます。common は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。organizationsconsumers詳細については、「プロトコルの基本情報」を参照してください。 |
| client_id | 必須 | 登録ポータルによってアプリが割り当てられたアプリケーション (クライアント) ID。 Microsoft Graph アプリケーションおよびサービス プリンシパル オブジェクトでは appId とも呼ばれます。 |
| grant_type | 必須 |
refresh_token である必要があります。 |
| scope | 省略可能 | アクセス許可 (scope) のスペースで区切られた一覧。 アプリが要求するアクセス許可は、手順 2. の元の承認コード要求で要求したアクセス許可と同じか、そのアクセス許可のサブセットである必要があります。 |
| refresh_token | 必須 | 手順 3. のトークン要求中にアプリが取得したrefresh_token。 |
| client_secret | Web アプリに必須 | アプリのアプリ登録ポータルで作成したクライアント シークレット。 client_secretsはデバイスに確実に格納できないため、ネイティブ アプリではシークレットを使用しないでください。 Web アプリと Web API に必須。これには、サーバー側に client_secret を安全に保存する機能があります。 |
応答
成功したトークン応答は、次のようになります。
HTTP/1.1 200 OK
Content-type: application/json
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "Mail.Read User.Read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
応答本文パラメーター
| パラメーター | 説明 |
|---|---|
| access_token | 要求されたアクセス トークン。 アプリはこのトークンを Microsoft Graph の呼び出しで使用できます。 |
| token_type | トークンの種類の値を示します。 Microsoft Entra IDがサポートする型はBearerのみです。 |
| expires_in | アクセス トークンの有効期間 (秒単位)。 |
| scope | access_token が有効なアクセス許可 (scope)。 |
| refresh_token | 新しい OAuth 2.0 の更新トークン。 古い更新トークンをこの新しく取得した更新トークンに置き換えて、更新トークンが可能な限り有効なままであることを確認します。 |
Microsoft 認証ライブラリ (MSAL) を使用する
この記事では、承認コード フローを実行するために生の HTTP 要求を手動で作成して発行する場合にのみ必要な低レベルのプロトコルの詳細について説明しました。 運用アプリでは、Microsoft 認証ライブラリ (MSAL) などの Microsoft ビルドまたはサポートされている認証ライブラリを使用して、セキュリティ トークンを取得し、Microsoft Graph などの保護された Web API を呼び出します。 また、 シナリオに基づいて Microsoft Graph 認証プロバイダーを選択する方法についても説明します。
MSAL やその他のサポートされている認証ライブラリは、検証、Cookie 処理、トークン キャッシュ、セキュリティで保護された接続などの詳細を処理することで、アプリケーションの機能に集中できるため、プロセスを簡略化します。
Microsoft では、Microsoft ID プラットフォームでサポートされている認証ライブラリの使用方法を示すさまざまなコード サンプルを構築および管理しています。 これらのコード サンプルにアクセスするには、Microsoft ID プラットフォームコード サンプルを参照してください。
関連コンテンツ
- シングルページ アプリ、Web アプリ、モバイル アプリなど、さまざまな種類のアプリからユーザーの代わりに Microsoft Graph を呼び出すことができます。 詳細については、「 シナリオとサポートされる認証フロー」を参照してください。
- サポートされている認証ライブラリ、サインイン ユーザー、および Microsoft Graph を呼び出すカスタム アプリを実行するために、Microsoft によって構築および管理されているコード サンプルから選択します。 「Microsoft Graph のチュートリアル」を参照してください。