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

[アーティクル]
07/19/2022

Microsoft Graph を使用してユーザーの代理としてリソースを読み取り/書き込みするには、Microsoft ID プラットフォームからアクセストークンを取得し、Microsoft Graph に送信する要求にトークンを添付する必要があります。アクセストークンの取得に使用する認証フローは、開発しているアプリの種類と、OpenID Connect を使用してユーザーがアプリにサインインするかどうかによって異なります。ネイティブアプリ、モバイルアプリ、一部の Web アプリで使用される一般的なフローの 1 つに、OAuth 2.0 認証コードの付与フロー があります。この記事では、このフローの使用例について説明します。

認証および承認の手順

OAuth 2.0 認証コードの付与フローを使用して Microsoft ID プラットフォームのエンドポイントからアクセストークンを取得するための基本手順は次のとおりです。

Azure AD にアプリを登録する。
承認を取得する。
アクセストークンを取得する。
アクセストークンを使用して Microsoft Graph を呼び出す。
更新トークンを使用して新しいアクセストークンを取得する。

1.アプリを登録する

Microsoft ID プラットフォームのエンドポイントを使用するには、Azure アプリ登録ポータルでアプリを登録する必要があります。アプリを登録するには、Microsoft アカウントのほか、職場または学校のアカウントを使用できます。

OAuth 2.0 認証コードの付与フローを使用するようにアプリを構成するには、アプリの登録時に次の値を保存します。

アプリ登録ポータルによって割り当てられたアプリケーション (クライアント) ID。
クライアント (アプリケーション) シークレット。パスワードか、公開鍵や秘密鍵のペア (証明書) のいずれか。クライアントシークレットはネイティブアプリには必要ありません。
Azure AD からの応答を受信するためのリダイレクト URI (または応答 URL)。

Azure portal でアプリを構成する手順については、「アプリを登録する」を参照してください。

2. 承認を取得する

多くの OpenID Connect (OIDC) および OAuth 2.0 フローのアクセストークンを取得するための最初の手順は、ユーザーを Microsoft ID プラットフォーム /authorize エンドポイントにリダイレクトすることです。Azure AD はユーザーをサインインし、アプリの要求するアクセス許可にユーザーが同意していることを要求します。認証コードの許可フローでは、同意が得られた後、Azure AD が authorization_code をアプリに返します。アプリは、このコードを Microsoft ID プラットフォーム /token エンドポイントでアクセストークンと引き換えることができます。

承認要求

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

Microsoft ID プラットフォームエンドポイントでは、scope パラメーターを使用してアクセス許可が要求されます。この例で要求された Microsoft Graph のアクセス許可は、User.Read および Mail.Read で、サインインしたユーザーのプロファイルとメールをアプリが読み取ることを許可します。offline_access のアクセス許可が標準 OIDC 範囲で要求され、アプリは、現在のトークンの期限が切れたときに新しいアクセストークンを取得するための更新トークンを使用できます。

// Line breaks for legibility only

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

パラメーター	必須	説明
tenant	必須	要求のパスで `{tenant}` 値を使用して、アプリケーションにサインインできるユーザーを制御できます。許可される値は、Microsoft のアカウントと職場または学校のアカウントの両方に `common`、職場または学校のアカウントのみに `organizations`、Microsoft のアカウントのみに `consumers`。また、テナント ID やドメイン名などのテナント識別子が含まれています。詳細については、プロトコルの基本情報を参照してください。
client_id	必須	登録ポータルによってアプリに割り当てられたアプリケーション ID。
response_type	必須	認可コードのフローに `code` を含める必要があります。
redirect_uri	推奨	アプリの redirect_uri。アプリが認証応答を送受信できる場所。アプリ登録ポータルに登録した redirect_uri のいずれかと正確に一致する必要があります。ただし、URL エンコードされている必要があります。ネイティブとモバイルアプリの場合は、既定値の `https://login.microsoftonline.com/common/oauth2/nativeclient` を使用する必要があります。
スコープ	必須	ユーザーが同意する必要がある Microsoft Graph のアクセス許可をスペースで区切った一覧。これらのアクセス許可には、User.Read や Mail.Read などのリソースへのアクセス許可や、`offline_access` などの OIDC スコープが含まれる場合があります。これは、アプリがリソースに長期間アクセスするために更新トークンが必要であることを示しています。
response_mode	推奨	結果のトークンをアプリに送信するために使用するメソッドを指定します。`query` または `form_post` にできます。
state	推奨	トークン応答でも返される要求に含まれている値。任意のコンテンツの文字列にすることができます。ランダムに生成された一意の値は、通常、クロスサイトリクエストフォージェリ攻撃を防止するために使用されます。state は、使用していたページまたはビューなど、認証要求が発生する前の、アプリでのユーザーの状態に関する情報をエンコードするためにも使用されます。

注意

Microsoft Graph では、アプリケーションのアクセス許可と委任されたアクセス許可という 2 種類のアクセス許可を公開しています。サインインしたユーザーが実行するアプリの場合は、scope パラメーターで、委任されたアクセス許可を要求します。これらのアクセス許可は、サインインしたユーザーの権限をアプリに委任し、Microsoft Graph を呼び出したときに、サインインしたユーザーとして動作できるようにします。Microsoft Graph で使用できるアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

Microsoft Graph では、以下のように明確に定義された OIDC スコープも公開しています: openid、email、profile、offline_access。 address および phone の OIDC スコープはサポートしていません。各 OIDC スコープの詳細については、「アクセス許可と同意」を参照してください。

認可要求の送信後、ユーザーは Microsoft で認証するための資格情報の入力を求められます。Microsoft ID プラットフォーム v2.0 エンドポイントは、ユーザーが scope クエリパラメーターに示されているアクセス許可に同意したことを確認します。ユーザーがこれらのアクセス許可のいずれかに同意していない場合、および管理者が組織内のすべてのユーザーに代わって同意していない場合は、ユーザーに対して必要なアクセス許可に同意するよう求めます。

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

Microsoft アカウントの同意ダイアログ。

試してみましょう Microsoft アカウントや Azure AD の職場または学校のアカウントを所有している場合は、次のリンクをクリックして試してみてください。サインイン後、ブラウザーは https://localhost/myapp/ にリダイレクトされ、アドレスバーに code が表示されます。

https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

承認応答

ユーザーがアプリがリクエストした権限に同意した場合、応答には code パラメーターに承認コードが含まれます。以前の要求に対して成功した応答の例を次に示します。要求の response_mode パラメーターが query に設定されているため、応答はリダイレクト URL のクエリ文字列で返されます。

GET https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d
&state=12345

パラメーター	説明
code	アプリが要求した authorization_code。アプリは、認証コードを使用してターゲットリソースのアクセストークンを要求できます。authorization_code は短期間であり、通常は約 10 分後に期限が切れます。
state	state パラメーターが要求に含まれている場合は、同じ値が応答に表示されます。アプリは要求と応答の state 値が同じであることを確認する必要があります。この確認は、クライアントに対するクロスサイトリクエストフォージェリ (CSRF) 攻撃の検出に役立ちます。
session_state	現在のユーザーセッションを識別する一意の値。この値は GUID ですが、検査なしで渡される不透明な値として扱う必要があります。

3.トークンを取得する

アプリは前の手順で受け取った承認 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=jXoM3iz...    // NOTE: Only required for web apps

パラメーター	必須	説明
tenant	必須	要求のパスで `{tenant}` 値を使用して、アプリケーションにサインインできるユーザーを制御できます。以下のいずれかの値を指定できます。 `common` は、Microsoft アカウントと職場または学校アカウントのどちらでも有効です。職場または学校アカウントのみの `organizations` Microsoft アカウントのみの `consumers` テナント ID やドメイン名などのテナント識別子。詳細については、プロトコルの基本情報を参照してください。
client_id	必須	登録ポータルによってアプリに割り当てられたアプリケーション ID。
grant_type	必須	認可コードのフローの `authorization_code` になる必要があります。
scope	必須	スコープのスペースで区切られた一覧。この区間でアプリで要求されたスコープは、最初の (承認) 区間で要求されたスコープと同じか、サブセットである必要があります。この要求で指定されたスコープが複数のリソースサーバーにまたがる場合、v2.0 エンドポイントは最初のスコープで指定されたリソースのトークンを返します。
code	必須	フローの最初の区間で取得した authorization_code。
redirect_uri	必須	authorization_code の取得に使用されたものと同じ redirect_uri 値。
client_secret	Web アプリに必須	アプリのアプリ登録ポータルで作成したクライアントシークレット。client_secrets はデバイスに確実に保存できないため、ネイティブアプリでは使用しないでください。Web アプリと Web API に必須。これには、サーバー側に client_secret を安全に保存する機能があります。

トークンの応答

アクセストークンはアプリに対して不透明ですが、応答には、そのアクセストークンが scope パラメーターに適しているアクセス許可の一覧が含まれています。

{
    "token_type": "Bearer",
    "scope": "user.read%20Fmail.read",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}

パラメーター	説明
token_type	トークンの種類の値を示します。Azure AD がサポートしている種類はベアラーのみです。
scope	access_token が有効な Microsoft Graph のアクセス許可のスペースで区切った一覧。
expires_in	アクセストークンの有効期間 (秒単位)。
access_token	要求されたアクセストークン。アプリはこのトークンを、Microsoft Graph の呼び出しで使用できます。
refresh_token	OAuth 2.0 の更新トークン。アプリはこのトークンを使用して、現在のアクセストークンの有効期限が切れた後、追加のアクセストークンを取得します。更新トークンは有効期限が長く、長期間にわたってリソースへのアクセスを保持するために使用できます。詳細については、「Azure Active Directory v2.0 トークンリファレンス」を参照してください。

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

アクセストークンの取得後は、そのトークンを使用して (トークンを要求の Authorization ヘッダーに含める)、Microsoft Graph を呼び出すことができます。次の要求は、サインインしたユーザーのプロファイルを取得します。

GET https://graph.microsoft.com/v1.0/me
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",
    "id":"12345678-73a6-4952-a53a-e9916737ff7f",
    "businessPhones":[
        "+1 555555555"
    ],
    "displayName":"Chris Green",
    "givenName":"Chris",
    "jobTitle":"Software Engineer",
    "mail":null,
    "mobilePhone":"+1 5555555555",
    "officeLocation":"Seattle Office",
    "preferredLanguage":null,
    "surname":"Green",
    "userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}

5.更新トークンを使用して新しいアクセストークンを取得する

アクセストークンの保存期間は短く、リソースへのアクセスを続行するには期限が切れた後で更新する必要があります。これは、POST エンドポイントに別の /token 要求を送信することで行うことができます。今回は、refresh_token の代わりに code を提供します。

要求

// Line breaks for legibility only

POST /common/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

パラメーター	必須	説明
client_id	必須	登録ポータルによってアプリに割り当てられたアプリケーション ID。
grant_type	必須	`refresh_token` である必要があります。
scope	省略可能	アクセス許可 (scope) のスペースで区切られた一覧。アプリで要求されたアクセス許可は、元の authorization_code 要求で要求されたアクセス許可と同じか、サブセットである必要があります。
refresh_token	必須	トークン要求の間に取得した refresh_token。
client_secret	Web アプリに必須	アプリのアプリ登録ポータルで作成したクライアントシークレット。client_secrets はデバイスに確実に保存できないため、ネイティブアプリではシークレットを使用しないでください。Web アプリと Web API に必須。これには、サーバー側に client_secret を安全に保存する機能があります。

応答

正常なトークン応答は、次のようになります。

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "user.read%20mail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}

パラメーター	説明
access_token	要求されたアクセストークン。アプリはこのトークンを Microsoft Graph の呼び出しで使用できます。
token_type	トークンの種類の値を示します。Azure AD がサポートしている種類はベアラーのみです。
expires_in	アクセストークンの有効期間 (秒単位)。
scope	access_token が有効なアクセス許可 (scope)。
refresh_token	新しい OAuth 2.0 の更新トークン。更新トークンを可能な限り長く有効にしておくために、古い更新トークンをこの新しく取得した更新トークンと置き換えます。

サポートされているアプリのシナリオと追加のリソース

Microsoft Graph は、次に示す種類のアプリから、ユーザーの代わりに呼び出すことができます。

ネイティブ/モバイルアプリ
Web アプリ
シングルページアプリ (SPA)
バックエンド Web API: たとえば、ネイティブアプリなどのクライアントアプリが Web API のバックエンドで機能を実装するシナリオの場合。Microsoft ID プラットフォームエンドポイントでは、クライアントアプリとバックエンド Web API の両方に同じアプリケーション ID が必要です。

Microsoft ID プラットフォームのエンドポイントでサポートされているアプリのシナリオの詳細については、「アプリのシナリオおよび認証フロー」を参照してください。

注: スタンドアロンの Web API からの Microsoft Graph の呼び出しは、現在 Microsoft ID プラットフォームエンドポイントではサポートされていません。このシナリオでは、Azure AD エンドポイントを使用する必要があります。

Microsoft ID プラットフォームのエンドポイントからユーザーに代わって Microsoft Graph にアクセスする方法の詳細については、次を参照してください。

プロトコルのドキュメントへのリンクや、さまざまな種類のアプリでの作業の開始についての記事は、「Microsoft ID プラットフォームのエンドポイントのドキュメント」を参照してください。
サポートされているアプリケーションタイプと認証フローの詳細な説明については、「v2.0 アプリタイプ」を参照してください。
推奨される認証ライブラリと Microsoft ID プラットフォーム用サーバーミドルウェアの詳細については、「Azure Active Directory v2.0 認証ライブラリ」を参照してください。

エンドポイントに関する考慮事項

Microsoft では引き続き Azure AD エンドポイントをサポートします。 Microsoft ID プラットフォームのエンドポイントと Azure AD のエンドポイントの使用には、いくつかの違いがあります。 Azure AD エンドポイントを使用する場合:

アプリには、プラットフォームごとのアプリケーション ID (クライアント ID) が必要です。
アプリがマルチテナントアプリの場合は、Azure ポータルでマルチテナントとなるよう明示的に設定する必要があります。
アプリに必要なすべてのアクセス許可を開発者が構成する必要があります。Azure AD エンドポイントは、動的 (増分) の同意をサポートしていません。
Azure AD エンドポイントは、承認とトークンの要求に resource パラメーターを使用して、アクセス許可が必要な Microsoft Graph などのリソースを指定します。エンドポイントは scope パラメーターをサポートしていません。
Azure AD エンドポイントは、管理者の同意用に特定のエンドポイントを公開しません。その代わりに、アプリは承認要求で prompt=admin_consent パラメーターを使用して、組織の管理者の同意を取得します。詳細については、「Azure Active Directory とアプリケーションの統合」の「実行時の Azure AD 同意フレームワークのトリガー」を参照してください。

ユーザーに代わって Microsoft Graph にアクセスする方法の詳細については、次のリソースを参照してください。

さまざまな種類のアプリで Microsoft ID プラットフォームを使用する方法については、「Microsoft ID プラットフォームのドキュメント」の「はじめに」リンクを参照してください。
Microsoft ID プラットフォームのエンドポイントで使用可能な Microsoft Authentication Library (MSAL) およびサーバーミドルウェアの詳細については、「Microsoft Authentication Library」を参照してください。

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

認証および承認の手順

1.アプリを登録する

2. 承認を取得する

承認要求

承認応答

3.トークンを取得する

トークン要求

トークンの応答

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

5.更新トークンを使用して新しいアクセストークンを取得する

要求

応答

サポートされているアプリのシナリオと追加のリソース

エンドポイントに関する考慮事項

関連項目

フィードバック

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

認証および承認の手順

1.アプリを登録する

2. 承認を取得する

承認要求

同意エクスペリエンス

承認応答

3.トークンを取得する

トークン要求

トークンの応答

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

5.更新トークンを使用して新しいアクセス トークンを取得する

要求

応答

サポートされているアプリのシナリオと追加のリソース

エンドポイントに関する考慮事項

関連項目

フィードバック

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

5.更新トークンを使用して新しいアクセストークンを取得する