使用 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

如果用户已经同意创建凭据，则浏览器可以创建凭据，而无需显示突出的模态 UI。

conditionalGet

浏览器可以通过将通行密钥显示为自动填充对话框的一部分，而不是突出的模态 UI 来进行身份验证。现有的等效项是 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 扩展程序标识符。

了解更多信息

要了解有关通行密钥的更多信息，请从使用通行密钥进行无密码登录开始。