透過同意要求權限

  • 文章

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 身分識別平台端點會檢查是否有相符的「使用者同意」記錄。 如果使用者過去未曾同意任何要求的權限，且系統管理員也未代表整個組織同意這些權限，則 Microsoft 身分識別平台會要求使用者授與所要求的權限。

在下列範例中，對應用程式的初始同意會自動包含 offline_access (「繼續存取您已授與存取權的資料」) 和 User.Read (「將您登入及讀取您的個人檔案」) 權限。 需要這些權限，應用程式才能正常運作。 offline_access 權限可讓應用程式存取重新整理權杖，這對原生應用程式和 Web 應用程式非常重要。 User.Read 權限提供對 sub 宣告的存取權。 其可讓用戶端或應用程式隨著時間正確識別使用者，並存取基本的使用者資訊。

範例螢幕擷取畫面：顯示公司帳戶同意。

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

要求代表整個租用戶同意需要管理員同意。 代表組織行使的管理員同意需要有為應用程式註冊的靜態權限。 如果您需要管理員來代表整個組織同意，請在應用程式註冊入口網站中設定這些權限。

當您的應用程式要求需要管理員同意的委派權限時，使用者會收到錯誤訊息，指出他們未獲授權而無法對您應用程式的權限表示同意。 使用者必須要求其管理員存取應用程式。 如果管理員代表整個租用戶同意，除非撤銷先前授與的權限，或是應用程式以累加方式要求新的權限，否則組織的使用者將不會看到應用程式的同意頁面。

使用相同應用程式的管理員會看到管理員同意提示。 管理員同意提示提供一個核取方塊，可讓他們代表整個租用戶的使用者授與應用程式存取要求的資料。 如需使用者和管理員同意體驗的詳細資訊，請參閱應用程式同意體驗。

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

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

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

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

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

注意

在對 Microsoft 身分識別平台 之授權、令牌或同意端點的要求中，如果範圍參數中省略資源標識符，則資源會假設為 Microsoft Graph。 例如，scope=User.Read 相當於 https://graph.microsoft.com/User.Read。

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

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

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

通常，當您建置需要管理員同意的應用程式時，應用程式會需要一個可供管理員核准應用程式權限的頁面或檢視。 此頁面可以是：

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

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

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

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

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

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

一般而言，應該針對特定應用程式來定義靜態權限。 這些權限應該為應用程式動態或累加要求的權限超集。

注意

只能透過使用 .default 來要求應用程式權限。 因此，如果您的應用程式需要應用程式權限，請確定應用程式註冊入口網站中列出這些權限。

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

  1. 以至少雲端應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
  2. 流覽至 [身分>識別應用程式> 應用程式註冊> 所有應用程式]。
  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 身分識別平台端點通訊協定參考。

另請參閱