共用方式為


受保護的 Web API:應用程式註冊

本文說明如何註冊受保護 Web API 的應用程式。

如需註冊應用程式的通用步驟,請參閱快速入門:使用 Microsoft 身分識別平台註冊應用程式

接受的權杖版本

Microsoft 身分識別平台可以發出 v1.0 權杖和 v2.0 權杖。 如需這些權杖的詳細資訊,請參閱存取權杖

當您在 Azure 入口網站中建立 Web API 應用程式註冊時,API 可接受的權杖版本取決於您選取的 [支援的帳戶類型]

  • 如果 [支援的帳戶類型] 值是 [任何組織目錄中的帳戶和個人 Microsoft 帳戶 (例如 Skype、Xbox、Outlook.com)],則接受的權杖版本必須是 v2.0。
  • 否則,接受的權杖版本可能是 v1.0。

建立應用程式之後,您可以依照下列步驟來判斷或變更接受的權杖版本:

  1. 在 Microsoft Entra 系統管理中心中,選取您的應用程式,然後選取 [資訊清單]
  2. 在資訊清單中尋找屬性 accessTokenAcceptedVersion
  3. 該值向 Microsoft Entra 指定 Web API 接受的權杖版本。
    • 如果值為 2,則 Web API 會接受 v2.0 權杖。
    • 如果值為 Null,Web API 會接受 v1.0 權杖。
  4. 在變更權杖版本後,請選取 [儲存]

Web API 會指定可接受的權杖版本。 當用戶端向 Microsoft 身分識別平台要求 Web API 的權杖時,用戶端會取得指出 Web API 接受權杖版本的權杖。

沒有重新導向 URI

Web API 不需要註冊重新導向 URI,因為使用者不會以互動方式登入。

公開的 API

Web API 特定的其他設定是公開的 API 和公開的範圍,或應用程式角色。

範圍和應用程式識別碼 URI

範圍通常具有表單 resourceURI/scopeName。 針對 Microsoft Graph,範圍具有捷徑。 例如,User.Readhttps://graph.microsoft.com/user.read 的捷徑。

在應用程式註冊期間,定義這些參數:

  • 資源 URI
  • 一或多個範圍
  • 一或多個應用程式角色

根據預設,應用程式註冊入口網站會建議您使用資源 URI api://{clientId}。 此 URI 是唯一值,但人類無法理解。 如果您變更 URI,請確定新的值是唯一值。 應用程式註冊入口網站會確保您使用已設定的發行者網域

在用戶端應用程式中,範圍會顯示為「委派的權限」,而應用程式角色會顯示為您 Web API 的「應用程式權限」

範圍也會出現在向應用程式使用者顯示的同意視窗上。 因此,請提供描述範圍的對應字串:

  • 如使用者所見。
  • 如租用戶管理員所見,管理員可授與系統管理員同意。

使用者無法同意應用程式角色 (因為這些角色是由代表使用者呼叫 Web API 的應用程式所使用)。 租用戶管理員必須同意您 Web API 的用戶端應用程式公開應用程式角色。 如需詳細資訊,請參閱系統管理員同意

公開委派權限 (範圍)

若要公開委派的權限或「範圍」,請遵循設定設定應用程式以公開 Web API 中的步驟。

如果您遵循本系列文章所述的 Web API 情節,請使用下列設定:

  • 應用程式識別碼 URI:如果出現提示,請接受建議的應用程式識別碼 URI (api://<clientId>)
  • 範圍名稱access_as_user
  • 有權同意者:管理員和使用者
  • 管理員同意顯示名稱Access TodoListService as a user
  • 管理員同意敘述Accesses the TodoListService web API as a user
  • 使用者同意顯示名稱Access TodoListService as a user
  • 使用者同意敘述Accesses the TodoListService web API as a user
  • 狀態已啟用

提示

對於應用程式識別碼 URI,您可以選擇將其設定為 API 的實體授權單位,例如 https://graph.microsoft.com。 如果已知需要呼叫之 API 的 URL,這非常有用。

如果您的 Web API 是由服務或精靈應用程式呼叫

如果您的 API 應該由精靈、服務或其他非互動式 (人為) 應用程式存取,請公開「應用程式權限」,而非委派權限。 由於精靈和服務型別應用程式會自動執行,並使用自己的身分識別進行驗證,因此沒有任何使用者可「委派」其權限。

公開應用程式權限 (應用程式角色)

若要公開應用程式權限,請遵循將應用程式角色新增至您的應用程式中的步驟。

在 [允許的成員類型] 底下的 [建立應用程式角色] 窗格中,選取 [應用程式]。 或者如文章中所述,使用 [應用程式資訊清單編輯器] 新增角色。

限制特定用戶端應用程式的存取權杖

應用程式角色是應用程式開發人員用來公開其應用程式權限的機制。 您的 Web API 程式碼應該在從呼叫者收到的存取權杖中,檢查是否有應用程式角色。

若要新增另一層安全性,Microsoft Entra 租用戶系統管理員可以設定其租用戶,讓 Microsoft 身分識別平台「只會」將安全性權杖發行至其核准 API 存取權的用戶端應用程式。

為了提升安全性,如欲將權杖發行限制為已指派應用程式角色的用戶端應用程式:

  1. Microsoft Entra 系統管理中心中,選取 [身分識別] > [應用程式] > [應用程式註冊]
  2. 在應用程式的 [概觀] 頁面的 [基本資訊] 中,找到並選擇其 [本地目錄中的受控應用程式] 連結,以瀏覽至其 [企業應用程式概觀] 頁面。
  3. [管理] 底下,選取 [屬性]
  4. 需要設定 [指派] 嗎?切換為 [是]
  5. 選取 [儲存]。

現在 Microsoft Entra ID 會檢查用戶端應用程式的應用程式角色指派,這些用戶端應用程式會要求 Web API 的存取權杖。 如果用戶端應用程式尚未指派任何應用程式角色,Microsoft Entra ID 會將錯誤訊息傳回類似 _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_ 的用戶端。

警告

請勿在應用程式的程式碼中使用 AADSTS 錯誤碼或其訊息字串作為常值。 "AADSTS" 錯誤碼和 Microsoft Entra ID 所傳回的錯誤訊息字串並非不可變,而且 Microsoft 得在您不知情的情況下變更。 如果您根據 AADSTS 程式碼或其訊息字串的值,在程式碼中做出分支決策,會導致應用程式的功能和穩定性面臨風險。

後續步驟

本系列中的下一篇文章是應用程式程式碼設定