共用方式為

在 Microsoft身分識別平臺中要求許可權和同意的開發人員指南

Microsoft身分識別平臺中的應用程式依賴同意，以取得必要資源或 API 的存取權。 對於不同的應用程式案例，不同類型的同意比較好。 為您的應用程式選擇最佳同意方法，可讓用戶和組織更成功。

在本文中，您將瞭解不同類型的同意，以及如何透過同意要求應用程式的許可權。

備註

對於外部租戶中的應用程式，客戶無法自行同意許可權。 系統管理員必須授與同意，應用程式才能代表他們存取資源。 如需詳細資訊，請參閱 授與管理員同意。

在靜態使用者同意案例中，您必須在 Microsoft Entra 系統管理中心的應用程式設定中指定它所需的所有許可權。 如果使用者（或系統管理員，視需要）未授與此應用程式的同意，則Microsoft身分識別平臺會提示使用者目前提供同意。

靜態權限也可讓系統管理員在組織中代表所有使用者授予同意。

雖然依賴靜態同意和單一許可權清單可讓程式代碼保持良好且簡單，但也表示您的應用程式會要求它可能需要的所有許可權。 此設定可防止使用者和系統管理員核准應用程式的存取要求。

透過Microsoft身分識別平臺端點，您可以忽略 Microsoft Entra 系統管理中心的應用程式註冊資訊中定義的靜態許可權。 相反地，你可以從應用程式的程式碼中動態請求權限。 你可以先要求一組最低限度的權限，隨著客戶使用更多應用程式功能，逐步要求其他權限。 為此，你可以在scope時，在參數中包含範圍，指定應用程式所需的範圍，無需在應用程式註冊資訊中預先定義。

如果使用者未同意請求中的任何範圍，他們會收到請求中所有權限的同意提示。 這些權限會額外授予該應用程式已獲得的其他權限（即增量式）。 增量同意僅適用於委派權限，不適用於應用程式權限。

允許應用程式透過 scope 參數動態要求許可權，可讓開發人員完全掌控用戶體驗。 您預先安排同意過程，並在一次初始授權請求中要求所有的權限。 如果您的應用程式需要大量的許可權，您可以累加收集使用者的許可權，因為他們嘗試在一段時間內使用應用程式的某些功能。

這很重要

動態同意可能很方便，但對於需要管理員同意的許可權而言，會面臨重大挑戰。 在入口的應用程式註冊和企業應用程式功能區中，系統管理員的同意流程並未在同意動態許可權時提供相關資訊。 我們建議開發人員列出應用程式在入口網站中所需的所有系統管理員特殊許可權。

這可讓租用戶系統管理員在入口網站中代表其所有使用者一次性同意。 使用者不需要在登入時經歷這些許可權的同意體驗。 替代方式是針對這些許可權使用動態同意。 若要授予管理員的同意，個別系統管理員需登入應用程式，觸發適當許可權的同意提示，並在同意對話框中選擇 同意我的整個組織。

在 OpenID Connect或 OAuth 2.0 授權要求中，應用程式可以使用查詢參數來要求所需的 scope 許可權。 例如，當使用者登入應用程式時，應用程式會傳送要求，如下列範例所示。 （換行符為可讀性而增加）。

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

參數 scope 是應用程式要求之委派許可權的空間分隔清單。 在資源的識別碼 (應用程式識別碼 URI) 後面附加權限值，以表示每個權限。 在要求範例中，應用程式需要許可權才能讀取使用者的行事曆，並以使用者身分傳送郵件。

登入之後，Microsoft身分識別平台會檢查現有的使用者同意。 如果使用者未核准要求的許可權，而系統管理員也不會核准這些許可權，平臺會提示使用者授與同意。

在下列範例中， offline_access [維護您授與存取權的數據存取權] 和 User.Read [登入並讀取配置檔] 權限會自動包含在應用程式的初始同意中。 適當的應用程式功能需要這些許可權。

權限 offline_access 可讓應用程式存取對原生 app 和網頁 app 而言至關重要的重新整理令牌。 該 User.Read 許可權賦予對 sub 宣告的存取權。 它可讓用戶端或應用程式在一段時間內正確識別使用者，並存取基本的用戶資訊。

顯示工作帳戶同意的範例螢幕快照。

當使用者核准許可權要求時，會記錄同意。 使用者稍後登入應用程式時，不需要再次同意。

要求整個租戶的同意，需要管理員同意。 代表組織進行管理員同意時，需要應用程式所註冊的靜態許可權。 如果您需要系統管理員代表整個組織同意，請設定應用程式註冊入口網站中的這些許可權。

當您的應用程式要求 需要系統管理員同意的委派許可權時，使用者會看到「未經授權同意」錯誤，且需要要求系統管理員存取權。 一旦系統管理員授與整個租使用者的同意，除非撤銷同意或新增許可權，否則不會再次提示使用者。

使用相同應用程式的系統管理員會看到管理員同意提示。 系統管理員同意的提示會提供一個複選框，允許他們代表整個租戶的使用者授予應用程式存取權，以存取所要求的資料。 如需使用者和系統管理員同意體驗的詳細資訊，請參閱 應用程式同意體驗。

需要管理員同意之 Microsoft Graph 的委派許可權範例如下：

  • 使用 User.Read.All 讀取所有使用者的完整設定檔
  • 使用 Directory.ReadWrite.All 將資料寫入到組織的目錄
  • 使用 Groups.Read.All 讀取組織目錄中的所有群組

若要檢視Microsoft Graph 許可權的完整清單，請參閱 Microsoft Graph 許可權參考。

您也可以在自己的資源上設定許可權，以要求系統管理員同意。 如需如何新增需要管理員同意的範圍的詳細資訊，請參閱 新增需要管理員同意的範圍。

某些組織可能會變更租用戶的預設使用者同意原則。 當您的應用程式要求存取這些原則時，系統會根據這些原則評估許可權。 使用者可能需要要求管理員同意，即使預設不需要。 若要了解系統管理員如何管理應用程式的同意原則，請參閱 管理應用程式同意原則。

備註

在 Microsoft 識別平台的授權、令牌或同意要求中，如果省略了參數中的 scope 資源識別碼，則預設為 Microsoft Graph。 例如，scope=User.Read 被視為 https://graph.microsoft.com/User.Read。

應用程式許可權一律需要管理員同意。 應用程式許可權沒有用戶內容，而且不會代表任何特定使用者完成同意授與。 而是直接授與用戶端應用程式權限。 這些類型的許可權只能由背景中執行的精靈服務和其他非互動式應用程式使用。 系統管理員必須事先設定許可權，並透過 Microsoft Entra 系統管理中心 授與系統管理員同意 。

如果要求權限的應用程式是多租戶應用程式，其應用程式註冊只存在於應用程式被建立的租戶中，因此無法在本地租戶中設定權限。 如果應用程式要求需要系統管理員同意的許可權，系統管理員必須代表使用者同意。 若要同意這些許可權，系統管理員必須自行登入應用程式，因此會觸發系統管理員同意登入體驗。 若要瞭解如何設定多租使用者應用程式的系統管理員同意體驗，請參閱 啟用多租使用者登入

系統管理員可以使用下列選項來授與應用程式的同意。

一般而言，當您建置需要系統管理員同意的應用程式時，應用程式需要頁面或檢視，系統管理員可以核准應用程式的許可權。 此頁面可以是：

  • 應用程式的註冊流程的一部分。
  • 應用程式的設定的一部分。
  • 專用的「連線」流程。

在許多情況下，只有在使用者以公司Microsoft帳戶或學校Microsoft帳戶登入之後，應用程式才會顯示「連線」檢視。

當您將使用者登入應用程式時，您可以先識別系統管理員所屬的組織，再要求他們核准必要的許可權。 雖然此步驟並非絕對必要，但它可協助您為組織使用者建立更直覺的體驗。

若要登入使用者，請遵循 Microsoft 身分識別平台通訊協定教學課程。

在應用程式註冊入口網站中要求權限

在應用程式註冊入口網站中，應用程式可以列出他們所需的許可權，包括委派的許可權和應用程式許可權。 此設定允許使用 .default 範圍和 Microsoft Entra 系統管理中心的 [授與系統管理員同意 ] 選項。

一般而言，應該以靜態方式定義指定應用程式的許可權。 它們應該是應用程式以動態或累加方式要求的許可權超集。

備註

應用程式許可權只能使用 .default來要求。 因此，如果您的應用程式需要應用程式許可權，請確定它們列在應用程式註冊入口網站中。

若要設定應用程式靜態要求的權限清單：

  1. 以至少 雲端應用程式系統管理員 的身分登入 Microsoft Entra 系統管理中心。
  2. 流覽至 Entra ID>應用程式註冊>所有應用程式。
  3. 選取應用程式，或如果您尚未 建立應用程式，請建立應用程式 。
  4. 在應用程式的 [ 概觀] 頁面上，於 [ 管理] 底下，選取 [ API 許可權>] [新增許可權]。
  5. 從可用的 API 清單中選取 [Microsoft Graph]。 然後新增應用程式所需的許可權。
  6. 選取新增權限。

成功回應

如果系統管理員核准應用程式的許可權，成功的回應如下所示：

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
參數 說明
tenant 授與您的應用程式其所要求許可權的目錄租戶，其格式為 GUID。
state 令牌回應中傳回的要求中包含的值。 其可以是任何您所需內容的字串。 狀態是用來在驗證要求發生之前，在應用程式中編碼用戶狀態的相關信息，例如他們開啟的頁面或檢視。
admin_consent 設定為 True。

從系統管理員同意端點收到成功的回應之後，您的應用程式會獲授與其要求的許可權。 接下來，您可以為您想要的資源請求令牌。

錯誤回應

如果系統管理員未核准您應用程式的許可權，失敗的回應如下所示：

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
參數 說明
error 錯誤碼字串，可用來分類發生的錯誤類型。 它也可以用來回應錯誤。
error_description 特定錯誤訊息，可協助開發人員識別錯誤的根本原因。

在使用者同意應用程式的許可權之後，您的應用程式可以取得存取令牌，代表應用程式在某些容量中存取資源的許可權。 存取令牌只能用於單一資源。 但是，在存取令牌內編碼了應用程式針對該資源授予的每個許可權。 若要取得存取令牌，您的應用程式可以向Microsoft身分識別平臺令牌端點提出要求，如下所示：

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

您可以在對資源的 HTTP 要求中使用產生的存取權杖。 它會可靠地向資源指出您的應用程式具有執行特定工作的適當許可權。

如需 OAuth 2.0 通訊協定以及如何取得存取令牌的詳細資訊，請參閱 Microsoft身分識別平臺端點通訊協議參考。

相關內容

  • Last updated on