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

發行項
07/03/2024

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

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

接受的權杖版本

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

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

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

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

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

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

沒有重新導向 URI

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

公開的 API

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

範圍和應用程式識別碼 URI

範圍通常具有表單 resourceURI/scopeName。針對 Microsoft Graph，範圍具有捷徑。例如，User.Read 是 https://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 存取權的用戶端應用程式。

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

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

現在 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 程式碼或其訊息字串的值，在程式碼中做出分支決策，會導致應用程式的功能和穩定性面臨風險。

後續步驟

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

共用方式為