Microsoft ID プラットフォームでのアクセス許可と同意の要求に関する開発者ガイド - Microsoft identity platform

2025-05-21

Microsoft ID プラットフォームのアプリケーションは、必要なリソースまたは API にアクセスするために同意に依存します。異なる種類の同意は、さまざまなアプリケーションシナリオに適しています。アプリの同意に最適なアプローチを選択すると、ユーザーや組織で成功を収められます。

この記事では、さまざまな種類の同意と、同意を通じてアプリケーションのアクセス許可を要求する方法について説明します。

静的ユーザーの同意シナリオでは、Microsoft Entra 管理センターのアプリの構成で必要なすべてのアクセス許可を指定する必要があります。ユーザー (または必要に応じて管理者) がこのアプリに同意しない場合、Microsoft ID プラットフォームは、現時点でユーザーに同意を求めます。

静的なアクセス許可により、管理者は、組織内のすべてのユーザーの代理として同意することができます。

静的な同意と 1 つのアクセス許可リストに依存することで、コードはわかりやすくシンプルに保たれ、アプリが必要とするすべてのアクセス許可を事前に要求することも意味します。この設定は、ユーザーと管理者がアプリのアクセス要求を承認するのを防げる可能性があります。

Microsoft ID プラットフォームエンドポイントでは、Microsoft Entra 管理センターのアプリケーション登録情報で定義されている静的アクセス許可を無視できます。代わりに、アクセス許可を段階的に要求できます。最小限のアクセス許可のセットを事前に要求し、顧客がより多くのアプリケーション機能を使用するにつれて、時間の経過と同時により多くの要求を行うことができます。これを行うには、アクセストークンを要求するときに scope パラメーターに新しいスコープを含めることで、アプリケーションが必要とするスコープをいつでも指定できます。アプリケーション登録情報に事前に定義する必要はありません。

ユーザーが要求に追加された新しいスコープに同意しない場合は、新しいアクセス許可のみに同意するように求められます。増分同意または動的同意は、委任されたアクセス許可にのみ適用され、アプリケーションのアクセス許可には適用されません。

scope パラメーターを使用してアプリケーションがアクセス許可を動的に要求できるようにすると、開発者はユーザーのエクスペリエンスを完全に制御できます。最初に同意エクスペリエンスを読み込み、1 回の初期承認要求ですべてのアクセス許可を要求します。アプリケーションで多数のアクセス許可が必要な場合は、時間の経過と同時にアプリケーションの特定の機能を使用しようとするときに、ユーザーからそれらのアクセス許可を段階的に収集できます。

重要

動的同意は便利ですが、管理者の同意を必要とするアクセス許可には大きな課題があります。ポータルの [アプリの登録] および [エンタープライズアプリケーション] ブレードにおける管理者の同意のエクスペリエンスでは、同意の時点でこれらの動的アクセス許可が認識されていません。開発者は、アプリケーションに必要なすべての管理者特権アクセス許可をポータルに一覧表示することをお勧めします。

これにより、テナント管理者はポータル内のすべてのユーザーに代わって 1 回同意できます。ユーザーは、サインイン時にこれらのアクセス許可に同意する必要はありません。代わりに、これらのアクセス許可に動的な同意を使用します。管理者の同意を付与するには、個々の管理者がアプリにサインインし、適切なアクセス許可の同意プロンプトをトリガーし、同意ダイアログで 組織全体の同意 を選択します。

OpenID Connect または OAuth 2.0 承認要求では、アプリケーションは scope クエリパラメーターを使用して、必要なアクセス許可を要求できます。たとえば、ユーザーがアプリにサインインすると、アプリケーションは次の例のような要求を送信します。 (改行は読みやすくするために追加されます)。

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

scope パラメーターは、アプリケーションが要求している委任されたアクセス許可のスペース区切りの一覧です。各アクセス許可は、リソースの識別子 (アプリケーション ID URI) にアクセス許可の値を追加して示されます。要求の例では、アプリケーションには、ユーザーの予定表を読み取り、ユーザーとしてメールを送信するためのアクセス許可が必要です。

サインイン後、Microsoft ID プラットフォームは既存のユーザーの同意を確認します。ユーザーが要求されたアクセス許可を承認せず、管理者も承認しない場合、プラットフォームはユーザーに同意を求めます。

次の例では、 offline_access ("アクセス権を付与するデータへのアクセスを維持する") アクセス許可と User.Read ("サインインしてプロファイルを読み取る") アクセス許可が、アプリケーションへの最初の同意に自動的に含まれます。これらのアクセス許可は、適切なアプリケーション機能のために必要です。

offline_accessアクセス許可は、ネイティブアプリと Web アプリにとって重要な更新トークンへのアクセス権をアプリケーションに付与します。 User.Readアクセス許可は、sub要求へのアクセスを許可します。これにより、クライアントまたはアプリケーションは、時間の経過と同時にユーザーを正しく識別し、基本的なユーザー情報にアクセスできます。

ユーザーがアクセス許可要求を承認すると、同意が記録されます。ユーザーが後でアプリケーションにサインインするときに、もう一度同意する必要はありません。

テナント全体の同意を要求するには、管理者の同意が必要です。組織に代わって行われる管理者の同意には、アプリに登録されている静的アクセス許可が必要です。組織全体に代わって管理者が同意する必要がある場合は、アプリ登録ポータルでこれらのアクセス許可を設定します。

アプリが管理者の同意を必要とする委任されたアクセス許可を要求すると、ユーザーに "同意が承認されていません" というエラーが表示され、管理者にアクセスを求める必要があります。管理者がテナント全体の同意を付与すると、同意が取り消されるか、新しいアクセス許可が追加されない限り、ユーザーは再びプロンプトを表示されません。

同じアプリケーションを使用している管理者には、管理者の同意プロンプトが表示されます。管理者の同意プロンプトには、テナント全体のユーザーに代わって、要求されたデータへのアクセス権をアプリケーションに付与できるチェックボックスが表示されます。ユーザーと管理者の同意エクスペリエンスの詳細については、「アプリケーションの同意エクスペリエンス」を参照してください。

管理者の同意を必要とする Microsoft Graph の委任されたアクセス許可の例を次に示します。

User.Read.All を使用したすべてのユーザーの完全なプロファイルの読み取り
Directory.ReadWrite.All を使用した組織のディレクトリへのデータの書き込み
Groups.Read.All を使用した組織のディレクトリ内の全グループの読み取り

Microsoft Graph のアクセス許可の完全な一覧を表示するには、 Microsoft Graph のアクセス許可のリファレンスを参照してください。

管理者の同意を必要とするように、独自のリソースに対するアクセス許可を構成することもできます。管理者の同意を必要とするスコープを追加する方法の詳細については、「管理者の同意を必要とするスコープを追加する」を参照してください。

一部の組織では、テナントの既定のユーザー同意ポリシーが変更される場合があります。アプリケーションがアクセス許可へのアクセスを要求すると、これらのポリシーに対して評価されます。既定では必要ない場合でも、ユーザーは管理者の同意を要求する必要がある場合があります。管理者がアプリケーションの同意ポリシーを管理する方法については、「アプリの同意ポリシーの管理」を参照してください。

注

Microsoft ID プラットフォームの承認、トークン、または同意要求では、 scope パラメーターのリソース識別子を省略すると、既定で Microsoft Graph が使用されます。たとえば、 scope=User.Read は https://graph.microsoft.com/User.Readとして扱われます。

アプリケーションのアクセス許可には、常に管理者の同意が必要です。アプリケーションのアクセス許可にはユーザーコンテキストがなく、特定のユーザーに代わって同意付与が行われることはありません。クライアントアプリケーションには直接的にアクセス許可が付与されます。これらの種類のアクセス許可は、デーモンサービスおよびバックグラウンドで実行される他の非対話型アプリケーションでのみ使用されます。管理者は、事前にアクセス許可を構成し、Microsoft Entra 管理センターを通じて管理者の同意を付与する必要があります。

アクセス許可を要求するアプリケーションがマルチテナントアプリケーションの場合、そのアプリケーションの登録は作成されたテナントにのみ存在するため、ローカルテナントでアクセス許可を構成することはできません。アプリケーションが管理者の同意を必要とするアクセス許可を要求する場合、管理者はユーザーの代わりに同意する必要があります。これらのアクセス許可に同意するには、管理者がアプリケーション自体にサインインする必要があるため、管理者の同意サインインエクスペリエンスがトリガーされます。マルチテナントアプリケーションの管理者の同意エクスペリエンスを設定する方法については、「マルチテナントログインを有効にする」を参照してください。

管理者は、次のオプションを使用して、アプリケーションの同意を付与できます。

推奨:ユーザーをアプリにサインインさせる

通常、管理者の同意を必要とするアプリケーションをビルドする場合、アプリケーションには、管理者がアプリのアクセス許可を承認できるページまたはビューが必要です。このページは次のようになります。

アプリのサインアップフローの一部。
アプリの設定の一部。
専用の "接続" フロー。

多くの場合、ユーザーが職場の Microsoft アカウントまたは学校の Microsoft アカウントでサインインした後にのみ、アプリケーションで "接続" ビューを表示するのが理にかなっています。

アプリにユーザーをサインインさせると、必要なアクセス許可の承認を求める前に、管理者が属する組織を特定できます。この手順は厳密には必要ではありませんが、組織のユーザーにとってより直感的なエクスペリエンスを作成するのに役立ちます。

ユーザーにサインインするには、Microsoft ID プラットフォームプロトコルのチュートリアルに従います。

アプリケーション登録ポータルでアクセス許可を要求する

アプリ登録ポータルでは、委任されたアクセス許可とアプリケーションのアクセス許可の両方を含め、アプリケーションで必要なアクセス許可を一覧表示できます。このセットアップでは、 .default スコープと Microsoft Entra 管理センターの [ 管理者の同意の付与] オプションを使用できます。

一般に、アクセス許可は特定のアプリケーションに対して静的に定義する必要があります。これらは、アプリケーションが動的または増分的に要求するアクセス許可のスーパーセットである必要があります。

注

アプリケーションのアクセス許可は、 .defaultを使用してのみ要求できます。そのため、アプリケーションにアプリケーションのアクセス許可が必要な場合は、それらがアプリ登録ポータルに一覧表示されていることを確認します。

アプリケーションに対して静的に要求されたアクセス許可の一覧を構成するには:

クラウドアプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
Entra ID>アプリケーションの登録>すべてのアプリケーションに移動します。
アプリケーションを選択するか、まだ作成していない場合はアプリを作成します。
アプリケーションの [概要] ページで、[管理] で [API のアクセス許可] を選択>アクセス許可を追加します。
使用可能な API の一覧から Microsoft Graph を選択します。次に、アプリケーションに必要なアクセス許可を追加します。
アクセス許可の追加 を選択します。

成功応答

管理者がアプリのアクセス許可を承認した場合、成功した応答は次のようになります。

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True

パラメーター	説明
`tenant`	アプリケーションに要求されたアクセス許可を GUID 形式で付与したディレクトリテナント。
`state`	トークン応答で返される要求に含まれる値。任意のコンテンツの文字列を指定することができます。状態は、認証要求が発生する前のアプリケーション内のユーザーの状態 (ページやビューなど) に関する情報をエンコードするために使用されます。
`admin_consent`	`True`に設定されます。

管理者の同意エンドポイントから正常な応答を受け取ると、アプリケーションには要求されたアクセス許可が付与されます。次に、必要なリソースのトークンを要求できます。

エラー応答

管理者がアプリのアクセス許可を承認しない場合、失敗した応答は次のようになります。

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request

パラメーター	説明
`error`	発生するエラーの種類を分類するために使用できるエラーコード文字列。また、エラーに対応するためにも使用できます。
`error_description`	開発者がエラーの根本原因を特定するのに役立つ特定のエラーメッセージ。

ユーザーがアプリのアクセス許可に同意すると、アプリケーションは、一部の容量でリソースにアクセスするためのアプリのアクセス許可を表すアクセストークンを取得できます。アクセストークンは、1 つのリソースにのみ使用できます。ただし、アクセストークン内でエンコードされるのは、そのリソースに対してアプリケーションに付与されるすべてのアクセス許可です。アクセストークンを取得するために、アプリケーションは次のように Microsoft ID プラットフォームトークンエンドポイントに要求を行うことができます。

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

結果のアクセストークンは、リソースへの HTTP 要求で使用できます。これは、アプリケーションが特定のタスクを実行するための適切なアクセス許可を持っていることをリソースに確実に示します。

OAuth 2.0 プロトコルとアクセストークンを取得する方法の詳細については、 Microsoft ID プラットフォームエンドポイントプロトコルリファレンスを参照してください。

次の方法で共有

Microsoft Identity Platform でのアクセス許可と同意の要求に関する開発者ガイド

静的なユーザーの同意

増分および動的なユーザーの同意

個々のユーザーの同意を要求する

管理者の同意を通じてテナント全体の同意を要求する

委任されたアクセス許可の管理者の同意

アプリケーションのアクセス許可に対する管理者の同意

マルチテナント アプリケーションの管理者の同意

推奨:ユーザーをアプリにサインインさせる

アプリケーション登録ポータルでアクセス許可を要求する

成功応答

エラー応答

同意後のアクセス許可の使用

関連コンテンツ

フィードバック

その他のリソース

マルチテナントアプリケーションの管理者の同意