權限及同意 Microsoft 身分識別平台端點中Permissions and consent in the Microsoft identity platform endpoint

適用範圍:Applies to:
  • Microsoft 身分識別平台端點Microsoft identity platform endpoint

與 Microsoft 身分識別平台整合的應用程式,會遵循可讓使用者和系統管理員控制資料存取方式的授權模型。Applications that integrate with Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. 已更新的授權模型實作端點上的 Microsoft 身分識別平台,並變更應用程式必須使用 Microsoft 身分識別平台互動的方式。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.

注意

Microsoft 身分識別平台端點不支援所有的案例和功能。The Microsoft identity platform endpoint does not support all scenarios and features. 若要判斷您是否應該使用 Microsoft 身分識別平台的端點,請參閱Microsoft 身分識別平台限制To determine whether you should use the Microsoft identity platform endpoint, read about Microsoft identity platform limitations.

範圍和權限Scopes and permissions

Microsoft 身分識別平台會實作 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 身分識別平台整合的 Web 主控資源都具有資源識別碼 (或稱為「應用程式識別碼 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 AD Graph:https://graph.windows.netAzure AD Graph: https://graph.windows.net

注意

強烈建議您使用 Microsoft Graph,而不要使用 Azure AD Graph、Office 365 郵件 API 等工具。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph, Office 365 Mail API, etc.

這也適用於已與 Microsoft 身分識別平台整合的第三方資源。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 身分識別平台中會以字串值表示。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 身分識別平台的要求中指定範圍的這些權限授權端點。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 身分識別平台支援兩種類型的權限:委派權限應用程式權限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. 在組織內,已登入使用者的權限會由原則或是一或多個系統管理員角色的成員資格決定。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

Microsoft 身分識別平台的 OpenID Connect 實作有一些定義妥善的範圍,不會套用到特定的資源: openidemailprofile,和offline_accessThe Microsoft identity platform implementation of OpenID Connect has a few well-defined scopes that do not apply to a specific resource: openid, email, profile, and offline_access. 不支援 addressphone OpenID Connect 範圍。The address and phone OpenID Connect scopes are not supported.

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 身分識別平台的權杖端點用來取得識別碼權杖,應用程式可以使用來進行驗證。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. 它可以存取的資訊包括但不限於使用者的名字、 姓氏、 慣用使用者名稱和物件識別碼。The information it can access includes, but isn't limited to, the user's given name, surname, preferred username, and object ID. 如需特定使用者之識別碼權杖中可用的設定檔宣告完整清單,請參閱 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 身分識別平台的權杖端點收到重新整理權杖。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.

如果您的應用程式並未明確地要求 offline_access 範圍,則不會收到重新整理權杖。If your app does not explicitly request the offline_access scope, it won't 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. 存取權杖的有效期通常在一小時內。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. 雖然offline_access範圍自動由伺服器上,您的用戶端必須仍要求它以便接收重新整理權杖。While the offline_access scope is automatically requested by the server, your client must still request it in order to receive the refresh tokens.

如需如何取得及使用重新整理權杖的詳細資訊,請參閱Microsoft 身分識別平台通訊協定參考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. 藉由將權限值附加至資源的識別碼 (應用程式識別碼 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 身分識別平台端點檢查是否有相符的記錄使用者同意After the user enters their credentials, the Microsoft identity platform endpoint checks for a matching record of user consent. 如果使用者尚未同意任何要求的權限在過去,也不具有系統管理員同意這些權限,代表整個組織,Microsoft 身分識別平台端點會要求使用者授與要求的權限。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.

如果公司的系統管理員在使用您的應用程式時被導向至授權端點,Microsoft 身分識別平台將會偵測使用者的角色,並詢問他們是否要代表整個租用戶同意您所要求的權限。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

管理員同意不接受範圍參數,因此所要求的任何權限都必須以靜態方式定義在應用程式的註冊中。The admin consent does not accept a scope parameter, so any permissions being requested must be statically defined in the application's registration. 一般情況下,它會是最佳的作法,以確保指定的應用程式以靜態方式定義的權限要求的權限,它將會以動態方式/以累加方式的超集。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.

若要設定的靜態要求的權限的應用程式清單To configure the list of statically requested permissions for an application

  1. 移至您的應用程式Azure 入口網站-應用程式註冊體驗,或建立應用程式如果您還沒有這麼做。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. 選取 Microsoft Graph從可用的 Api 清單,然後加入您的應用程式所需的權限。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 身分識別平台通訊協定教學課程To sign the user in, follow our Microsoft identity platform protocol tutorials.

向目錄管理員要求權限Request the permissions from a directory admin

當您準備好向組織的系統管理員要求權限時,您可以將使用者重新導向至 Microsoft 身分識別平台系統管理員同意端點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}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
// Pro tip: Try pasting the below request in a browser!
https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
參數Parameter 條件Condition 描述Description
tenant 必要項Required 您想要要求權限的目錄租用戶。The directory tenant that you want to request permission from. 可以提供 GUID 或易記的名稱格式,或是一般會參考使用 common (如範例所示)。Can be provided in GUID or friendly name format OR generically referenced with common as seen in the example.
client_id 必要項Required 應用程式 (用戶端) 識別碼Azure 入口網站-應用程式註冊指派給您的應用程式的體驗。The 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.

此時,Azure AD 會要求租用戶系統管理員登入來完成要求。At this point, Azure AD requires a tenant administrator to sign in to complete the request. 系統會請系統管理員核准您在應用程式註冊入口網站中,為您應用程式要求的所有權限。The administrator is asked to approve all the permissions that you have requested for your app in the app registration portal.

成功回應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 將設定為 TrueWill 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. 一個存取權杖只能用於一個單一資源,但存取權杖內部所編碼的是您應用程式針對該資源已獲得的每項權限。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 身分識別平台權杖端點,就像這樣: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 身分識別平台的端點通訊協定參考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 身分識別平台的端點。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. scope 值為 https://graph.microsoft.com/.default 在功能上與 v1.0 端點 resource=https://graph.microsoft.com 相同 - 也就是說,它會對應用程式已在 Azure 入口網站中註冊的 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.

/.Default 範圍可用在任何 OAuth 2.0 流程中,但是,不需要上的代理者流程用戶端認證流程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.

注意

用戶端無法結合靜態 (/.default) 和動態同意單一要求中的。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.readThe 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 之間不存在使用者同意。No consent for the user exists between the client and Microsoft Graph. 用戶端已註冊 user.readcontacts.read 權限,以及 Azure Key Vault 範圍 https://vault.azure.net/user_impersonationThe 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 範圍。The token returned will have just the user.read and contacts.read scopes in it.

範例 3:使用者已同意,但用戶端要求額外的範圍Example 3: The user has consented and the client requests additional scopes

使用者已經對用戶端同意 mail.readThe 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 only and all 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.readThe 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. 這種行為存在 msal,從 ADAL 移動某些舊版用戶端,而且不應由新的用戶端為目標的 Microsoft 身分識別平台的端點。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.

如果您或應用程式的使用者在同意程序中發現非預期的錯誤,請參閱本文以取得疑難排解步驟:對應用程式執行同意時出現非預期的錯誤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.