共用方式為

Microsoft 身分識別平台的範圍和權限

  • 發行項

Microsoft 身分識別平台會實作 OAuth 2.0 授權通訊協定。 OAuth 2.0 是一種可讓第三方應用程式代表使用者存取 Web 主控資源的方法。 任何與 Microsoft 身分識別平台整合的 Web 託管資源都具有資源識別碼，又稱為應用程式識別碼 URI。

在本文中，您會了解身分識別平台的範圍和範圍。

下列清單顯示 Microsoft Web 裝載資源的幾個範例：

  • Microsoft Graph：https://graph.microsoft.com
  • Microsoft 365 Mail API：https://outlook.office.com
  • Azure Key Vault：https://vault.azure.net

對於任何已整合 Microsoft 身分識別平台的的第三方資源也是如此。 上述任何資源都可以定義一組權限，以將該資源的功能切割成較小區塊。 例如，Microsoft Graph 除了別的之外，還定義了權限來執行下列工作：

  • 讀取使用者的行事曆
  • 寫入使用者的行事曆
  • 以使用者身分傳送電子郵件

由於這些類型的權限定義，資源對其資料以及 API 功能的公開方式有更細緻的控制。 第三方應用程式可向使用者和系統管理員要求這些權限，且必須在他們核准要求後，應用程式才可存取資料或代表使用者執行動作。

當資源的功能切割成較小的權限集時，第三方應用程式可以建立成只要求其功能運作所需的權限。 使用者和系統管理員可以知道應用程式所能存取的資料。 更加確信應用程式沒有惡意。 開發人員應總是遵守最低權限的原則，僅要求其應用程式運作所需的權限。

在 OAuth 2.0 中，這些類型的權限集合稱為「範圍」。 我們也常將其稱為「權限」。 在 Microsoft 身分識別平台，權限以字串值表示。 應用程式透過 scope 查詢參數中指定權限，以要求所需的權限。 身分識別平台支援多個定義明確的 OpenID Connect 範圍，以及資源型權限 (在資源的識別碼或應用程式識別碼 URI 後面附加權限值，以表示每個權限)。 例如，權限字串 https://graph.microsoft.com/Calendars.Read 可用來要求在 Microsoft Graph 中讀取使用者行事曆的權限。

在 Microsoft 身分識別平台的授權服務要求中，如果範圍參數中省略了資源識別碼，則假定該資源是 Microsoft Graph。 例如，scope=User.Read 相當於 https://graph.microsoft.com/User.Read。

管理員受限的權限

Microsoft 身分識別平台的權限可以設為須受管理員限制。 例如，很多較高權限的 Microsoft Graph 權限要求管理員核准。 如果應用程式需要受管理員限制的權限，組織管理員必須代表組織使用者同意這些範圍。 下一節提供這類權限的範例：

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

注意

向 Microsoft 身分識別平台的授權、權杖或同意端點提出要求時，如果 scope 參數中省略資源識別碼，則假定資源為 Microsoft Graph。 例如，scope=User.Read 相當於 https://graph.microsoft.com/User.Read。

雖然消費者使用者可以授與應用程式存取這類資料，但組織使用者無法授與存取同一組敏感性公司資料。 如果應用程式向組織使用者要求存取其中一個權限，使用者會收到錯誤訊息，指出他們無權同意應用程式權限。

如果應用程式要求應用程式權限，且管理員授與這些權限，則管理員不是代表任何特定使用者完成此授與。 此時會直接為用戶端應用程式授與權限。 只有精靈服務及其他在背景執行的非互動式應用程式才應使用這些類型的權限。 如需直接存取案例的詳細資訊，請參閱 Microsoft 身分識別平台的存取案例。

如需如何在 Web API 中公開範圍的逐步指南，請參閱設定應用程式公開 Web API。

OpenId Connect 範圍

Microsoft 身分識別平台的 OpenID Connect 實作有幾個定義明確的範圍也託管於 Microsoft Graph：openid、email、profile 和 offline_access。 不支援 address 和 phone OpenID Connect 範圍。

如果您要求 OpenID Connect 範圍和權杖，則會取得權杖來呼叫 UserInfo 端點。

openid 範圍

如果應用程式使用 OpenID Connect 來登入，則必須要求 openid 範圍。 openid 範圍在公司帳戶同意頁面上顯示為 [將您登入] 權限。

此權限可讓應用程式以 sub 宣告的形式接收使用者的唯一識別碼。 此權限也可讓應用程式存取 UserInfo 端點。 在 Microsoft 身分識別平台權杖端點上，可以使用 openid 範圍來取得識別碼權杖。 應用程式可以使用這些權杖進行驗證。

email 範圍

email 範圍可以搭配 openid 範圍及任何其他範圍一起使用。 它會以 email 宣告的形式為應用程式提供使用者主要電子郵件地址的存取權。

只有當使用者帳戶有相關聯的電子郵件地址時，權杖才會包含 email 宣告 (但不一定)。 如果應用程式使用 email 範圍，應用程式必須能夠處理權杖中沒有 email 宣告的情況。

profile 範圍

profile 範圍可以搭配 openid 範圍及任何其他範圍一起使用。 此範圍可讓應用程式存取使用者的大量相關資訊。 它能存取的資訊包括但不限於使用者的名字、姓氏、慣用使用者名稱及物件識別碼。

如需特定使用者的 id_tokens 參數中可用的 profile 宣告完整清單，請參閱 id_tokens 參考。

offline_access 範圍

offline_access 範圍可延長您應用程式代表使用者存取資源的時間。 在同意頁面上，此範圍顯示為 [繼續存取您已授與存取權的資料] 權限。

當使用者核准 offline_access 範圍時，您的應用程式就可以從 Microsoft 身分識別平台權杖端點收到重新整理權杖。 重新整理權杖會長期存在。 當舊存取權杖過期時，您的應用程式即可獲得新存取權杖。

注意

此權限目前出現在所有同意頁面上，即使流程未提供重新整理權杖也一樣 (例如隱含流程)。 如果用戶端可能從隱含流程內開始，然後進入需要有重新整理權杖的程式碼流程，此設定可解決這種情況。

在 Microsoft 身分識別平台上 (對 v2.0 端點提出要求)，您的應用程式必須明確要求 offline_access 範圍，才能收到重新整理權杖。 當您在 OAuth 2.0 授權碼流程中兌換授權碼時，只會從 /token 端點收到存取權杖。

存取權杖通常大約一小時有效。 屆時，您的應用程式將必須把使用者重新導向回 /authorize 端點，以要求新的授權碼。 在此重新導向期間，視應用程式類型而定，使用者可能需要再次輸入其認證，或再次同意權限。

重新整理令牌的到期時間比存取令牌還長，而且通常有效期為一天。 如需有關如何取得及使用重新整理權杖的詳細資訊，請參閱 Microsoft 身分識別平台通訊協定參考。

在回應中包含重新整理令牌可能取決於數個因素，包括應用程式的特定設定，以及授權程序期間要求的範圍。 如果您預期在回應中收到重新整理令牌但失敗，請考慮下列因素：

  • 範圍需求：請確定您要求 offline_access 範圍以及任何其他必要範圍。
  • 授權授與類型：使用授權碼授與類型時，通常會提供重新整理令牌。 如果您的流程不同，可能會影響回應。
  • 用戶端組態：檢查身分識別平臺中的應用程式設定。 某些組態可能會限制發行refresh_tokens。

.default 範圍

.default 範圍用於泛指要求中的資源服務 (API)，而不識別特定權限。 如果需要同意，則使用 .default 可表示應該提示同意應用程式註冊中列出的所有必要權限 (針對清單中的所有 API)。

scope 參數值由資源的識別碼 URI 和 .default 構成，以斜線分隔 (/)。 例如，如果資源的識別碼 URI 為 https://contoso.com，則要求的範圍是 https://contoso.com/.default。 如果您必須加上第二個斜線才能正確要求權杖，請參閱尾端斜線一節。

使用 scope={resource-identifier}/.default 在功能上等同於 v1.0 端點上的 resource={resource-identifier} (其中 {resource-identifier} 是 API 的識別碼 URI，例如 Microsoft Graph 的 https://graph.microsoft.com)。

.default 範圍可用於任何 OAuth 2.0 流程，並起始管理員同意。 代理者流程和用戶端認證流程中需要使用此範圍。

用戶端在單一要求中不能兼具靜態 (.default) 同意和動態同意。 因此，scope=https://graph.microsoft.com/.default Mail.Read 會因為合併範圍類型而導致錯誤。

只有在用戶端與資源間的任何委派權限並未授與同意的情況下，.default 範圍參數才會代表登入使用者觸發同意提示。

如果已同意，傳回的權杖會包含登入使用者針對該資源授與的所有範圍。 但是，如果尚未授與所要求資源的權限 (或已提供 prompt=consent 參數)，則會出現同意提示，要求同意用戶端應用程式註冊上針對清單中所有 API 設定的一切必要權限。

例如，如果要求範圍 https://graph.microsoft.com/.default，表示應用程式要求 Microsoft Graph API 的存取權杖。 如果已代表登入使用者授與 Microsoft Graph 至少一個委派權限，則登入會繼續，而且存取權杖中會包含所有已授與該使用者的 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 起始第二次登入，但這次使用 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 身分識別平台為目標的新用戶端「不應該」使用此設定。 請務必從 Azure AD 驗證程式庫 (ADAL) 移轉至 Microsoft 驗證程式庫 (MSAL)。

用戶端認證授與流程和 .default

.default 的另一種用法是在非互動式應用程式中要求應用程式角色 (又稱為應用程式權限)，例如精靈應用程式經由用戶端認證授與流程來呼叫 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 應該接受卻拒絕權杖，請考慮加上第二個斜線，然後再試一次。

另請參閱