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

  • [アーティクル]

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

この記事では、ID プラットフォームのスコープとアクセス許可について説明します。

次のリストに、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 Graph と見なされます。 たとえば、scope=User.Read は、https://graph.microsoft.com/User.Read と同じです。

管理者によって制限されるアクセス許可

Microsoft ID プラットフォームのアクセス許可は、管理者限定に設定できます。 たとえば、多くのより高い特権の Microsoft Graph のアクセス許可には、管理者の承認が必要です。 アプリが管理者によって制限されたアクセス許可を必要とする場合、組織の管理者は、組織のユーザーの代わりにこれらのスコープに同意する必要があります。 次のセクションでは、これらのアクセス許可の種類の例を示します。

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

Note

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

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

アプリケーションがアプリケーションのアクセス許可を要求していて、管理者がこれらのアクセス許可を付与する場合、この許可は特定のユーザーに代わっては行われません。 代わりに、クライアント アプリケーションはアクセス許可を "直接" 付与されます。 これらの種類のアクセス許可は、バックグラウンドで実行されるデーモン サービスと他の非対話型アプリケーションでのみ使用する必要があります。 直接アクセス シナリオの詳細については、Microsoft ID プラットフォームのアクセス シナリオに関するページを参照してください。

Web API でスコープを公開する方法のステップ バイ ステップ ガイドについては、「Web API を公開するようにアプリケーションを構成する」を参照してください。

OpenID Connect のスコープ

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

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

openid スコープ

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

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

email スコープ

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

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

profile スコープ

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 エンドポイントにリダイレクトし、新しい承認コードを要求する必要があります。 このリダイレクト中に、アプリの種類によっては、ユーザーが資格情報を再入力したり、アクセス許可に再同意したりする必要がある場合もあります。

更新トークンの有効期限はアクセス トークンよりも長く、通常は 1 日有効です。 更新トークンの取得方法と使用方法の詳細については、Microsoft ID プラットフォーム プロトコルのリファレンスを参照してください。

.default スコープ

.default スコープは、特定のアクセス許可を特定せずに、要求内のリソース サービス (API) を汎用的に参照するために使用されます。 同意が必要な場合、.default を使用すると、アプリケーションの登録に示されているすべての必要なアクセス許可 (一覧内のすべての API) について、同意を求めるメッセージが表示されます。

スコープ パラメーターの値は、リソースの識別子 URI と、スラッシュ (/) で区切られた .default を使用して構築されます。 たとえば、リソースの識別子 URI が https://contoso.com の場合、要求するスコープは https://contoso.com/.default です。 トークンを正しく要求するために 2 つ目のスラッシュを含める必要がある場合は、末尾のスラッシュに関するセクションを参照してください。

scope={resource-identifier}/.default を使用することは、機能的には v1.0 エンドポイントの resource={resource-identifier} と同じです (ここで、{resource-identifier} は API の識別子 URI であり、たとえば Microsoft Graph の場合は https://graph.microsoft.com)。

.default スコープは、任意の OAuth 2.0 フローで、admin consent を開始するために使用できます。 これはOn-Behalf-Of フローとクライアント資格情報フローで使用する必要があります。

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

.default スコープ パラメーターは、サインインしたユーザーに代わって、クライアントとリソースの間で委任されたアクセス許可に同意が付与されていない場合にのみ、同意プロンプトをトリガーします。

同意が存在する場合、返されるトークンには、サインインしたユーザーのそのリソースに付与されているすべてのスコープが含まれます。 ただし、要求されたリソースにアクセス許可が付与されていない場合 (または、prompt=consent パラメーターが指定されている場合) は、一覧のすべての API について、クライアント アプリケーションの登録で構成されている必要なすべてのアクセス許可に同意プロンプトが表示されます。

たとえば、スコープ https://graph.microsoft.com/.default が要求された場合、アプリケーションは Microsoft Graph API のアクセス トークンを要求しています。 サインインしているユーザーに代わって Microsoft Graph に少なくとも 1 つの委任されたアクセス許可が付与されている場合、サインインは続行され、そのユーザーに付与されているすべての Microsoft Graph の委任されたアクセス許可がアクセス トークンに含まれます。 要求されたリソース (この例では Microsoft Graph) にアクセス許可が付与されていない場合は、一覧のすべての API について、アプリケーションで構成されている必要なすべてのアクセス許可の同意プロンプトが表示されます。

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

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

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

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

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

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

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

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

クライアントは、まず、scope=https://graph.microsoft.com/.default を使用してサインインを実行します。 応答の scopes パラメーターに基づいて、アプリケーションのコードで Mail.Read のみが付与されていることが検出されます。 クライアントは scope=https://graph.microsoft.com/.default を使用して 2 回目のサインインを開始し、今度は prompt=consent を使用して強制的に同意します。 アプリケーションが登録したすべてのアクセス許可に対してユーザーの同意が許可されている場合は、同意プロンプトが表示されます。 (そうでない場合は、エラー メッセージまたは管理者の同意要求フォームが表示されます)。Contacts.Read と Mail.Read の両方が同意プロンプトに表示されます。 同意が付与され、サインインが続行される場合、返されるトークンは Microsoft Graph 用であり、Mail.Read と Contacts.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=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

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

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

クライアント資格情報の付与フローと .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 番目のスラッシュを追加して再試行することを検討してください。

関連項目