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

[アーティクル]
03/10/2024

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

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

前提条件

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

Microsoft ID プラットフォームの認証と承認の概念について説明します。詳細については、「認証と承認の基本」を参照してください。
アプリをMicrosoft Entra IDに登録します。詳細については、「アプリケーションをMicrosoft ID プラットフォームに登録する」を参照してください。

認証および承認の手順

アプリが承認コードフローを使用して Microsoft Graph への承認とアクセスを取得するには、次の 5 つの手順に従う必要があります。

アプリをMicrosoft Entra IDに登録します。
承認を要求します。
アクセストークンを要求します。
アクセストークンを使用して、Microsoft Graph を呼び出す。
[省略可能]更新トークンを使用して、期限切れのアクセストークンを更新します。

1. アプリを登録する

アプリが Microsoft ID プラットフォームエンドポイントまたは Microsoft Graph を呼び出す前に、適切に登録されている必要があります。手順に従って、Microsoft Entra 管理センターにアプリを登録します。

アプリの登録から、次の値を保存します。

アプリ登録ポータルによって割り当てられたアプリケーション ID (Microsoft Entra 管理センターのオブジェクト ID と呼ばれます)。
アプリがMicrosoft Entra IDから応答を受信するためのリダイレクト URI (または応答 URL)。
クライアントシークレット (アプリケーションパスワード)、証明書、またはフェデレーション ID 資格情報。このプロパティは、ネイティブ、モバイル、シングルページアプリケーションなどのパブリッククライアントには必要ありません。

2. 承認を要求する

承認コードフローの最初の手順は、ユーザーがアプリに代わって動作することを承認することです。

フローでは、アプリはユーザーを Microsoft ID プラットフォーム /authorize エンドポイントにリダイレクトします。このエンドポイントを通じて、Microsoft Entra IDはユーザーをサインインさせ、アプリが要求するアクセス許可に対する同意を要求します。同意が得られた後、Microsoft Entra IDは承認コードをアプリに返します。アプリは、Microsoft ID プラットフォーム /token エンドポイントでこのコードをアクセストークンに引き換えることができます。

承認要求

次の例は、エンドポイントへの要求を /authorize 示しています。

要求 URL でエンドポイントを呼び出 /authorize し、必要なプロパティと推奨されるプロパティをクエリパラメーターとして指定します。

次の例では、アプリは User.Read および Mail.Read Microsoft Graph のアクセス許可を要求します。これにより、アプリはサインインしているユーザーのプロファイルとメールをそれぞれ読み取ります。 offline_accessアクセス許可は、アプリが更新トークンを取得できるように要求される標準 OIDC スコープです。アプリは、更新トークンを使用して、現在のアクセストークンの有効期限が切れたときに新しいアクセストークンを取得できます。

HTTP
cURL

// 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'

パラメーター

パラメーター	必須	説明
tenant	必須	要求のパスで `{tenant}` 値を使用して、アプリケーションにサインインできるユーザーを制御できます。以下のいずれかの値を指定できます。 `common` は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。職場または学校アカウントのみの `organizations` Microsoft アカウントのみの `consumers` テナント ID やドメイン名などのテナント識別子。詳細については、「プロトコルの基本情報」を参照してください。
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 などのリソースアクセス許可、および OIDC スコープ (など `offline_access`) を含めることができます。これは、アプリがリソースへの有効期間の長いアクセスに更新トークンを必要とすることを示します。
response_mode	推奨	結果のトークンをアプリに送信するために使用するメソッドを指定します。または `query` になります。`form_post`
state	推奨	トークン応答にも返される要求に含まれる値。任意のコンテンツの文字列にすることができます。ランダムに生成された一意の値は、通常、クロスサイトリクエストフォージェリ攻撃を防止するために使用されます。このプロパティは、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) をエンコードするためにも使用されます。

アプリが承認要求を送信すると、ユーザーは Microsoft で認証するための資格情報の入力を求められます。 Microsoft ID プラットフォーム v2.0 エンドポイントは、ユーザーがクエリパラメーターに示されているscopeアクセス許可に同意したことを確認します。ユーザーまたは管理者が同意していないアクセス許可がある場合は、必要なアクセス許可に同意するように求められます。 Microsoft Entra同意エクスペリエンスの詳細については、「アプリケーションの同意エクスペリエンス」と「アクセス許可と同意の概要」を参照してください。

次のスクリーンショットは Microsoft アカウントユーザーの同意ダイアログボックスの例です。

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 ですが、検査なしで渡される不透明な値として扱う必要があります。

3. アクセストークンを要求する

アプリは、前の手順で受け取った承認codeを使用して、エンドポイントに要求を送信してアクセストークンをPOST/token要求します。

// 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...''

パラメーター

パラメーター	必須	説明
tenant	必須	要求のパスで `{tenant}` 値を使用して、アプリケーションにサインインできるユーザーを制御できます。以下のいずれかの値を指定できます。 `common` は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。職場または学校アカウントのみの `organizations` Microsoft アカウントのみの `consumers` テナント ID やドメイン名などのテナント識別子。詳細については、「プロトコルの基本情報」を参照してください。
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 の更新トークン。アプリでは、現在のアクセストークンの有効期限が切れた後に、このトークンを使用して追加のアクセストークンを取得できます。更新トークンは有効期限が長く、長期間にわたってリソースへのアクセスを保持するために使用できます。更新トークンは、パラメーターとして`scope`含まれている場合`offline_access`にのみ返されます。詳細については、 v2.0 トークンリファレンスを参照してください。

4.アクセストークンを使用して、Microsoft Graph を呼び出す

アクセストークンを取得した後、アプリはそれを使用して、アクセストークンを ベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチすることで Microsoft Graph を呼び出します。次の要求は、サインインしたユーザーのプロファイルを取得します。

要求

HTTP
cURL

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

5. 更新トークンを使用して、期限切れのアクセストークンを更新する

アクセストークンは有効期間が短く、リソースへのアクセスを継続するには、有効期限が切れた後にアプリを更新する必要があります。アプリは、エンドポイントに/token別POSTの要求を送信することで、これを行います。今回は次のようになります。

要求本文にrefresh_tokenコードの代わりにを指定する
refresh_tokenではなくauthorization_code、 をgrant_typeとして指定します。

要求

HTTP
cURL

// 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...'

パラメーター

パラメーター	必須	説明
tenant	必須	要求のパスで `{tenant}` 値を使用して、アプリケーションにサインインできるユーザーを制御できます。以下のいずれかの値を指定できます。 `common` は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。職場または学校アカウントのみの `organizations` Microsoft アカウントのみの `consumers` テナント ID やドメイン名などのテナント識別子。詳細については、「プロトコルの基本情報」を参照してください。
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 を呼び出します。

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

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

シングルページアプリ、Web アプリ、モバイルアプリなど、さまざまな種類のアプリからユーザーの代わりに Microsoft Graph を呼び出すことができます。詳細については、「シナリオとサポートされる認証フロー」を参照してください。
サポートされている認証ライブラリ、サインインユーザー、および Microsoft Graph を呼び出すカスタムアプリを実行するために、Microsoft によって構築および管理されているコードサンプルから選択します。「Microsoft Graph のチュートリアル」を参照してください。

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

前提条件

認証および承認の手順

1. アプリを登録する

2. 承認を要求する

承認要求

パラメーター

承認応答

クエリパラメーター

3. アクセストークンを要求する

トークン要求

パラメーター

トークンの応答

応答本文のプロパティ

4.アクセストークンを使用して、Microsoft Graph を呼び出す

要求

応答

5. 更新トークンを使用して、期限切れのアクセストークンを更新する

要求

パラメーター

応答

応答本文パラメーター

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

フィードバック

フィードバック

その他のリソース

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

前提条件

認証および承認の手順

1. アプリを登録する

2. 承認を要求する

承認要求

パラメーター

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

承認応答

クエリ パラメーター

3. アクセス トークンを要求する

トークン要求

パラメーター

トークンの応答

応答本文のプロパティ

4.アクセス トークンを使用して、Microsoft Graph を呼び出す

要求

応答

5. 更新トークンを使用して、期限切れのアクセス トークンを更新する

要求

パラメーター

応答

応答本文パラメーター

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

関連コンテンツ

フィードバック

フィードバック

その他のリソース

クエリパラメーター

3. アクセストークンを要求する

4.アクセストークンを使用して、Microsoft Graph を呼び出す

5. 更新トークンを使用して、期限切れのアクセストークンを更新する