Microsoft ID プラットフォームでのアクセス許可と同意

Microsoft ID プラットフォームと統合するアプリケーションは、データにアクセスする方法をユーザーと管理者が制御できるようにする承認モデルに従います。 Microsoft ID プラットフォームで、承認モデルの実装が更新されました。 アプリが Microsoft ID プラットフォームと対話する方法が変更されています。 この記事では、スコープ、アクセス許可、同意など、この承認モデルの基本的な概念について説明します。

スコープとアクセス許可

Microsoft ID プラットフォームでは、OAuth 2.0 承認プロトコルが実装されています。 OAuth 2.0 は、ユーザーに代わってサードパーティのアプリが Web でホストされるリソースにアクセスできる方法です。 Microsoft ID プラットフォームと統合される、Web でホストされるすべてのリソースは、リソース識別子つまり "アプリケーション ID URI" を持っています。

Microsoft の Web でホストされるリソースの例をいくつか次に示します。

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 メール API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Microsoft ID プラットフォームと統合されたサードパーティのリソースも同様です。 これらのリソースのいずれでも、機能をより小さいまとまりに分割するために使用できるアクセス許可のセットを定義できます。 たとえば、Microsoft Graph では、特に次のタスクを実行するアクセス許可が定義されています。

  • ユーザーの予定表の読み取り
  • ユーザーの予定表への書き込み
  • ユーザーとしてのメールの送信

これらの種類のアクセス許可が定義されていることで、リソースでは、データと、API 機能を公開する方法を、きめ細かく制御できます。 サード パーティのアプリでは、ユーザーや管理者にこれらのアクセス許可を要求でき、ユーザーや管理者が承認してからでなければ、アプリはデータにアクセスしたり、ユーザーの代理として動作したりできません。

リソースの機能を細かいアクセス許可セットにまとめると、サードパーティのアプリを、その機能を実行するために必要なアクセス許可のみを要求するように構築できます。 ユーザーと管理者は、アプリによってアクセスできるデータを把握できます。 また、アプリが悪意のある目的を持って動作していないことも確信できます。 開発者は常に最小限の特権の原則に従って、アプリケーションが機能するために必要なアクセス許可のみを要求する必要があります。

OAuth 2.0 では、これらの種類のアクセス許可セットは "スコープ" と呼ばれます。 "アクセス許可" と呼ばれることもよくあります。 Microsoft ID プラットフォームでは、アクセス許可は文字列値として表現されます。 scope クエリ パラメーターでアクセス許可を指定することによって、アプリが必要なアクセス許可を要求します。 ID プラットフォームは、いくつかの適切に定義された OpenID connect スコープ とリソースベースのアクセス許可をサポートします (各アクセス許可は、リソースの識別子またはアプリケーション ID の URI にアクセス許可値を追加することによって示されます)。 たとえば、アクセス許可文字列 https://graph.microsoft.com/Calendars.Read を使用して、Microsoft Graph のユーザーの予定表を読み取るアクセス許可を要求します。

アプリでは、通常、Microsoft ID プラットフォーム承認エンドポイントへの要求でスコープを指定することにより、これらのアクセス許可を要求します。 ただし、一部の高い特権のアクセス許可は、管理者の同意によってのみ許可することができます。 これらは、管理者の同意エンドポイントを使用して要求または付与できます。 詳細については、この後の説明を参照してください。

Microsoft ID プラットフォームの承認、トークン、または同意エンドポイントへの要求では、スコープ パラメーターでリソース識別子が省略されている場合、リソースは Microsoft Graph と見なされます。 たとえば、scope=User.Read は、https://graph.microsoft.com/User.Read と同じです。

アクセス許可の種類

Microsoft ID プラットフォームでは、 "委任されたアクセス許可" と "アプリケーションのアクセス許可" という 2 種類のアクセス許可がサポートされています。

  • 委任されたアクセス許可 は、サインインしているユーザーが存在するアプリで使用されます。 これらのアプリでは、アプリが要求するアクセス許可にユーザーまたは管理者が同意します。 目的のリソースに対する呼び出しを行うときにサインインしたユーザーとして振る舞う権限を、アプリに委任します。

    一部の委任されたアクセス許可には、管理者以外のユーザーが同意できます。 ただし、高い特権のアクセス許可には管理者の同意が必要です。 委任されたアクセス許可に同意できる管理者ロールについては、Azure Active Directory (Azure AD) での管理者ロールのアクセス許可に関する記事を参照してください。

  • アプリケーションのアクセス許可 は、サインインしているユーザーが存在しない状態で実行されるアプリ (バックグラウンド サービスまたはデーモンとして実行されるアプリなど) で使用されます。 アプリケーションのアクセス許可に同意できるのは管理者だけです。

"有効なアクセス許可" は、アプリがターゲット リソースに要求を行うときに持っているアクセス許可です。 アプリに付与される委任されたアクセス許可とアプリケーションのアクセス許可の違い、およびアプリがターゲット リソースへの呼び出しを行うときに付与される有効なアクセス許可について理解しておくことが重要です。

  • 委任されたアクセス許可の場合、アプリの "有効なアクセス許可" は、(同意によって) アプリに付与されている委任されたアクセス許可と現在サインインしているユーザーの特権に共通する部分の最小特権です。 サインインしているユーザーよりも多くの特権をアプリに付与することはできません。

    組織内では、サインインしているユーザーの特権は、ポリシーによって決定することも、1 つ以上の管理者ロールのメンバーシップによって決定することもできます。 委任されたアクセス許可に同意できる管理者ロールについては、「Azure AD での管理者ロールのアクセス許可」を参照してください。

    たとえば、委任されたアクセス許可として User.ReadWrite.All がアプリに付与されているものとします。 通常、このアクセス許可は、組織内のすべてのユーザーのプロファイルを読み取り、更新する権限をアプリに付与します。 サインインしているユーザーが全体管理者の場合、アプリは組織内のすべてのユーザーのプロファイルを更新できます。 ただし、サインインしているユーザーに管理者ロールがない場合、アプリが更新できるのは、サインインしているユーザーのプロファイルだけです。 アプリにはユーザーの代理で動作するためのアクセス許可が付与されていますが、そのユーザーに組織内の他のユーザーのプロファイルを更新する権限がないため、アプリがこれを実行することはできません。

  • アプリケーションのアクセス許可の場合、アプリの "有効なアクセス許可" は、そのアクセス許可が暗示する完全なレベルの権限になります。 たとえば、アプリケーションのアクセス許可として User.ReadWrite.All が付与されているアプリは、組織内のすべてのユーザーのプロファイルを更新できます。

OpenID Connect のスコープ

OpenID Connect の Microsoft ID プラットフォーム実装には、Microsoft Graph でもホストされている適切に定義されたスコープ openidemailprofileoffline_access があります。 addressphone の OpenID Connect スコープはサポートされていません。

OpenID Connect スコープとトークンを要求すると、UserInfo エンドポイントを呼び出すためのトークンを取得します。

openid

アプリは、OpenID Connect を使用してサインインする場合、openid スコープを要求する必要があります。 openid スコープは、職場アカウントの同意ページでは サインイン アクセス許可として表示されます。 個人用 Microsoft アカウントの同意ページでは、プロフィールの表示と、Microsoft アカウントを使うアプリとサービスへの接続 アクセス許可として表示されます。

このアクセス許可を使用して、sub 要求の形式でユーザーの一意の識別子をアプリが受け取ることができます。 このアクセス許可により、アプリは UserInfo エンドポイントにもアクセスできます。 openid スコープは、Microsoft ID プラットフォーム トークン エンドポイントで ID トークンを取得するために使用できます。 これらのトークンは、アプリが認証に使用できます。

email

email スコープは openid スコープやその他のスコープと共に使用できます。 これにより、アプリがユーザーのプライマリ電子メール アドレスに email 要求の形式でアクセスできます。

電子メール アドレスがユーザー アカウントと関連付けられている場合のみ (常にではありません)、email 要求はトークンに含まれます。 アプリは、email スコープを使用する場合は、トークン内に email 要求が存在しない状況に対応できる必要があります。

プロファイル

profile スコープは openid スコープやその他のスコープと共に使用できます。 これにより、アプリはユーザーの多くの情報にアクセスできます。 アプリがアクセスできる情報には、ユーザーの名、姓、希望するユーザー名、オブジェクト ID などがありますが、これらに限定されるものではありません。

特定のユーザーに対して id_tokens パラメーターで使用できる profile 要求の完全な一覧については、id_tokens のリファレンスをご覧ください。

offline_access

offline_accessスコープを使用すると、アプリはユーザーの代わりに、長期間にわたってリソースにアクセスできます。 同意ページで、このスコープは、アクセス権を与えたデータへのアクセスを管理する アクセス許可として表示されます。

ユーザーが offline_access スコープを承認すると、アプリは Microsoft ID プラットフォーム トークン エンドポイントから更新トークンを取得できます。 更新トークンの有効期間は長期です。 アプリは、古いアクセス トークンの有効期限が切れると、新しいアクセス トークンを取得できます。

注意

このアクセス許可は、更新トークンを提供しないフロー (暗黙的フローなど) も含め、現在すべての同意ページに表示されます。 この設定は、クライアントが暗黙的フロー内で開始した後、更新トークンが予測されるコード フローに移行することができるシナリオに対応します。

Microsoft ID プラットフォーム (要求は v2.0 エンドポイントに対して行われます) では、更新トークンを受信するには、アプリが offline_access スコープを明示的に要求する必要があります。 そのため、OAuth 2.0 承認コード フローの承認コードを使用すると、/token エンドポイントからアクセス トークンだけが取得されます。

アクセス トークンの有効期間は短期です。 通常は、1 時間以内に期限切れとなります。 その時点で、アプリはユーザーを /authorize エンドポイントにリダイレクトして、新しい承認コードを取得する必要があります。 このリダイレクト中に、アプリの種類によっては、ユーザーが資格情報を再入力したり、アクセス許可に再同意したりする必要がある場合もあります。

更新トークンの取得方法と使用方法の詳細については、Microsoft ID プラットフォーム プロトコルのリファレンスを参照してください。

Microsoft ID プラットフォームのアプリケーションでは、必要なリソースや API へのアクセス権を取得するために同意を利用します。 成功を収めるために、アプリが認識しておく必要があると考えられる多くの種類の同意があります。 アクセス許可を定義する場合は、ユーザーがアプリや API へのアクセス権を取得する方法も理解しておく必要があります。

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

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

アプリの静的アクセス許可は Azure portal で定義されており、コードを適切に維持できますが、開発者にとってはそれがいくつかの問題を引き起こす場合があります。

  • アプリで、ユーザーの初回サインインの時点で必要になる可能性があるすべてのアクセス許可を要求する必要があります。 アクセス許可のリストは長くなる場合があり、エンドユーザーが初回サインイン時にアプリのアクセスを承認することを阻げる要因となります。

  • アプリでアクセスする可能性のあるすべてのリソースが事前にわかっている必要があります。 不特定の数のリソースにアクセスする可能性があるアプリを作成することは、困難です。

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

scope パラメーターを使用してアプリからアクセス許可を動的に要求できるため、開発者はユーザーの操作を完全に制御できます。 同意操作を初期段階に組み込み、1 回の初期承認要求ですべてのアクセス許可を求めることもできます。 アプリで多数のアクセス許可が必要な場合は、時間の経過と共に、ユーザーがアプリの特定の機能を使用するときにアクセス許可を集めることができます。

重要

動的な同意は便利な場合もありますが、管理者の同意を必要とするアクセス許可の場合、管理者の同意エクスペリエンスで同意する時点でこれらのアクセス許可を把握できないため、大きな問題が生じます。 管理者特権のアクセス許可が必要な場合、またはアプリが動的な同意を使用する場合は、Azure portal で (管理者の同意が必要なアクセス許可のサブセットだけでなく) すべてのアクセス許可を登録する必要があります。 これにより、テナント管理者が、すべてのユーザーを代表して同意できます。

管理者の同意は、特定の高い権限のアクセス許可がアプリに必要な場合に必要となります。 管理者の同意により、管理者は、組織の高い権限が必要なデータにアプリやユーザーがアクセスすることを承認する前に制御を強化できます。

組織の代わりに管理者が同意する場合でも、アプリに静的なアクセス許可が登録されている必要があります。 管理者に組織全体の代理として同意してもらう必要がある場合には、アプリ登録ポータルでアプリのそれらのアクセス許可を設定します。 これにより、アプリケーションを設定するために組織の管理者に必要なサイクルが減ります。

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

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 のリソースにおける高い特権のアクセス許可には、"管理者によって制限されている" に設定できるものがあります。 これらの種類のアクセス許可の例をいくつか、次に示します。

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

注意

Microsoft ID プラットフォームの承認、トークン、または同意エンドポイントへの要求では、スコープ パラメーターでリソース識別子が省略されている場合、リソースは Microsoft Graph と見なされます。 たとえば、scope=User.Read は、https://graph.microsoft.com/User.Read と同じです。

コンシューマー ユーザーがこの種類のデータへのアプリケーション アクセスを許可する場合がありますが、組織のユーザーは会社の同じ機密データへのアクセスを許可することはできません。 アプリケーションが組織のユーザーにこれらのアクセス許可のいずれかへのアクセスを要求すると、ユーザーは、アプリのアクセス許可に同意する権限がないという内容のエラー メッセージを受け取ります。

アプリが管理者によって制限されたアクセス許可のスコープを必要とする場合、組織の管理者は、組織のユーザーの代わりにこれらのスコープに同意する必要があります。 許可できないアクセス許可の同意を要求するプロンプトがユーザーに表示されないようにする場合、アプリでは管理者の同意エンドポイントを使用できます。 管理者の同意エンドポイントについては、次のセクションで説明します。

アプリケーションが高い特権の委任されたアクセス許可を要求していて、管理者の同意エンドポイントを介して管理者がこれらのアクセス許可を付与すると、テナントのユーザー全員に対して同意が付与されます。

アプリケーションがアプリケーションのアクセス許可を要求していて、管理者が管理者の同意エンドポイントを介してこれらのアクセス許可を付与する場合、この許可は特定のユーザーに代わっては行われません。 代わりに、クライアント アプリケーションはアクセス許可を "直接" 付与されます。 これらの種類のアクセス許可は、バックグラウンドで実行されるデーモン サービスと他の非対話型アプリケーションでのみ使用されます。

管理者の同意エンドポイントを使用して管理者の同意を付与したら、それで終了です。 ユーザーはそれ以上の操作を行う必要はありません。 管理者の同意が付与されると、ユーザーは一般的な認証フローを使用してアクセス トークンを取得できます。 結果として得られたアクセス トークンには、同意済みのアクセス許可が含まれています。

全体管理者がアプリケーションを使用していて、承認エンドポイントに送られると、Microsoft ID プラットフォームによってユーザーのロールが検出されます。 全体管理者がテナント全体に代わり、要求されたアクセス許可に対して同意するかどうかが尋ねられます。 その代わりに、専用の管理者の同意エンドポイントを使用して、テナント全体に代わってアクセス許可を付与するように管理者に事前に要求することもできます。 このエンドポイントは、アプリケーションのアクセス許可を要求する場合にも必要です。 アプリケーションのアクセス許可は、承認エンドポイントを使用して要求することはできません。

これから説明する手順に従うと、管理者に制限されているスコープを含むテナントのユーザー全員のアクセス許可をアプリで要求できます。 この操作には高い特権があります。 この操作は、ご自身のシナリオに必要な場合にだけ使用してください。

手順を実装するコード サンプルについては、GitHub の管理者に制限されているスコープのサンプルを参照してください。

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

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

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

注意

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

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

  1. Azure portal の [アプリの登録] クイックスタート エクスペリエンス内のアプリケーションに移動します。
  2. アプリケーションを選択するか、まだ作成していない場合はアプリを作成します。
  3. アプリケーションの [概要] ページの [管理] で、 [API のアクセス許可] > [アクセス許可の追加] の順に選択します。
  4. 利用可能な API の一覧から [Microsoft Graph] を選択します。 次に、アプリに必要なアクセス許可を追加します。
  5. [アクセス許可の追加] を選択します。

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

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

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

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

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

ディレクトリ管理者にアクセス許可を要求する

組織の管理者にアクセス許可を要求する準備ができたら、Microsoft ID プラットフォームの管理者の同意エンドポイントにユーザーをリダイレクトできます。

// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
&scope=
https://graph.microsoft.com/calendars.read
https://graph.microsoft.com/mail.send
パラメーター 条件 説明
tenant 必須 アクセス許可を要求するディレクトリ テナント。 これは GUID またはフレンドリ名の形式で指定できます。 または、例に示すように、組織で汎用的に参照することもできます。 "common" は使用しないでください。個人のアカウントでは、テナントのコンテキスト以外で管理者の同意を提供できないためです。 テナントを管理する個人用アカウントとの最善の互換性を確保するには、可能であればテナント ID を使用します。
client_id 必須 Azure portal の [アプリの登録] エクスペリエンスでアプリに割り当てられたアプリケーション (クライアント) ID。
redirect_uri 必須 処理するアプリの応答の送信先となるリダイレクト URI。 アプリケーション登録ポータルで登録したリダイレクト URI のいずれかと完全に一致させる必要があります。
state 推奨 要求に含まれ、かつトークンの応答として返される値。 任意のコンテンツの文字列を指定することができます。 この状態は、認証要求の前にアプリ内でユーザーの状態 (表示中のページやビューなど) に関する情報をエンコードする目的に使用します。
scope 必須 アプリケーションによって要求されるアクセス許可のセットを定義します。 スコープは静的 (/.default を使用) または動的です。 このセットには、OpenID Connect スコープ (openidprofileemail) を含めることができます。 アプリケーションのアクセス許可が必要な場合は、/.default を使用して、静的に構成されたアクセス許可の一覧を要求する必要があります。

現在 Azure AD では、テナント管理者がサインインして、要求を完了する必要があります。 管理者は、ユーザーが scope パラメーターで要求したすべてのアクセス許可を承認するように求められます。 静的な (/.default) 値を使用した場合、それは v1.0 管理者の同意エンドポイントのように機能し、アプリに必要なアクセス許可で見つかったすべてのスコープに対する同意を要求します。

成功応答

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

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&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": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/mail.read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

リソースへの HTTP 要求では、取得したアクセス トークンを使用できます。 アクセス トークンはリソースに対して、特定のタスクを行う適切なアクセス許可がアプリにあることを確実に示すことができます。

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

/.default スコープ

/.default スコープを使用すると、v1.0 エンドポイントから Microsoft ID プラットフォーム エンドポイントにアプリを移行するのに役立ちます。 /.default スコープは、アプリケーション登録で構成されたアクセス許可の静的一覧を参照するすべてのアプリケーションに組み込まれています。

https://graph.microsoft.com/.defaultscope 値は、機能的に v1.0 エンドポイントの resource=https://graph.microsoft.com と同じです。 アプリケーションは、その要求に https://graph.microsoft.com/.default スコープを指定することで、アプリ登録ポータルでアプリに対して選択されたすべての Microsoft Graph アクセス許可のスコープを含むアクセス トークンを要求します。 スコープは、リソース URI と /.default を使用して作成されます。 そのため、リソース URI が https://contosoApp.com である場合、要求されるスコープは https://contosoApp.com/.default になります。 トークンを正しく要求するために 2 つ目のスラッシュを含める必要がある場合は、末尾のスラッシュに関するセクションを参照してください。

/.default スコープは、任意の OAuth 2.0 フローで使用できます。 ただし、On-Behalf-Of フロークライアント資格情報フローでは必須です。 また、v2 管理者の同意エンドポイントを使用してアプリケーションのアクセス許可を要求する場合にも必要です。

クライアントは、静的 (/.default) な同意と動的な同意を 1 つの要求に結合することはできません。 そのため、scope=https://graph.microsoft.com/.default+mail.read を指定すると、スコープの種類が結合されるため、エラーになります。

/.default スコープは、prompt=consent に対しても v1.0 エンドポイントの動作をトリガーします。 リソースに関係なく、アプリケーションによって登録されたすべてのアクセス許可に対して同意が要求されます。 要求の一部として含まれている場合、/.default スコープは、要求されたリソースのスコープを含むトークンを返します。

/.default スコープは機能的に、resource 中心の v1.0 エンドポイントの動作と同じです。 また、v1.0 エンドポイントの同意動作も備えています。 つまり、/.default では、ユーザーがクライアントとリソース間のアクセス許可を付与していない場合にのみ、同意プロンプトがトリガーされます。

このような同意が存在する場合、返されるトークンには、そのリソースに関してユーザーが付与したすべてのスコープが含まれます。 ただし、アクセス許可が付与されていない場合や prompt=consent パラメーターが指定されている場合は、クライアント アプリケーションによって登録されたすべてのスコープに対して同意プロンプトが表示されます。

例 1:ユーザーまたはテナント管理者がアクセス許可を付与している

この例では、ユーザーまたはテナント管理者が mail.readuser.read の Microsoft Graph アクセス許可をクライアントに付与しています。

クライアントが scope=https://graph.microsoft.com/.default を要求すると、Microsoft Graph に対するクライアント アプリケーションの登録済みアクセス許可の内容に関係なく、同意プロンプトは表示されません。 返されるトークンにはスコープ mail.readuser.read が含まれます。

例 2:ユーザーがクライアントとリソース間のアクセス許可を付与していない

この例では、ユーザーがクライアントと Microsoft Graph 間の同意を付与していません。 クライアントは、アクセス許可 user.readcontacts.read に登録されています。 また、Azure Key Vault スコープ https://vault.azure.net/user_impersonation にも登録されています。

クライアントが scope=https://graph.microsoft.com/.default のトークンを要求すると、user.read スコープ、contacts.read スコープ、Key Vault user_impersonation スコープの同意ページがユーザーに表示されます。 返されるトークンには user.readcontacts.read のスコープだけが含まれます。 これは、Microsoft Graph に対してのみ使用できます。

例 3: ユーザーは同意済みで、クライアントが追加のスコープを要求する

この例では、ユーザーは、クライアントの mail.read に既に同意しています。 クライアントは、contacts.read スコープに登録されています。

クライアントが scope=https://graph.microsoft.com/.default を使用してトークンを要求し、prompt=consent を介して同意を要求すると、アプリケーションによって登録されたすべて (かつ唯一) のアクセス許可の同意ページがユーザーに表示されます。 contacts.read スコープは同意ページにありますが、mail.read はありません。 返されるトークンは Microsoft Graph に対するものです。 これには mail.readcontacts.read が含まれます。

クライアントで /.default スコープを使用する

場合によっては、クライアントが独自の /.default スコープを要求できることがあります。 このシナリオを以下の例で説明します。

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
response_type=token            //Code or a hybrid flow is also possible here
&client_id=9ada6f8a-6d83-41bc-b169-a306c21527a5
&scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
&redirect_uri=https%3A%2F%2Flocalhost
&state=1234

同意と /.default の前述の説明がこのシナリオに適用される場合、このコード例では登録済みのすべてのアクセス許可の同意ページが生成されます。 この場合、コードによってアクセス トークンではなく id_token が返されます。

この動作は、Azure AD Authentication Library (ADAL) から Microsoft Authentication Library (MSAL) に移行している一部のレガシ クライアントに対応しています。 この設定は、Microsoft ID プラットフォームを対象とする新しいクライアントでは使用 "できません"。

クライアント資格情報付与フローと /.default

/.default のもう 1 つの用途は、Web API を呼び出すための クライアント資格情報付与フローを使用するデーモン アプリのような非対話型アプリケーションで、アプリケーションのアクセス許可 (または "ロール") を要求することです。

Web API についてのアプリケーションのアクセス許可 (ロール) を作成するには、アプリケーションへのアプリ ロールの追加に関する記事を参照してください。

クライアント アプリ内のクライアント資格情報要求には scope={resource}/.default を含める "必要があります"。 ここでは {resource} が、アプリが呼び出そうとしている Web API です。 個々のアプリケーションのアクセス許可 (ロール) を使用したクライアント資格情報要求の発行は、サポートされて "いません"。 返されるアクセス トークンには、その Web API に付与されているすべてのアプリケーションのアクセス許可 (ロール) が含まれます。

アプリケーション向けの管理者の同意の付与など、定義するアプリケーションのアクセス許可にアクセス権を付与するには、「Web API にアクセスするようにクライアント アプリケーションを構成する」を参照してください。

末尾のスラッシュと /.default

一部のリソース URI には末尾にスラッシュが付いています。たとえば、https://contoso.com ではなく https://contoso.com/ のようになります。 末尾にスラッシュがあると、トークンの検証で問題が発生する場合があります。 主に、Azure Resource Manager (https://management.azure.com/) のトークンが要求されたときに問題が発生します。 この場合、リソース URI の末尾のスラッシュは、トークンの要求時にスラッシュが必要であることを意味します。 そのため、https://management.azure.com/ のトークンを要求し、/.default を使用する場合は、https://management.azure.com//.default を要求する必要があります (二重スラッシュに注意してください)。 一般的に、トークンが発行されていることを検証していて、それを受け入れるべき API がトークンを拒否している場合は、2 番目のスラッシュを追加して再試行することを検討してください。

トラブルシューティング手順については、「アプリケーションに同意すると、予期しないエラーが発生する」を参照してください。

次の手順