更简单的 WebAuthn 功能检测

Eiji Kitamura

Published: January 15, 2025, Last updated: April 09, 2026

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

PublicKeyCredential.getClientCapabilities() 方法允许信赖方确定浏览器支持哪些 WebAuthn 功能。该方法会返回一个 promise，该 promise 会解析为受支持功能的列表，以便开发者根据客户端的特定功能定制身份验证体验和工作流。

兼容性

Browser Support

  • Chrome: 133.
  • Edge: 133.
  • Firefox: 135.
  • Safari: 17.4.

Source

getClientCapabilities()

getClientCapabilities() 是一个 WebAuthn API，允许信赖方确定哪些功能可用。如需使用该 API，您需要调用 PublicKeyCredential.getClientCapabilities()。返回的 promise 会解析为一个包含功能的 对象，每个功能都使用 true 或 false 指示其可用性。如果功能为 undefined，则表示其可用性未知。

if (window.PublicKeyCredential && 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

浏览器可以创建凭据并使用该凭据进行身份验证，即使该凭据与 信赖方 ID 不匹配，只要该凭据在 相关来源 文件中指定即可。

signalAllAcceptedCredentials

浏览器可以向通行密钥提供方传递服务器上的可用凭据，以便通行密钥提供方可以使通行密钥列表与服务器保持一致。

signalCurrentUserDetails

浏览器可以向通行密钥提供方传递服务器上的用户信息（例如用户名和显示名称），以便通行密钥提供方可以使其通行密钥信息与服务器保持一致。

signalUnknownCredential

浏览器可以向通行密钥提供方传递服务器上已删除的凭据，以便通行密钥提供方可以使通行密钥列表与服务器保持一致。

userVerifyingPlatformAuthenticator

浏览器可以在平台身份验证器上创建凭据并使用该凭据进行身份验证。这并不意味着浏览器支持混合协议。现有的等效项是 PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()。

extensions

信赖方还可以使用 getClientCapabilities() 确定可用的扩展程序。

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

标识符以 extension: 为前缀，后跟扩展程序名称。 如需了解扩展程序名称，请参阅 IANA 中定义的 WebAuthn 扩展程序标识符。

了解详情

如需详细了解通行密钥，请从使用通行密钥进行无密码登录开始。