ユーザーの代わりにアクセスを取得
[アーティクル] 2024/10/14
18 人の共同作成者
フィードバック
この記事の内容
前提条件
手順 1: 承認を要求する
手順 2: アクセス トークンを要求する
手順 3: アクセス トークンを使用して Microsoft Graph を呼び出す
手順 4: 更新トークンを使用して、期限切れのアクセス トークンを更新する
Microsoft 認証ライブラリ (MSAL) を使用する
関連コンテンツ
さらに 3 個を表示
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。
承認コード フローの最初の手順は、ユーザーがアプリに代わって動作することを承認することです。
フローでは、アプリはユーザーを 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'
テーブルを展開する
パラメーター
必須
説明
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 などのリソースのアクセス許可や、 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 ですが、検査なしで渡される不透明な値として扱う必要があります。
アプリは、前の手順で受け取った承認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...''
テーブルを展開する
パラメーター
必須
説明
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 の更新トークン。 アプリでは、現在のアクセス トークンの有効期限が切れた後に、このトークンを使用して追加のアクセス トークンを取得できます。 更新トークンは有効期限が長く、長期間にわたってリソースへのアクセスを保持するために使用できます。 更新トークンは、 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
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...'
テーブルを展開する
パラメーター
必須
説明
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 のチュートリアル」を 参照してください。