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

Eiji Kitamura

发布时间：2025 年 1 月 15 日

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

借助 PublicKeyCredential.getClientCapabilities() 方法，依赖方可以确定浏览器支持哪些 WebAuthn 功能。该方法会返回一个 promise，该 promise 会解析为支持的功能列表，让开发者能够根据客户端的具体功能量身定制身份验证体验和工作流。

兼容性

Browser Support

• x
• x
• x
• 17.4

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

了解详情

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