使用 getClientCapabilities() 進行更簡單的 WebAuthn 功能偵測

Eiji Kitamura

發布日期：2025 年 1 月 15 日

WebAuthn 提供多項獨特功能，例如與混合式通訊協定的藍牙互動、與密碼金鑰供應商通訊，以及在自動填入功能中建議密碼金鑰。不過，不同用戶端和驗證器對 WebAuthn 功能的支援程度不一。這種差異可能導致使用者體驗不一致，部分使用者可能會遇到錯誤，或無法使用特定驗證選項。開發人員可藉此判斷用戶端功能，進而建立更穩固的驗證流程，因應這些差異。

PublicKeyCredential.getClientCapabilities() 方法可讓信賴方判斷瀏覽器支援哪些 WebAuthn 功能。這個方法會傳回可解析為支援功能清單的 Promise，讓開發人員根據用戶端的特定功能，調整驗證體驗和工作流程。

相容性

getClientCapabilities()

getClientCapabilities() 是 WebAuthn API，可讓信賴方判斷有哪些功能可用。如要使用 API，請呼叫 PublicKeyCredential.getClientCapabilities()。傳回的 Promise 會解析為包含功能的物件，每個功能都會以 true 或 false 指出可用性。如果功能為 undefined，請考量其可用性不明。

if (window.PublicKeyCredential &&
  if (PublicKeyCredential.getClientCapabilities) {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    if (capabilities.conditionalGet === true &&
        capabilities.passkeyPlatformAuthenticator === true) {
      // The browser supports passkeys and the conditional mediation.
    }
  }
}

conditionalCreate

如果使用者已同意建立憑證，瀏覽器可以建立憑證，不必顯示顯眼的強制回應 UI。

conditionalGet

瀏覽器可以顯示密碼金鑰做為自動填入對話方塊的一部分，藉此進行驗證，而非顯示醒目的強制回應 UI。現有等效函式為 PublicKeyCredential.isConditionalMediationAvailable()。

hybridTransport

裝置可以使用藍牙，讓瀏覽器建立憑證，並透過混合式通訊協定使用該憑證跨裝置進行驗證。這通常表示瀏覽器可以顯示 QR code，供使用者掃描並透過含有憑證的手機登入。

passkeyPlatformAuthenticator

瀏覽器可以建立憑證，並透過使用者驗證平台驗證器，或透過混合通訊協定支援的其他裝置，使用憑證進行驗證。等同於 hybridTransport || userVerifyingPlatformAuthenticator。

relatedOrigins

只要瀏覽器建立的憑證與 RP ID 不符，且憑證已在相關來源檔案中指定，瀏覽器就能使用該憑證進行驗證。

signalAllAcceptedCredentials

瀏覽器可以將伺服器上可用的憑證信號傳送給密碼金鑰提供者，讓密碼金鑰提供者確保密碼金鑰清單與伺服器一致。

signalCurrentUserDetails

瀏覽器可以在伺服器上向密碼金鑰供應商發出信號，提供使用者名稱和顯示名稱等使用者資訊，讓密碼金鑰供應商的密碼金鑰資訊與伺服器保持一致。

signalUnknownCredential

瀏覽器可以向密碼金鑰提供者傳送伺服器上已刪除的憑證信號，讓密碼金鑰提供者確保密碼金鑰清單與伺服器一致。

userVerifyingPlatformAuthenticator

瀏覽器可以在平台驗證器上建立憑證並進行驗證。這不代表瀏覽器支援混合通訊協定。 現有等效函式為 PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()。

擴充功能

RP 也可以使用 getClientCapabilities() 判斷可用的擴充功能。

if (capabilities['extension:appid'] === true) {
  // appId extension is supported
}

識別碼的前置字串為 extension:，後方接著擴充功能名稱。 如需擴充功能名稱，請參閱 IANA 定義的 WebAuthn 擴充功能 ID。

瞭解詳情

如要進一步瞭解密碼金鑰，請參閱「使用密碼金鑰登入帳戶」。