ユーザーの代わりにアクセスを取得

Microsoft Graph を呼び出すには、アプリがMicrosoft ID プラットフォームからアクセス トークンを取得する必要があります。 このアクセス トークンには、サインインしているユーザーの代わりに Microsoft Graph にアクセスするアプリが承認されているか、独自の ID でアクセスできるかに関する情報が含まれます。 この記事では、アプリが ユーザーの代わりに Microsoft Graph にアクセスする方法 ( 委任されたアクセスとも呼ばれます) に関するガイダンスを提供します。

この記事では、 OAuth 2.0 承認コード付与フローと呼ばれる一般的なフローを使用して、アプリがユーザーに代わってアクセスするために必要な生の HTTP 要求について詳しく説明します。 または、未加工の HTTP 要求を書き込まないようにし、これらの詳細の多くを処理し、アクセス トークンを取得して Microsoft Graph を呼び出すのに役立つ Microsoft ビルドまたはサポートされている認証ライブラリを使用することもできます。 詳細については、「 Microsoft 認証ライブラリ (MSAL) を使用する」を参照してください。

この記事では、OAuth 2.0 承認コード付与フローの使用に関する次の手順を実行します。

1. 承認を要求します。
2. アクセス トークンを要求します。
3. アクセス トークンを使用して、Microsoft Graph を呼び出す。
4. [省略可能]更新トークンを使用して、期限切れのアクセス トークンを更新します。

前提条件

この記事の手順に進む前に、次の手順を実行してください。

1. Microsoft ID プラットフォームの認証と承認の概念について説明します。 詳細については、「 認証と承認の基本」を参照してください。
2. アプリを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

curl --location --request GET 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=11111111-1111-1111-1111-111111111111&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=offline_access%20User.Read%20Mail.Read&state=12345'

パラメーター

ユーザーの同意エクスペリエンス

アプリが承認要求を送信すると、ユーザーは 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#

クエリ パラメーター

手順 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

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d' \
--data-urlencode 'redirect_uri=https://localhost/myapp/' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_secret=zHF8Q~Krjqh4r...''

パラメーター

トークンの応答

アクセス トークンには、 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..."
}

応答本文のプロパティ

手順 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

curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw' \
--data ''

応答

成功した応答は次のようになります (一部の応答ヘッダーが削除されました)。

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

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_secret=jXoM3iz...'

パラメーター

応答

成功したトークン応答は、次のようになります。

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...",
}

応答本文パラメーター

Microsoft 認証ライブラリ (MSAL) を使用する

この記事では、承認コード フローを実行するために生の HTTP 要求を手動で作成して発行する場合にのみ必要な低レベルのプロトコルの詳細について説明しました。 運用アプリでは、Microsoft 認証ライブラリ (MSAL) などの Microsoft ビルドまたはサポートされている認証ライブラリを使用して、セキュリティ トークンを取得し、Microsoft Graph などの保護された Web API を呼び出します。 また、 シナリオに基づいて Microsoft Graph 認証プロバイダーを選択する方法についても説明します。

MSAL やその他のサポートされている認証ライブラリは、検証、Cookie 処理、トークン キャッシュ、セキュリティで保護された接続などの詳細を処理することで、アプリケーションの機能に集中できるため、プロセスを簡略化します。

Microsoft では、Microsoft ID プラットフォームでサポートされている認証ライブラリの使用方法を示すさまざまなコード サンプルを構築および管理しています。 これらのコード サンプルにアクセスするには、Microsoft ID プラットフォームコード サンプルを参照してください。

関連コンテンツ

• 委任されたシナリオでデータを認証してアクセスする基本的なアプリケーションを作成するために、さまざまな SDK を使用して構築されたコード サンプルについては、 Microsoft Graph チュートリアル を参照してください。
• さまざまな SDK を使用して構築され、Microsoft によって管理されているコード サンプルから選択して、サポートされている認証ライブラリ、サインイン ユーザー、および Microsoft Graph を呼び出すカスタム アプリを実行します。 「Microsoft Graph のチュートリアル」を参照してください。