次の方法で共有

同意によるアクセス許可の要求

  • [アーティクル]

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

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

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

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

静的な同意と単一のアクセス許可リストに依存することで、コードは適切でシンプルに保たれますが、アプリが事前に必要とする可能性のあるすべてのアクセス許可を要求することも意味します。 これにより、ユーザーと管理者がアプリのアクセス要求を承認できない可能性があります。

Microsoft ID プラットフォーム エンドポイントでは、Microsoft Entra 管理センターのアプリケーション登録情報で定義されている静的なアクセス許可を無視できます。 代わりに、アクセス許可を段階的に要求できます。 ユーザーが追加のアプリケーション機能を使用する際に、最小限のアクセス許可セットを事前に要求して、時間をかけてより多くを要求することができます。 これを行うために、任意の時点でアプリケーションに必要なスコープを指定できます。その場合、アクセス トークンの要求時に scope パラメーターに新しいスコープを含めます。アプリケーションの登録情報で事前に定義する必要はありません。 要求に追加された新しいスコープにユーザーがまだ同意していない場合、新しいアクセス許可のみの同意を求められます。 増分または動的な同意は、委任されたアクセス許可にのみ適用され、アプリケーションのアクセス許可には適用されません。

scope パラメーターを使用してアプリケーションからアクセス許可を動的に要求できるため、開発者はユーザーの操作を完全に制御できます。 同意操作を初期段階に組み込み、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 プラットフォームは、"ユーザーの同意" の一致するレコードがないか確認します。 ユーザーが過去に要求されたどのアクセス許可にも同意しておらず、管理者も組織全体の代わりにそれらのアクセス許可に同意していない場合、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 プラットフォームの承認、トークン、または同意エンドポイントへの要求では、スコープ パラメーターでリソース識別子が省略されている場合、リソースは Microsoft Graph と見なされます。 たとえば、scope=User.Read は https://graph.microsoft.com/User.Read と同等です。

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

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

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

通常、管理者の同意を必要とするアプリケーションを構築する場合、そのアプリケーションには、管理者がアプリのアクセス許可を承認できるページまたはビューが必要です。 このページとして以下が考えられます。

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

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

ユーザーをアプリにサインインさせると、必要なアクセス許可の承認をユーザーに依頼する前に、管理者が所属する組織を識別できます。 この手順は必須ではありませんが、組織のユーザーに向けたより直観的なエクスペリエンスの作成に役立ちます。

ユーザーをサインインさせるには、Microsoft ID プラットフォーム プロトコルのチュートリアルに従ってください。

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

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

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

注意

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

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

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

成功応答

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

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 プラットフォーム エンドポイント プロトコルのリファレンスを参照してください。

関連項目