Microsoft ID プラットフォーム エンドポイントでのアクセス許可と同意Permissions and consent in the Microsoft identity platform endpoint

Microsoft ID プラットフォームと統合するアプリケーションは、データにアクセスする方法をユーザーと管理者が制御できるようにする承認モデルに従います。Applications that integrate with Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. この承認モデルの実装が Microsoft ID プラットフォーム エンドポイントで更新されて、アプリが Microsoft ID プラットフォームとやり取りする方法が変わりました。The implementation of the authorization model has been updated on the Microsoft identity platform endpoint, and it changes how an app must interact with the Microsoft identity platform. この記事では、スコープ、アクセス許可、同意など、この承認モデルの基本的な概念について説明します。This article covers the basic concepts of this authorization model, including scopes, permissions, and consent.

スコープとアクセス許可Scopes and permissions

Microsoft ID プラットフォームでは、OAuth 2.0 承認プロトコルが実装されています。The Microsoft identity platform implements the OAuth 2.0 authorization protocol. OAuth 2.0 は、ユーザーに代わってサードパーティのアプリが Web でホストされるリソースにアクセスできる方法です。OAuth 2.0 is a method through which a third-party app can access web-hosted resources on behalf of a user. Microsoft ID プラットフォームと統合される、Web でホストされるすべてのリソースは、リソース識別子つまり "アプリケーション ID URI" を持っています。Any web-hosted resource that integrates with the Microsoft identity platform has a resource identifier, or Application ID URI. Microsoft の Web でホストされるリソースには、次のようなものがあります。For example, some of Microsoft's web-hosted resources include:

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

注意

Office 365 メール API などではなく、Microsoft Graph を使用することを強くお勧めします。We strongly recommend that you use Microsoft Graph instead of Office 365 Mail API, etc.

Microsoft ID プラットフォームと統合されたサードパーティのリソースも同様です。The same is true for any third-party resources that have integrated with the Microsoft identity platform. これらのリソースのいずれでも、機能をより小さいまとまりに分割するために使用できるアクセス許可のセットを定義できます。Any of these resources also can define a set of permissions that can be used to divide the functionality of that resource into smaller chunks. たとえば、Microsoft Graph では、特に次のタスクを実行するアクセス許可が定義されています。As an example, Microsoft Graph has defined permissions to do the following tasks, among others:

  • ユーザーの予定表の読み取りRead a user's calendar
  • ユーザーの予定表への書き込みWrite to a user's calendar
  • ユーザーとしてのメールの送信Send mail as a user

これらの種類のアクセス許可を定義することで、リソースでは、データと、API 機能を公開する方法を、きめ細かく制御できます。By defining these types of permissions, the resource has fine-grained control over its data and how API functionality is exposed. サード パーティのアプリでは、ユーザーや管理者にこれらのアクセス許可を要求でき、ユーザーや管理者が承認してからでなければ、アプリはデータにアクセスしたり、ユーザーの代理として動作したりできません。A third-party app can request these permissions from users and administrators, who must approve the request before the app can access data or act on a user's behalf. リソースの機能を細かいアクセス許可セットにまとめることによって、サードパーティのアプリは、機能を実行するために必要な特定のアクセス許可のみを要求するように構築できます。By chunking the resource's functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. ユーザーや管理者は、アプリがアクセスできるデータを正確に知ることができ、アプリが悪意のある動作をしていないことを確信できます。Users and administrators can know exactly what data the app has access to, and they can be more confident that it isn't behaving with malicious intent. 開発者は常に最小限の特権の概念に従って、アプリケーションが機能するために必要なアクセス許可のみを要求する必要があります。Developers should always abide by the concept of least privilege, asking for only the permissions they need for their applications to function.

OAuth 2.0 では、これらの種類のアクセス許可は "スコープ" と呼ばれます。In OAuth 2.0, these types of permissions are called scopes. "アクセス許可" と呼ばれることもよくあります。They are also often referred to as permissions. アクセス許可は、Microsoft ID プラットフォームでは文字列値として表現されます。A permission is represented in the Microsoft identity platform as a string value. Microsoft Graph の例では、各アクセス許可の文字列値は次のようになります。Continuing with the Microsoft Graph example, the string value for each permission is:

  • Calendars.Read を使用したユーザーの予定表の読み取りRead a user's calendar by using Calendars.Read
  • Calendars.ReadWrite を使用したユーザーの予定表への書き込みWrite to a user's calendar by using Calendars.ReadWrite
  • Mail.Send を使用したユーザーとしてのメールの送信Send mail as a user using by Mail.Send

アプリでは、通常、Microsoft ID プラットフォーム承認エンドポイントへの要求でスコープを指定することにより、これらのアクセス許可を要求します。An app most commonly requests these permissions by specifying the scopes in requests to the Microsoft identity platform authorize endpoint. ただし、特定の高い特権アクセス許可は、管理者が同意することによってのみ付与することができ、管理者同意エンドポイントを使用して要求/付与できます。However, certain high privilege permissions can only be granted through administrator consent and requested/granted using the administrator consent endpoint. 詳細については、後の説明を参照してください。Read on to learn more.

アクセス許可の種類Permission types

Microsoft ID プラットフォームでは、委任されたアクセス許可アプリケーションのアクセス許可という 2 種類のアクセス許可がサポートされています。Microsoft identity platform supports two types of permissions: delegated permissions and application permissions.

  • 委任されたアクセス許可は、サインインしているユーザーが存在するアプリで使用されます。Delegated permissions are used by apps that have a signed-in user present. これらのアプリでは、ユーザーまたは管理者がアプリから要求されたアクセス許可に同意すると、ターゲット リソースの呼び出し時にサインイン ユーザーとして動作するためのアクセス許可がアプリに委任されます。For these apps, either the user or an administrator consents to the permissions that the app requests, and the app is delegated permission to act as the signed-in user when making calls to the target resource. 一部の委任されたアクセス許可には管理者以外のユーザーでも同意できますが、一部の高い特権のアクセス許可では管理者の同意が必要です。Some delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent. 委任されたアクセス許可に同意できる管理者ロールについては、「Azure AD での管理者ロールのアクセス許可」を参照してください。To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

  • アプリケーションのアクセス許可は、サインインしているユーザーが存在しない状態で実行されるアプリ (バックグラウンド サービスまたはデーモンとして実行されるアプリなど) で使用されます。Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. アプリケーションのアクセス許可には、管理者だけが同意できます。Application permissions can only be consented by an administrator.

"有効なアクセス許可" は、アプリがターゲット リソースに要求を行うときに付与されるアクセス許可です。Effective permissions are the permissions that your app will have when making requests to the target resource. アプリに付与される委任されたアクセス許可とアプリケーションのアクセス許可の違い、およびターゲット リソースへの呼び出しを行うときの有効なアクセス許可について理解しておくことが重要です。It's important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to the target resource.

  • 委任されたアクセス許可の場合、アプリの有効な "アクセス許可" は、(同意によって) アプリに付与されている委任されたアクセス許可と現在サインインしているユーザーの特権の共通部分の最小特権になります。For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. サインインしているユーザーよりも多くの特権をアプリに付与することはできません。Your app can never have more privileges than the signed-in user. 組織内では、サインインしているユーザーの特権は、ポリシーによって決定することも、1 つ以上の管理者ロールのメンバーシップによって決定することもできます。Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. 委任されたアクセス許可に同意できる管理者ロールについては、「Azure AD での管理者ロールのアクセス許可」を参照してください。To learn which administrator roles can consent to delegated permissions, see Administrator role permissions in Azure AD.

    たとえば、委任されたアクセス許可として User.ReadWrite.All がアプリに付与されているものとします。For example, assume your app has been granted the User.ReadWrite.All delegated permission. 通常、このアクセス許可は、組織内のすべてのユーザーのプロファイルを読み取り、更新する権限をアプリに付与します。This permission nominally grants your app permission to read and update the profile of every user in an organization. サインインしているユーザーが全体管理者の場合、アプリは組織内のすべてのユーザーのプロファイルを更新できます。If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. ただし、サインインしているユーザーが管理者ロールに属していない場合、アプリが更新できるのは、サインインしているユーザーのプロファイルだけになります。However, if the signed-in user isn't in an administrator role, your app will be able to update only the profile of the signed-in user. アプリにはユーザーの代理で動作するためのアクセス許可が付与されていますが、そのユーザーに組織内の他のユーザーのプロファイルを更新する権限がないため、アプリがこれを実行することはできません。It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.

  • アプリケーションのアクセス許可の場合、アプリの "有効なアクセス許可" は、そのアクセス許可が暗示する完全なレベルの権限になります。For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. たとえば、アプリケーションのアクセス許可として User.ReadWrite.All が付与されているアプリは、組織内のすべてのユーザーのプロファイルを更新できます。For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

OpenID Connect のスコープOpenID Connect scopes

OpenID Connect の Microsoft ID プラットフォーム実装には、Microsoft Graph にもホストされている適切に定義されたスコープ openidemailprofileoffline_access があります。The Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that are also hosted on the Microsoft Graph: openid, email, profile, and offline_access. addressphone の OpenID Connect スコープはサポートされていません。The address and phone OpenID Connect scopes are not supported.

OIDC スコープとトークンを要求すると、UserInfo エンドポイントを呼び出すためのトークンが付与されます。Requesting the OIDC scopes and a token will give you a token to call the UserInfo endpoint.

openidopenid

アプリは、OpenID Connect を使用してサインインを行う場合、openid スコープを要求する必要があります。If an app performs sign-in by using OpenID Connect, it must request the openid scope. openid スコープは、職場アカウントの同意ページでは "サインイン" アクセス許可として表示され、個人用 Microsoft アカウントの同意ページでは "プロフィールの表示と、Microsoft アカウントを使うアプリとサービスへの接続" アクセス許可として表示されます。The openid scope shows on the work account consent page as the "Sign you in" permission, and on the personal Microsoft account consent page as the "View your profile and connect to apps and services using your Microsoft account" permission. このアクセス許可により、sub 要求の形式でユーザーの一意の識別子をアプリが受け取ることができます。With this permission, an app can receive a unique identifier for the user in the form of the sub claim. アプリが UserInfo エンドポイントにアクセスすることも可能にします。It also gives the app access to the UserInfo endpoint. openid スコープは、Microsoft ID プラットフォーム トークン エンドポイントで ID トークンを取得するために使用できます。このトークンは、アプリが認証目的で使用できます。The openid scope can be used at the Microsoft identity platform token endpoint to acquire ID tokens, which can be used by the app for authentication.

emailemail

email スコープは openid スコープやその他のスコープと共に使用できます。The email scope can be used with the openid scope and any others. これにより、アプリがユーザーのプライマリ電子メール アドレスに email 要求の形式でアクセスできます。It gives the app access to the user's primary email address in the form of the email claim. 電子メール アドレスがユーザー アカウントと関連付けられている場合のみ (常にではありません)、email 要求はトークンに含まれます。The email claim is included in a token only if an email address is associated with the user account, which isn't always the case. email スコープを使用する場合は、トークンに email 要求が存在しないケースにも対応できるようにアプリを準備する必要があります。If it uses the email scope, your app should be prepared to handle a case in which the email claim does not exist in the token.

profileprofile

profile スコープは openid スコープやその他のスコープと共に使用できます。The profile scope can be used with the openid scope and any others. これにより、アプリはユーザーの多くの情報にアクセスできます。It gives the app access to a substantial amount of information about the user. アプリがアクセスできる情報には、ユーザーの名、姓、希望するユーザー名、オブジェクト ID などがありますが、これらに限定されるものではありません。The information it can access includes, but isn't limited to, the user's given name, surname, preferred username, and object ID. 特定のユーザーに対して id_tokens パラメーターで使用できるプロファイル要求の完全な一覧については、id_tokens のリファレンスをご覧ください。For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the id_tokens reference.

offline_accessoffline_access

offline_accessスコープを使用すると、アプリはユーザーの代わりに、長期間にわたってリソースにアクセスできます。The offline_access scope gives your app access to resources on behalf of the user for an extended time. 同意ページで、このスコープは、"アクセス権を与えたデータへのアクセスを管理する" アクセス許可として表示されます。On the consent page, this scope appears as the "Maintain access to data you have given it access to" permission. ユーザーが offline_access スコープを承認すると、アプリは Microsoft ID プラットフォーム トークン エンドポイントから更新トークンを取得できます。When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. 更新トークンの有効期間は長期です。Refresh tokens are long-lived. アプリは、古いアクセス トークンの有効期限が切れると、新しいアクセス トークンを取得できます。Your app can get new access tokens as older ones expire.

注意

このアクセス許可は、更新トークンを提供しないフロー (暗黙的フロー) も含め、現在のすべての同意画面に表示されます。This permission appears on all consent screens today, even for flows that don't provide a refresh token (the implicit flow). これは、クライアントが暗黙的フロー内で開始した後、更新トークンが予測されるコード フローに移行することが可能なシナリオも対象にするためです。This is to cover scenarios where a client can begin within the implicit flow, and then move onto to the code flow where a refresh token is expected.

Microsoft ID プラットフォーム (要求は v2.0 エンドポイントに対して行われます) では、更新トークンを受信するには、アプリが offline_access スコープを明示的に要求する必要があります。On the Microsoft identity platform (requests made to the v2.0 endpoint), your app must explicitly request the offline_access scope, to receive refresh tokens. つまり、OAuth 2.0 承認コード フローの承認コードを使用すると、/token エンドポイントからアクセス トークンだけが取得されます。This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll receive only an access token from the /token endpoint. アクセス トークンの有効期間は短期です。The access token is valid for a short time. アクセス トークンは、通常、1 時間以内に期限切れとなります。The access token usually expires in one hour. その時点で、アプリはユーザーを /authorize エンドポイントにリダイレクトして、新しい承認コードを取得する必要があります。At that point, your app needs to redirect the user back to the /authorize endpoint to get a new authorization code. このリダイレクト中に、アプリの種類によっては、ユーザーが資格情報を再入力したり、アクセス許可に再同意したりする必要がある場合もあります。During this redirect, depending on the type of app, the user might need to enter their credentials again or consent again to permissions.

更新トークンの取得方法と使用方法の詳細については、Microsoft ID プラットフォーム プロトコルのリファレンスを参照してください。For more information about how to get and use refresh tokens, see the Microsoft identity platform protocol reference.

OpenID Connect または OAuth 2.0 承認要求では、アプリは scope クエリ パラメーターを使用して、必要なアクセス許可を要求できます。In an OpenID Connect or OAuth 2.0 authorization request, an app can request the permissions it needs by using the scope query parameter. たとえば、ユーザーがアプリにサインインするときに、アプリは次のような要求を送信します (読みやすくするために、改行を追加しています)。For example, when a user signs in to an app, the app sends a request like the following example (with line breaks added for legibility):

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 パラメーターは、アプリが要求している委任されたアクセス許可の、空白文字で区切られた一覧です。The scope parameter is a space-separated list of delegated permissions that the app is requesting. 各アクセス許可は、リソースの識別子 (アプリケーション ID URI) にアクセス許可の値を追加することによって示されます。Each permission is indicated by appending the permission value to the resource's identifier (the Application ID URI). 上の要求では、ユーザーの予定表を読み取り、ユーザーとしてメールを送信するためのアクセス許可をアプリが必要としています。In the request example, the app needs permission to read the user's calendar and send mail as the user.

ユーザーが資格情報を入力すると、Microsoft ID プラットフォーム エンドポイントは、ユーザーの同意の一致するレコードがないか確認します。After the user enters their credentials, the Microsoft identity platform endpoint checks for a matching record of user consent. ユーザーが過去に要求されたどのアクセス許可にも同意しておらず、管理者も組織全体の代わりにそれらのアクセス許可に同意していない場合、Microsoft ID プラットフォーム エンドポイントは要求されたアクセス許可の付与をユーザーに求めます。If the user has not consented to any of the requested permissions in the past, nor has an administrator consented to these permissions on behalf of the entire organization, the Microsoft identity platform endpoint asks the user to grant the requested permissions.

注意

この時点で、offline_access ("アクセス権を与えたデータへのアクセスを管理する") と user.read ("サインインとプロファイルの読み取り") のアクセス許可が、アプリケーションへの初期同意に自動的に組み込まれます。At this time, the offline_access ("Maintain access to data you have given it access to") and user.read ("Sign you in and read your profile") permissions are automatically included in the initial consent to an application. 一般に、これらのアクセス許可は、適切なアプリの機能に必要です。offline_access は、ネイティブおよび Web のアプリに不可欠の更新トークンへのアクセスをアプリに提供し、user.read は、クライアントまたはアプリが長期間にわたってユーザーを適切に識別し、基本的なユーザー情報にアクセスできるようにする sub 要求へのアクセスを提供します。These permissions are generally required for proper app functionality - offline_access gives the app access to refresh tokens, critical for native and web apps, while user.read gives access to the sub claim, allowing the client or app to correctly identify the user over time and access rudimentary user information.

作業アカウントの同意を示すスクリーンショットの例

ユーザーがアクセス許可の要求を承認すると、同意が記録されるので、ユーザーはそれ以降にアカウントにサインインするときに再度同意する必要はありません。When the user approves the permission request, consent is recorded and the user doesn't have to consent again on subsequent sign-ins to the application.

多くの場合、組織がアプリケーションのライセンスまたはサブスクリプションを購入している場合は、組織のすべてのメンバーが使用できるようにアプリケーションを事前にセットアップすることが望まれます。Often, when an organization purchases a license or subscription for an application, the organization wants to proactively set up the application for use by all members of the organization. このプロセスの一環として、管理者は、テナントのユーザーの代理としてアプリケーションへの同意を与えることができます。As part of this process, an administrator can grant consent for the application to act on behalf of any user in the tenant. 管理者がテナント全体に対する同意を与えると、組織のユーザーにはアプリケーションの同意ページは表示されません。If the admin grants consent for the entire tenant, the organization's users won't see a consent page for the application.

テナントのユーザー全員に対して委任されたアクセス許可の同意を要求するには、アプリで管理者の同意エンドポイントを使用できます。To request consent for delegated permissions for all users in a tenant, your app can use the admin consent endpoint.

さらに、アプリケーションでは、管理者の同意エンドポイントを使用してアプリケーションのアクセス許可を要求する必要があります。Additionally, applications must use the admin consent endpoint to request Application Permissions.

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

Microsoft のエコシステムにおける高い権限には、管理者によって制限されているとマークされているものもあります。Some high-privilege permissions in the Microsoft ecosystem can be set to admin-restricted. これらの種類のアクセス許可の例として、次のアクセス許可があります。Examples of these kinds of permissions include the following:

  • User.Read.All を使用してすべてのユーザーの完全なプロファイルを読み取るRead all user's full profiles by using User.Read.All
  • Directory.ReadWrite.All を使用した組織のディレクトリへのデータの書き込みWrite data to an organization's directory by using Directory.ReadWrite.All
  • Groups.Read.All を使用して組織のディレクトリ内の全グループを読み取るRead all groups in an organization's directory by using Groups.Read.All

コンシューマー ユーザーがこの種類のデータへのアプリケーション アクセスを許可している場合でも、組織のユーザーは会社の同一の機密データ セットへのアクセスを許可することが制限されます。Although a consumer user might grant an application access to this kind of data, organizational users are restricted from granting access to the same set of sensitive company data. アプリケーションが組織のユーザーにこれらのアクセス許可のいずれかへのアクセスを要求すると、ユーザーは、アプリのアクセス許可に同意する権限がないという内容のエラー メッセージを受け取ります。If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they're not authorized to consent to your app's permissions.

アプリが組織の管理者に制限されるスコープにアクセスする必要がある場合は、次のように管理者の同意エンドポイントを使用して、会社の管理者から直接要求する必要があります。If your app requires access to admin-restricted scopes for organizations, you should request them directly from a company administrator, also by using the admin consent endpoint, described next.

アプリケーションが高い特権の委任されたアクセス許可を要求していて、管理者の同意エンドポイントを介して管理者がこれらのアクセス許可を付与すると、テナントのユーザー全員に対して同意が付与されます。If the application is requesting high privilege delegated permissions and an administrator grants these permissions via the admin consent endpoint, consent is granted for all users in the tenant.

アプリケーションがアプリケーションのアクセス許可を要求していて、管理者が管理者の同意エンドポイントを介してこれらのアクセス許可を付与する場合、この許可は特定のユーザーに代わっては行われません。If the application is requesting application permissions and an administrator grants these permissions via the admin consent endpoint, this grant isn't done on behalf of any specific user. 代わりに、クライアント アプリケーションはアクセス許可を "直接" 付与されます。Instead, the client application is granted permissions directly. これらの種類のアクセス許可は、バックグラウンドで実行されるデーモン サービスと他の非対話型アプリケーションでのみ使用されます。These types of permissions are only used by daemon services and other non-interactive applications that run in the background.

注意

管理者の同意エンドポイントを使って管理者の同意を付与した後は、管理者の同意の付与は終わっており、ユーザーはそれ以上のアクションを実行する必要がないことに注意してください。Please note after granting admin consent using the admin consent endpoint, you have finished granting admin consent and users do not need to perform any further additional actions. 管理者の同意を付与した後、ユーザーは一般的な認証フローを使ってアクセス トークンを取得でき、結果のアクセス トークンには同意されたアクセス許可が付与されます。After granting admin consent, users can get an access token via a typical auth flow and the resulting access token will have the consented permissions.

会社の管理者がアプリケーションを使用していて、承認エンドポイントに送られた場合、Microsoft ID プラットフォームは、ユーザーのロールを検出し、アプリケーションで要求されたアクセス許可に対してテナント全体の代わりに同意するかどうかを管理者に確認します。When a Company Administrator uses your application and is directed to the authorize endpoint, Microsoft identity platform will detect the user's role and ask them if they would like to consent on behalf of the entire tenant for the permissions you have requested. ただし、テナント全体に代わって管理者がアクセス許可を付与することを事前に要求する必要がある場合に使用できる、専用の管理者の同意エンドポイントもあります。However, there is also a dedicated admin consent endpoint you can use if you would like to proactively request that an administrator grants permission on behalf of the entire tenant. アプリケーションのアクセス許可を要求する場合も、このエンドポイントを使用する必要があります (これは、承認エンドポイントでは要求できません)。Using this endpoint is also necessary for requesting Application Permissions (which can't be requested using the authorize endpoint).

これから説明する手順に従うと、管理者に制限されているスコープを含むテナントのユーザー全員のアクセス許可をアプリで要求できます。If you follow these steps, your app can request permissions for all users in a tenant, including admin-restricted scopes. これは、高い特権の操作であり、シナリオに必要な場合にのみ行う必要があります。This is a high privilege operation and should only be done if necessary for your scenario.

手順を実装するコード サンプルについては、管理者に制限されているスコープのサンプルに関するページを参照してください。To see a code sample that implements the steps, see the admin-restricted scopes sample.

アプリケーション登録ポータルでアクセス許可を要求するRequest the permissions in the app registration portal

アプリケーションは、アプリ登録ポータルで必要なアクセス許可 (委任されたアクセス許可とアプリケーションのアクセス許可の両方) を確認できます。Applications are able to note which permissions they require (both delegated and application) in the app registration portal. これにより、/.default スコープと Azure portal の "管理者の同意を与える" オプションを使用できるようになります。This allows use of the /.default scope and the Azure portal's "Grant admin consent" option. 一般に、特定のアプリケーションに対して静的に定義するアクセス許可を、動的/増分的に将来要求するアクセス許可のスーパーセットにすることが、最善の方法です。In general, it's best practice to ensure that the permissions statically defined for a given application are a superset of the permissions that it will be requesting dynamically/incrementally.

注意

アプリケーションのアクセス許可は、/.default を使用することによってのみ要求できます。アプリでアプリケーションのアクセス許可が必要な場合は、アプリの登録ポータルに一覧表示されていることを確認してください。Application permissions can only be requested through the use of /.default - so if your app needs application permissions, make sure they're listed in the app registration portal.

アプリケーションに対して静的に要求されるアクセス許可のリストを構成するにはTo configure the list of statically requested permissions for an application

  1. Azure portal - アプリの登録エクスペリエンスでアプリケーションに移動するか、まだアプリを作成していない場合は作成します。Go to your application in the Azure portal – App registrations experience, or create an app if you haven't already.
  2. [API のアクセス許可] セクションを見つけ、API のアクセス許可内で [アクセス許可の追加] をクリックします。Locate the API Permissions section, and within the API permissions click Add a permission.
  3. 使用可能な API の一覧から [Microsoft Graph] を選択し、アプリに必要なアクセス許可を追加します。Select Microsoft Graph from the list of available APIs and then add the permissions that your app requires.
  4. アプリの登録を保存します。Save the app registration.

通常、管理者の同意エンドポイントを使用するアプリケーションを構築する場合は、アプリ側に管理者がアプリのアクセス許可を承認できるページやビューが必要です。Typically, when you build an application that uses the admin consent endpoint, the app needs a page or view in which the admin can approve the app's permissions. このページは、アプリのサインアップ フローやアプリの設定の一部にするか、専用の "接続" フローにすることができます。This page can be part of the app's sign-up flow, part of the app's settings, or it can be a dedicated "connect" flow. 多くの場合、職場または学校の Microsoft アカウントでユーザーがサインインした後にのみ、”接続" ビューが表示されます。In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work or school Microsoft account.

ユーザーをアプリにサインインさせるとき、必要なアクセス許可の承認をユーザーに依頼する前に、管理者が所属する組織を識別できます。When you sign the user into your app, you can identify the organization to which the admin belongs before asking them to approve the necessary permissions. 必須ではありませんが、組織のユーザーに向けたより直観的なエクスペリエンスの作成に役立ちます。Although not strictly necessary, it can help you create a more intuitive experience for your organizational users. ユーザーをサインインさせるには、Microsoft ID プラットフォーム プロトコルのチュートリアルに従ってください。To sign the user in, follow our Microsoft identity platform protocol tutorials.

ディレクトリ管理者にアクセス許可を要求するRequest the permissions from a directory admin

組織の管理者にアクセス許可を要求する準備ができたら、Microsoft ID プラットフォームの管理者の同意エンドポイントにユーザーをリダイレクトできます。When you're ready to request permissions from your organization's admin, you can redirect the user to the Microsoft identity platform admin consent endpoint.

// 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
パラメーターParameter 条件Condition 説明Description
tenant 必須Required アクセス許可を要求するディレクトリ テナント。The directory tenant that you want to request permission from. GUID またはフレンドリ名の形式で指定できます。または、例に示すように、組織によって総称的に参照できます。Can be provided in GUID or friendly name format OR generically referenced with organizations as seen in the example. 'Common' は使用しないでください。個人のアカウントは、テナントのコンテキスト以外で管理者の同意を提供することはできません。Do not use 'common', as personal accounts cannot provide admin consent except in the context of a tenant. テナントを管理する個人用アカウントとの最善の互換性を確保するには、可能であればテナント ID を使用します。To ensure best compatibility with personal accounts that manage tenants, use the tenant ID when possible.
client_id 必須Required Azure portal の [アプリの登録] エクスペリエンスでアプリに割り当てられたアプリケーション (クライアント) IDThe Application (client) ID that the Azure portal – App registrations experience assigned to your app.
redirect_uri 必須Required 処理するアプリの応答の送信先となるリダイレクト URI。The redirect URI where you want the response to be sent for your app to handle. アプリケーション登録ポータルで登録したリダイレクト URI のいずれかと完全に一致させる必要があります。It must exactly match one of the redirect URIs that you registered in the app registration portal.
state 推奨Recommended 要求に含まれ、かつトークンの応答として返される値。A value included in the request that will also be returned in the token response. 任意のコンテンツの文字列を指定することができます。It can be a string of any content you want. この状態は、認証要求の前にアプリ内でユーザーの状態 (表示中のページやビューなど) に関する情報をエンコードする目的に使用します。Use the state to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
scope 必須Required アプリケーションによって要求されるアクセス許可のセットを定義します。Defines the set of permissions being requested by the application. これは静的スコープ (/.default を使用) か動的スコープになります。This can be either static (using /.default) or dynamic scopes. これには OIDC スコープ (openidprofileemail) が含まれることもあります。This can include the OIDC scopes (openid, profile, email). アプリケーションのアクセス許可が必要な場合は、/.default を使用して、静的に構成されたアクセス許可の一覧を要求する必要があります。If you need application permissions, you must use /.default to request the statically configured list of permissions.

現在 Azure AD では、テナント管理者がサインインして、要求を完了する必要があります。At this point, Azure AD requires a tenant administrator to sign in to complete the request. 管理者は、ユーザーが scope パラメーターで要求したすべてのアクセス許可を承認するように求められます。The administrator is asked to approve all the permissions that you have requested in the scope parameter. 静的な (/.default) 値を使用した場合、それは v1.0 管理者の同意エンドポイントのように機能し、アプリに必要なアクセス許可で見つかったすべてのスコープに対する同意を要求します。If you've used a static (/.default) value, it will function like the v1.0 admin consent endpoint and request consent for all scopes found in the required permissions for the app.

成功応答Successful response

管理者がアプリにアクセス許可を承認すると、成功応答は次のようになります。If the admin approves the permissions for your app, the successful response looks like this:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
パラメーターParameter 説明Description
tenant アプリケーションが要求したアクセス許可を GUID 形式で付与するディレクトリ テナント。The directory tenant that granted your application the permissions it requested, in GUID format.
state 要求に含まれ、かつトークンの応答として返される値。A value included in the request that also will be returned in the token response. 任意のコンテンツの文字列を指定することができます。It can be a string of any content you want. この状態は、認証要求の前にアプリ内でユーザーの状態 (表示中のページやビューなど) に関する情報をエンコードする目的に使用されます。The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consent True に設定されます。Will be set to True.

エラー応答Error response

管理者がアプリにアクセス許可を承認しない場合、失敗した応答は次のようになります。If the admin does not approve the permissions for your app, the failed response looks like this:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
パラメーターParameter 説明Description
error 発生したエラーの種類を分類したりエラーに対処したりする際に使用するエラー コード文字列。An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description エラーの根本的な原因を開発者が特定しやすいように記述した具体的なエラー メッセージ。A specific error message that can help a developer identify the root cause of an error.

管理者の同意エンドポイントから成功応答を受信した後で、アプリは要求したアクセス許可を獲得しています。After you've received a successful response from the admin consent endpoint, your app has gained the permissions it requested. 次に、必要なリソースのトークンを要求できます。Next, you can request a token for the resource you want.

アクセス許可の使用Using permissions

ユーザーがアプリのアクセス許可に同意したら、アプリは一定範囲でリソースにアクセスするためのアプリのアクセス許可を表すアクセス トークンを取得できます。After the user consents to permissions for your app, your app can acquire access tokens that represent your app's permission to access a resource in some capacity. アクセス トークンは、1 つのリソースだけで使用できますが、アクセス トークンの内部には、そのリソースに関してアプリに付与されたすべてのアクセス許可がエンコードされます。An access token can be used only for a single resource, but encoded inside the access token is every permission that your app has been granted for that resource. アクセス トークンを取得するために、アプリは Microsoft ID プラットフォーム トークン エンドポイントに対して、次のような要求を行うことができます。To acquire an access token, your app can make a request to the Microsoft identity platform token endpoint, like this:

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 要求では、取得したアクセス トークンを使用できます。You can use the resulting access token in HTTP requests to the resource. アクセス トークンはリソースに対して、特定のタスクを実行する適切なアクセス許可がアプリにあることを確実に示すことができます。It reliably indicates to the resource that your app has the proper permission to perform a specific task.

OAuth 2.0 プロトコルとアクセス トークンの取得方法の詳細については、Microsoft ID プラットフォーム エンドポイント プロトコルのリファレンスを参照してください。For more information about the OAuth 2.0 protocol and how to get access tokens, see the Microsoft identity platform endpoint protocol reference.

/.default スコープThe /.default scope

/.default スコープを使用すると、v1.0 エンドポイントから Microsoft ID プラットフォーム エンドポイントにアプリを移行するのに役立ちます。You can use the /.default scope to help migrate your apps from the v1.0 endpoint to the Microsoft identity platform endpoint. これは、アプリケーション登録で構成されたアクセス許可の静的一覧を参照するすべてのアプリケーションの組み込みスコープです。This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. https://graph.microsoft.com/.defaultscope 値は、v1.0 エンドポイント resource=https://graph.microsoft.com と機能的に同じです。つまり、これは、アプリケーションが Azure portal で登録した Microsoft Graph のスコープでトークンを要求します。A scope value of https://graph.microsoft.com/.default is functionally the same as the v1.0 endpoints resource=https://graph.microsoft.com - namely, it requests a token with the scopes on Microsoft Graph that the application has registered for in the Azure portal. これは、リソース URI と /.default を使用して作成されます (たとえば、リソース URI が https://contosoApp.com の場合、要求されたスコープは https://contosoApp.com/.default になります)。It is constructed using the resource URI + /.default (e.g. if the resource URI is https://contosoApp.com, then the scope requested would be https://contosoApp.com/.default). トークンを正しく要求するために 2 つ目のスラッシュを含める必要がある場合は、末尾のスラッシュに関するセクションを参照してください。See the section on trailing slashes for cases where you must include a second slash to correctly request the token.

/.default スコープは、任意の OAuth 2.0 フローで使用できますが、On-Behalf-Of フロークライアント資格情報フロー、および v2 管理者の同意エンドポイントを使用してアプリケーションのアクセス許可を要求するときに必要になります。The /.default scope can be used in any OAuth 2.0 flow, but is necessary in the On-Behalf-Of flow and client credentials flow, as well as when using the v2 admin consent endpoint to request application permissions.

注意

クライアントは、静的 (/.default) と動的の同意を 1 つの要求に結合することはできません。Clients can't combine static (/.default) and dynamic consent in a single request. そうした場合、スコープの種類の結合が原因で scope=https://graph.microsoft.com/.default+mail.read はエラーになります。Thus, scope=https://graph.microsoft.com/.default+mail.read will result in an error due to the combination of scope types.

/.default スコープは、prompt=consent に対しても v1.0 エンドポイントの動作をトリガーします。The /.default scope triggers the v1.0 endpoint behavior for prompt=consent as well. リソースに関係なく、アプリケーションによって登録されたすべてのアクセス許可に対して同意が要求されます。It requests consent for all permissions registered by the application, regardless of the resource. 要求の一部として含まれている場合、/.default スコープは、要求されたリソースのスコープを含むトークンを返します。If included as part of the request, the /.default scope returns a token that contains the scopes for the resource requested.

/.default は、機能的には resource 中心の v1.0 エンドポイントの動作と同じであるため、v1.0 エンドポイントの同意の動作も行います。Because /.default is functionally identical to the resource-centric v1.0 endpoint's behavior, it brings with it the consent behavior of the v1.0 endpoint as well. つまり、/.default は、ユーザーによってクライアントとリソース間のアクセス許可が付与されていない場合にのみ、同意プロンプトをトリガーします。Namely, /.default only triggers a consent prompt if no permission has been granted between the client and the resource by the user. そのような同意が存在する場合は、ユーザーがそのリソースに対して付与したすべてのスコープを含むトークンが返されます。If any such consent exists, then a token will be returned containing all scopes granted by the user for that resource. ただし、アクセス許可が付与されていない場合や prompt=consent パラメーターが指定されている場合は、クライアント アプリケーションによって登録されたすべてのスコープに対して同意プロンプトが表示されます。However, if no permission has been granted, or the prompt=consent parameter has been provided, a consent prompt will be shown for all scopes registered by the client application.

例 1:ユーザーまたはテナント管理者がアクセス許可を付与しているExample 1: The user, or tenant admin, has granted permissions

この例では、ユーザー (またはテナント管理者) が Microsoft Graph のアクセス許可 mail.readuser.read をクライアントに付与しています。In this example, the user (or a tenant administrator) has granted the client the Microsoft Graph permissions mail.read and user.read. クライアントが scope=https://graph.microsoft.com/.default の要求を行うと、Microsoft Graph に対するクライアント アプリケーションの登録済みアクセス許可の内容に関係なく、同意プロンプトは表示されません。If the client makes a request for scope=https://graph.microsoft.com/.default, then no consent prompt will be shown regardless of the contents of the client applications registered permissions for Microsoft Graph. スコープ mail.readuser.read を含むトークンが返されます。A token would be returned containing the scopes mail.read and user.read.

例 2:ユーザーがクライアントとリソース間のアクセス許可を付与していないExample 2: The user hasn't granted permissions between the client and the resource

この例では、クライアントと Microsoft Graph 間のユーザーの同意は存在しません。In this example, no consent for the user exists between the client and Microsoft Graph. クライアントは user.readcontacts.read のアクセス許可、および Azure Key Vault スコープ https://vault.azure.net/user_impersonation を登録しています。The client has registered for the user.read and contacts.read permissions, as well as the Azure Key Vault scope https://vault.azure.net/user_impersonation. クライアントが scope=https://graph.microsoft.com/.default のトークンを要求すると、user.readcontacts.read、および Key Vault user_impersonation のスコープの同意画面がユーザーに表示されます。When the client requests a token for scope=https://graph.microsoft.com/.default, the user will see a consent screen for the user.read, contacts.read, and the Key Vault user_impersonation scopes. 返されるトークンには、user.readcontacts.read スコープだけが含まれ、Microsoft Graph に対してのみ使用できます。The token returned will have just the user.read and contacts.read scopes in it and only be usable against Microsoft Graph.

例 3: ユーザーは同意済みで、クライアントが追加のスコープを要求するExample 3: The user has consented and the client requests additional scopes

この例では、ユーザーは、クライアントの mail.read に既に同意しています。In this example, the user has already consented to mail.read for the client. クライアントは、登録で contacts.read スコープを登録しています。The client has registered for the contacts.read scope in its registration. クライアントが scope=https://graph.microsoft.com/.default を使用してトークンを要求し、prompt=consent を介して同意を要求すると、アプリケーションによって登録されたすべて (かつ唯一) のアクセス許可の同意画面がユーザーに表示されます。When the client makes a request for a token using scope=https://graph.microsoft.com/.default and requests consent through prompt=consent, then the user will see a consent screen for all (and only) the permissions registered by the application. contacts.read は同意画面に表示されますが、mail.read は表示されません。contacts.read will be present in the consent screen, but mail.read will not. 返されたトークンは Microsoft Graph 用であり、mail.readcontacts.read が含まれます。The token returned will be for Microsoft Graph and will contain mail.read and contacts.read.

クライアントで /.default スコープを使用するUsing the /.default scope with the client

クライアントがそれ自体の /.default スコープを要求するという /.default スコープの特殊なケースがあります。A special case of the /.default scope exists where a client requests its own /.default scope. このシナリオを以下の例で説明します。The following example demonstrates this scenario.

// 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 が返されます。This produces a consent screen for all registered permissions (if applicable based on the above descriptions of consent and /.default), then returns an id_token, rather than an access token. この動作は、ADAL から MSAL に移行する特定のレガシー クライアントのために存在するものであり、Microsoft ID プラットフォーム エンドポイントを対象とする新しいクライアントでは使用しないでくださいThis behavior exists for certain legacy clients moving from ADAL to MSAL, and should not be used by new clients targeting the Microsoft identity platform endpoint.

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

一部のリソース URI には、末尾のスラッシュ (https://contoso.com ではなく https://contoso.com/) があるため、トークンの検証で問題が発生する可能性があります。Some resource URIs have a trailing slash (https://contoso.com/ as opposed to https://contoso.com), which can cause problems with token validation. これは主に、リソース URI の末尾にスラッシュがあり、トークンが要求されたときに存在している必要がある Azure Resource Management (https://management.azure.com/) のトークンを要求するときに発生します。This can occur primarily when requesting a token for Azure Resource Management (https://management.azure.com/), which has a trailing slash on their resource URI and requires it to be present when the token is requested. したがって、https://management.azure.com/ のトークンを要求し、/.default を使用する場合は、https://management.azure.com//.default を要求する必要があります。二重スラッシュに注意してください。Thus, when requesting a token for https://management.azure.com/ and using /.default, you must request https://management.azure.com//.default - note the double slash!

一般的に、トークンが発行されていることを検証し、それを受け入れるべき API がトークンを拒否している場合は、2 番目のスラッシュを追加して再試行することを検討してください。In general - if you've validated that the token is being issued, and the token is being rejected by the API that should accept it, consider adding a second slash and trying again. これは、ログイン サーバーが、/.default が末尾から削除された scope パラメーターの URI に一致する対象ユーザーと共にトークンを出力したために発生します。This happens because the login server emits a token with the audience matching the URIs in the scope parameter - with /.default removed from the end. これにより末尾のスラッシュが削除されて一致しなくなった場合でも、ログイン サーバーは要求を処理し、リソース URI に対して検証します。これは、非標準であり、アプリケーションが依存しないようにする必要があります。If this removes the trailing slash, the login server still processes the request and validates it against the resource URI, even though they no longer match - this is non-standard and should not be relied on by your application.

アプリケーションの所有者やユーザーによる同意プロセスの間に予期しないエラーが発生する場合は、こちらの記事「アプリケーションに同意すると、予期しないエラーが発生する」のトラブルシューティング手順をご覧ください。If you or your application's users are seeing unexpected errors during the consent process, see this article for troubleshooting steps: Unexpected error when performing consent to an application.