分享方式：

受保護的 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.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 存取權的用戶端應用程式。

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

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

後續步驟

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