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

Eiji Kitamura

發布日期：2025 年 1 月 15 日

WebAuthn 提供獨特功能，例如與混合式通訊協定的藍牙互動、與密碼金鑰供應器通訊，以及在自動填入功能中建議密碼金鑰。不過，不同用戶端和驗證工具對 WebAuthn 功能的支援程度各有不同。這類差異可能會導致使用者體驗不一致，部分使用者可能會遇到錯誤，或無法使用特定驗證選項。提供方法讓開發人員判斷用戶端功能，就能讓他們建立更健全的驗證流程，以便因應這些變化。

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

相容性

getClientCapabilities()

getClientCapabilities() 是 WebAuthn API，可讓信賴方判斷可用的功能。如要使用 API，您必須呼叫 PublicKeyCredential.getClientCapabilities()。傳回的承諾會解析為包含功能的物件，每個功能都會透過 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
}

這個 ID 開頭為 extension:，後面接著擴充功能名稱。如要瞭解擴充功能名稱，請參閱 在 IANA 定義的 WebAuthn 擴充功能 ID。

瞭解詳情

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