使用 getClientCapabilities() 简化 WebAuthn 功能检测

Eiji Kitamura

发布时间：2025 年 1 月 15 日

WebAuthn 提供独特的功能，例如与蓝牙交互以实现混合协议、与通行密钥提供方通信，以及在自动填充中建议通行密钥。不过，不同的客户端和身份验证器对 WebAuthn 功能的支持程度各不相同。这种差异可能会导致用户体验不一致，部分用户可能会遇到错误或无法使用某些身份验证选项。为开发者提供一种确定客户端功能的方法，使他们能够创建更可靠的身份验证流程，以适应这些变化。

借助 PublicKeyCredential.getClientCapabilities() 方法，信赖方可以确定浏览器支持哪些 WebAuthn 功能。该方法会返回一个 promise，该 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

如果用户已同意创建凭据，浏览器可以在不显示醒目的模态界面的情况下创建凭据。

conditionalGet

浏览器可以通过在自动填充对话框中显示通行密钥来进行身份验证，而不是通过醒目的模态界面。现有等效项为 PublicKeyCredential.isConditionalMediationAvailable()。

hybridTransport

设备可以使用蓝牙，以便浏览器可以创建凭据，并使用混合协议通过该凭据进行跨设备身份验证。这通常意味着浏览器可以显示二维码，以便用户扫描该二维码并使用具有凭据的手机登录。

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 扩展程序标识符。

了解详情

如需详细了解通行密钥，请先参阅使用通行密钥实现无密码登录。