WebAuthn 客户端能力

WebAuthn 是 Passkey 背后的现代标准。它不依赖传统密码，而是利用公钥密码学，让用户能通过 Passkey 进行身份验证。这些 Passkey 可以是生物识别信息（如指纹或面部识别），也可以是实体安全密钥。这一转变不仅增强了安全性，还免去了密码管理的麻烦，从而改善了用户体验。

[WebAuthn Level 3] 标准引入了新的客户端能力（可通过浏览器 API getClientCapabilities() 获取），旨在为开发者和平台在实施 Passkey 时提供更多控制权和灵活性。这些更新带来的增强功能简化了在不同设备、浏览器和平台之间集成 Passkey 的过程，确保了更流畅、更一致的用户体验。

在这篇博客文章中，我们将回答以下问题：

1. 什么是 WebAuthn 客户端能力？
2. 存在哪些 WebAuthn 客户端能力？
3. WebAuthn 客户端能力如何改进 Passkey 的实现？
4. 为什么 WebAuthn 客户端能力对开发者和产品经理都很重要？

读完本文，我们将了解这些功能如何帮助我们创建符合现代用户期望的无缝、安全的身份验证流程。

WebAuthn 客户端能力是一组功能，允许浏览器和平台表明它们支持哪些类型的 WebAuthn 功能。简单来说，它们就像一张“功能清单”，让网站知道用户的设备上哪些身份验证方法和设置是可用的。这使得开发者可以根据客户端的能力来定制身份验证流程，从而确保更流畅、更安全的用户体验。

例如，如果浏览器表明它支持[生物识别身份验证]（如 Touch ID），开发者就可以设计登录流程，为用户提供使用指纹登录的选项。反之，如果浏览器不支持某些功能，开发者可以提供备用选项，如密码或短信一次性密码（SMS OTP）。

[WebAuthn Level 3 标准]引入了几个新的客户端能力，使 Passkey 的实现更加通用和用户友好。对 getClientCapabilities() API 调用的首次支持是在 Safari 17.4 中引入的。

要检测浏览器是否支持，以下代码片段可能会很有用：

// Check if PublicKeyCredential is supported in the current browser
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential is not supported in this browser.");
}
 
// Check if getClientCapabilities method exists on PublicKeyCredential
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Error getting client capabilities:", error);
    }
} else {
    console.log("getClientCapabilities is not supported in this browser");
}

getClientCapabilities() 允许网站和应用查询客户端（例如浏览器或设备）以确定其支持哪些 WebAuthn 功能。通过了解客户端的能力，开发者可以优化身份验证流程，利用可用的功能（如[生物识别身份验证]），并在某些能力缺失时提供替代方法。

Subscribe to our Passkeys Substack for the latest news.

Subscribe

下面我们来仔细看看 WebAuthn 的客户端能力以及它们如何影响 Passkey 的集成：

conditionalCreate 根据特定条件启用[自动创建 Passkey]。如果[密码管理器]支持，应用程序可以在[密码自动填充]期间使用此功能自动创建 Passkey。此功能通过自动将用户从密码过渡到 Passkey，有助于提高 [Passkey 的采用率]和后续使用率。

与 conditionalCreate 类似，conditionalGet 会自动触发 Passkey 登录。这在需要实现最佳 Passkey 用户体验的场景中非常有用，它使登录不仅无密码，而且无用户名（用户只需在模态框/下拉菜单中点击选定的 Passkey 即可进行身份验证）。通过使用此功能，开发者可以确保[Passkey 身份验证]仅在适当的时候发生，从而最大限度地减少不必要的提示并增强用户体验。

hybridTransport 确保 Passkey 可以在不同设备之间使用，实现无缝的跨设备身份验证（通过二维码和蓝牙）。例如，用户可以使用存储在智能手机上的 Passkey 登录桌面设备上的服务。此功能允许用户安全地进行身份验证，而无需为每台设备手动传输 Passkey 或依赖传统的登录方法，从而营造统一的身份验证体验。

平台[验证器]，如 [Windows Hello]、Face ID 或 Touch ID，直接内置于设备中，通过让用户使用生物识别或其他设备原生方法（如 PIN 码、图案）进行身份验证，提供更快、更流畅、更安全的 Passkey 体验。

Become part of our Passkeys Community for updates & support.

Join

userVerifyingPlatformAuthenticator 确保[Passkey 身份验证]涉及[用户验证]，例如主动的指纹扫描或面部识别，从而提供额外的安全层。

relatedOrigins 功能允许在同一组织拥有的不同域（例如 amazon.com 和 amazon.de）之间进行无缝身份验证。例如，如果一家公司管理多个域或拥有不同的子域，用户只需登录一次即可访问所有资产，而无需在每个资产上重新进行身份验证。此功能简化了用户体验，减少了摩擦，对于国际环境或拥有多服务平台的企业尤其有价值。

signalAllAcceptedCredentials(options) 方法提供给定用户的所有 [WebAuthn 凭证 ID] 的完整列表。当用户通过身份验证后，WebAuthn 信赖方应优先使用此方法而不是 signalUnknownCredential()，因为不存在隐私泄露的风险。此方法提供了用户公钥凭证的全面概览，包括任何可能尚未在当前连接的[验证器]上更新的近期更改。

我们来看一个例子。一个用户（userId: A）有两个 Passkey，其凭证 ID 经过 Base64URL 编码后分别为 X 和 Y。然后，该用户在网站（example.com）的账户设置中删除了 Passkey X（因此公钥被删除）。现在，运行以下代码片段：

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle, Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

如果在执行上述代码时[验证器]可用，那么[验证器]会从未来的身份验证仪式中删除或隐藏 Passkey X。但是，执行时[验证器]可能未连接，因此建议信赖方定期执行此代码，例如在每次登录时。

未出现在 allAcceptedCredentialIds 中的 Passkey 将被移除或隐藏，这可能是不可逆的。因此，信赖方必须注意，切勿从列表中移除有效的 WebAuthn 凭证 ID。如果不小心移除了一个有效的[凭证 ID]，[信赖方]应立即在另一次 signalAllAcceptedCredentials(options) 调用中包含它，以尽快“取消隐藏”该 Passkey。如果 Passkey 被移除而不是隐藏，那么就很难修复了。

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

signalCurrentUserDetails(options) 方法用于通知用户的当前名称和 WebAuthn 显示名称。当调用 signalCurrentUserDetails(options) 时，客户端会遵循一组定义的步骤来执行此操作。

我们来看一个例子。一个 WebAuthn [用户 ID]为 A 的用户在一个网站（example.com）的账户设置中更新了他们的名字。然后，[信赖方]可以运行以下代码：

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // user ID, Base64URL.
    name: "New user name",
    displayName: "New display name",
});

然后，[验证器]会更新本地保存的 Passkey 的元数据。最大的好处是，在未来的条件式 UI / [Passkey 自动填充]请求中，[条件式 UI]选择/下拉菜单会显示更新后的名称和 WebAuthn 显示名称。

signalUnknownCredential(options) 方法用于通知某个 WebAuthn [凭证 ID] 未被 WebAuthn 信赖方识别，例如，如果该 Passkey 已被用户删除。与 signalAllAcceptedCredentials(options) 不同，此方法不需要提供接受的凭证 ID 的完整列表和 WebAuthn [用户句柄]，从而防止对未经身份验证的调用者造成潜在的隐私泄露。

我们来看一个例子。一个用户在网站（example.com）的账户设置中删除了一个[凭证 ID]为 X 的 Passkey（因此公钥被删除）。但是，私钥仍然在用户的设备上可用。这意味着在未来的[条件式 UI] / [Passkey 自动填充]登录请求中（allowCredentials 列表为空），该 Passkey 仍然可以被选择。但登录尝试会失败，因为公钥已被删除，所以[信赖方]应运行：

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // credential ID the user just tried, Base64URL
});

然后，[验证器]会从未来的身份验证仪式中删除或隐藏[凭证 ID]为 X 的 Passkey。

由于 WebAuthn Level 3 标准仍处于草案状态，这些新客户端能力的采用尚未完全普及。不同的浏览器一直在逐步实现这些功能，但支持情况各不相同。以下是上述主要浏览器可用性的最新概览：

随着 Level 3 标准的成熟以及更多浏览器推出这些功能，采用速度可能会加快。如果你想了解当前有多少用户可以利用 getClientCapabilities()，可以使用免费的 [Passkeys Analyzer] 查看真实世界的数据。请密切关注浏览器发布说明和相关文档，以便随着其发展规划更广泛的兼容性。

Are your users passkey-ready?

Test Passkey-Readiness

作为开发者，我们可能会思考这些新的 WebAuthn 客户端能力检测意味着什么，以及应如何在应用中使用它们。下面是一些使用它们的建议。

但是请注意，并非所有浏览器都支持 getClientCapabilities() API 调用（截至 2024 年 11 月）。有一个可用的 polyfill [在这里]，可以在所有浏览器都跟上之前使用。

在代码中尽早使用 getClientCapabilities()，以便在页面加载或身份验证流程开始时检测客户端支持的功能。这将允许你动态地定制体验，并提供在设备/浏览器上可用的[Passkey 功能]，例如在支持平台身份验证时加以推广，或在不支持时提供替代方法（例如，短信一次性密码或[硬件安全密钥]）。

如果你要为一个当前使用密码的网站或应用添加 Passkey，conditionalCreate 功能可以极大地促进你的 [Passkey 采用率]。在后台，当使用合适的凭证管理器进行[密码自动填充]时（截至 2024 年 10 月，仅支持 [Apple Passwords]），会自动生成一个 Passkey，并在未来的自动填充中优先使用。

为了不仅获得高 [Passkey 采用率]，还要实现高 [Passkey 登录]使用率，请尝试通过检查 conditionalGet 来确定设备或浏览器是否能使用[条件式 UI] / [Passkey 自动填充]。这样，你将引导用户使用已创建的 Passkey 进行登录，因为操作系统/浏览器会主动建议它，并且比自动填充密码更省力。

利用 hybridTransport 实现跨设备身份验证（通过[二维码]和蓝牙），允许用户从他们的智能手机无缝登录，即使他们正在桌面设备上访问你的服务。

WebAuthn 客户端能力是填补当前 Passkey 差距方面迈出的重要一步。在这篇博客文章中，我们探讨了关于 WebAuthn 客户端能力的关键问题：

1. 什么是 WebAuthn 客户端能力？ 我们解释了这些功能如何允许浏览器和平台表明它们对特定功能的支持，从而让开发者对身份验证流程有更多的控制权。
2. 存在哪些 WebAuthn 客户端能力？ 我们概述了 Level 3 标准中引入的新能力，包括 getClientCapabilities、conditionalCreate、hybridTransport 等。
3. WebAuthn 客户端能力如何改进 Passkey 的实现？ 我们讨论了这些能力如何简化集成、增强跨设备使用并提高安全性。
4. 为什么 WebAuthn 客户端能力对开发者很重要？ 这些功能有助于创建符合现代用户期望的无缝、安全的身份验证体验，使实现过程更简单、更有效。

我们鼓励你探索新的 [WebAuthn Level 3] 功能，并持续关注它们在各浏览器中的采用情况。如果你希望实施 Passkey 并利用这些高级功能，[请联系我们以获取专业的指导和支持]。