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

  • 文章

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

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

接受的令牌版本

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

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

  • 如果支援的帳戶類型值為任何組織目錄中的帳戶和個人 Microsoft 帳戶（例如 Skype、Xbox、Outlook.com），則可接受的令牌版本必須是 v2.0。
  • 否則，可接受的令牌版本可以是 v1.0。

建立應用程式之後，您可以遵循下列步驟來判斷或變更可接受的令牌版本：

  1. 在 Azure 入口網站 中，選取您的應用程式，然後選取 [指令清單]。
  2. 在指令清單中尋找 property 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
  • 神秘 可以同意：管理員 和使用者
  • 管理員 同意顯示名稱：以使用者身分存取 TodoListService
  • 管理員 同意描述：以使用者身分存取 TodoListService Web API
  • 使用者同意顯示名稱： 以使用者身分存取 TodoListService
  • 使用者同意描述： 以使用者身分存取 TodoListService Web API
  • 狀態： 已啟用

提示

針對應用程式識別碼 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：應用程式<應用程式名稱>未指派給 Web API> 的角色<。

警告

請勿在應用程式的程式代碼中使用 AADSTS 錯誤碼 或其訊息字串作為常值。 Microsoft Entra ID 所傳回的「AADSTS」錯誤碼和錯誤訊息字串不可變，且可以隨時由 Microsoft 變更，且不知情。 如果您根據 AADSTS 程式代碼的值或其訊息字串，在程式代碼中做出分支決策，您會讓應用程式的功能和穩定性面臨風險。

下一步

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