WebAuthn 公钥凭证提示 / User-Agent 提示

WebAuthn 和 Passkey 的发展势头正劲，应用也越来越广泛。同时，从技术角度来看，WebAuthn 标准也在快速演进。**WebAuthn 公钥凭证提示（也称为 User-agent 提示）**是 Web Authentication API 的最新成员，旨在改进开发者在其应用中实现 Passkey 身份验证的方式。

在本文中，我们将回答以下问题：

• 什么是 WebAuthn 公钥凭证提示？
• 为什么需要 WebAuthn 公钥凭证提示？
• WebAuthn 公钥凭证提示如何工作？
• 在您的项目中，WebAuthn 公钥凭证提示有哪些限制和推荐的使用场景？

让我们先从其背后的动机开始看起。

如今，我们可以在不同地方创建和存储 Passkey：

• 第三方密码管理器（例如 1Password、Dashlane、Bitwarden、KeePassXC）
• Google 密码管理器 / Chrome 个人资料
• iCloud 钥匙串 / Apple 密码
• Windows Hello
• 另一台智能手机（iOS、Android）或平板电脑（iPadOS、Android）
• 硬件安全密钥（例如 YubiKey）

对用户来说，这提供了灵活性和选择的自由。然而，在某些应用和场景中，需要限制部分选项，例如，如果出于更高的安全要求，您希望只允许使用硬件安全密钥。

为了影响 Passkey 的创建和存储位置，我们之前有 authenticatorAttachment 属性。

Subscribe to our Passkeys Substack for the latest news.

Subscribe

authenticatorAttachment 允许信赖方限制 Passkey 可以在何处创建。

platform 表示一个内置于运行 WebAuthn 设备中的验证器。WebAuthn 使用特定于该平台的传输方法（如平台特定的 API）与其通信。与平台验证器关联的公钥凭证称为平台凭证。在上面的列表中，以下凭证管理器/位置可以存储平台凭证：

• 第三方密码管理器（例如 1Password、Dashlane、Bitwarden、KeePassXC）
• Google 密码管理器 / Chrome 个人资料
• iCloud 钥匙串 / Apple 密码
• Windows Hello

Windows 11 和 Chrome：

macOS 15 (Sequoia) 和 Chrome：

点击“取消”后，会出现以下弹窗：

macOS 15 (Sequoia) 和 Safari：

cross-platform 表示一个独立于运行 WebAuthn 设备之外的验证器（漫游验证器），因为它可以在多个设备上使用。WebAuthn 通过蓝牙或 NFC 等跨平台传输协议与其交互。与漫游验证器关联的公钥凭证称为漫游凭证。在上面的列表中，以下凭证管理器/位置可以存储跨平台凭证：

• 另一台智能手机（iOS、Android）或平板电脑（iPadOS、Android）
• 硬件安全密钥（例如 YubiKey）

Windows 11 和 Chrome：

macOS 15 (Sequoia) 和 Chrome：

macOS 15 (Sequoia) 和 Safari：

未指定表示可以使用平台验证器或跨平台验证器。此时，用户可以选择他们希望在哪里存储 Passkey。

Windows 11 和 Chrome：

macOS 15 (Sequoia) 和 Chrome：

macOS 15 (Sequoia) 和 Safari：

点击“取消”后，会出现以下弹窗：

authenticatorAttachment 已经使用了一段时间。然而，在面对跨设备验证（通过二维码和蓝牙）等新技术发展时，它也显得不够灵活。在这种情况下，Passkey 也可能存储在Google 密码管理器中（平台凭证），但由信赖方使用 cross-platform 触发。除此之外，信赖方在登录（而非注册）流程中影响应使用哪种 Passkey 的控制，只能通过修改凭证的 transports 值来实现。

这就是 WebAuthn 公钥凭证提示发挥作用的地方。

Become part of our Passkeys Community for updates & support.

Join

WebAuthn 公钥凭证提示是 Web Authentication API（在 WebAuthn Level 3 中正式引入）中新增的一个参数。它们为浏览器提供指导，告知用户在身份验证过程中可能使用哪种类型的验证器。这有助于通过将浏览器的用户界面聚焦于最相关的选项，从而提供更流畅、更直观的用户体验。

三种提示类型

提示分为三种类型：

1. security-key：表示用户预计会使用硬件安全密钥（例如 YubiKey）。
2. client-device：建议用户将使用附加到客户端设备的平台验证器（如 macOS 上的 Touch ID、iOS 上的 Face ID 或 Windows 上的 Windows Hello）。
3. hybrid：暗示用户可能会使用智能手机或平板电脑通过二维码和蓝牙进行跨设备身份验证。

这些提示并非信赖方的严格要求，而是作为指导，旨在通过向浏览器提供提示来增强用户体验。

下面您将看到在 macOS Sequoia (Edge + Chrome) 和 Windows 10 (Chrome) 上的截图，其中 authenticatorAttachment 未指定，而 WebAuthn User-agent 提示设置为 security-key。

在这里，我们看到了另一个限制，即 security-key 提示在 Windows 10 上没有被遵循，至少不是直接遵循。其流程与 client-device 提示基本相同。

点击“取消”后，会出现以下弹窗：

下面您将看到在 macOS Sequoia (Edge + Chrome) 和 Windows 10 (Chrome) 上的截图，其中 authenticatorAttachment 未指定，而 WebAuthn User-agent 提示设置为 client-device。

点击“取消”后，会出现以下弹窗：

点击“取消”后，会出现以下弹窗：

点击“取消”后，会出现以下弹窗：

下面您将看到在 macOS Sequoia (Edge + Chrome) 和 Windows 10 (Chrome) 上的截图，其中 authenticatorAttachment 未指定，而 WebAuthn User-agent 提示设置为 hybrid。

随着提示的引入，开发者现在可以按优先级降序提供一个偏好数组，从而提供更大的灵活性。

下面的代码片段告诉浏览器，用户很可能会使用硬件安全密钥进行身份验证，从而相应地聚焦用户界面。

为了与旧版 User-agent 兼容，在 PublicKeyCredentialCreationOptions 中使用此提示时，authenticatorAttachment 应设置为 cross-platform。

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

在网站/信赖方只想允许使用硬件安全密钥并引导用户朝这个方向发展的高保障场景中，security 提示尤其有价值。

在此示例中，提示建议用户可能会使用当前设备的内置平台验证器。

为了与旧版 User-agent 兼容，在 PublicKeyCredentialCreationOptions 中使用此提示时，authenticatorAttachment 应设置为 platform。

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['client-device'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    }
  }
});

如果一个用户账户关联了多个 Passkey，其中一些可能在正在登录的设备上可用，而另一些则存储在其他设备上，那么设置 client-device 提示会很有帮助。如果系统（Passkey 智能分析）检测到尝试登录的用户很有可能在本地拥有可用的 Passkey，那么可以在 PublicKeyCredentialRequestOptions 中设置此提示，从而为用户省去一次选择正确 Passkey 的点击。

在此示例中，提示建议用户可能会使用智能手机或类似设备进行身份验证。

为了与旧版 User-agent 兼容，在 PublicKeyCredentialCreationOptions 中使用此提示时，authenticatorAttachment 应设置为 cross-platform。

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

如果用户拥有多个密钥，并且系统（Passkey 智能分析）检测到当前设备上可能没有可用的本地 Passkey，hybrid 提示会很有帮助。为了改善用户体验并节省一次点击，您可以设置此 WebAuthn User-agent 提示，并直接提示用户进行跨设备身份验证（通过二维码和蓝牙）。此外，如果您尝试构建一个移动优先的 Passkey 系统，那么设置此提示非常有意义。

要亲自尝试不同的选项，我们建议您查看 Passkeys Debugger。

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

Try for Free

理解 WebAuthn 公钥凭证提示如何与 authenticatorAttachment 和 credential transports 等其他 WebAuthn 参数交互至关重要。

首先，需要注意的是，这些提示并非严格要求。它们不会强制约束 User-agent（浏览器），而是作为指导，利用您拥有的关于请求的上下文信息来提供最佳体验。这意味着浏览器可以选择考虑这些提示，但没有义务严格遵守它们。

提示以数组形式提供，按优先级降序排列。这个顺序决定了浏览器应如何优先处理它们：

• 第一个提示优先：如果两个提示相互矛盾，浏览器会优先考虑第一个。
• 重叠的提示：如果一个更具体的提示可能不被所有浏览器识别，您可以在其后包含一些不太具体的提示，以获得更广泛的兼容性。
• 重复的提示：如果同一个提示出现多次，任何后续的出现都将被忽略。

示例：

hints: ['security-key', 'hybrid', 'client-device']

在这个数组中：

1. 浏览器首先优先考虑 security-key。
2. 如果不适用，则考虑 hybrid。
3. 最后，它会考虑 client-device（客户端设备上的平台验证器）。

提示可能与 authenticatorAttachment 和 credential transports 中包含的信息相矛盾。当这种情况发生时，提示的优先级更高。与之前严格使用 authenticatorAttachment（将验证器限制为 platform 或 cross-platform）相比，这提供了更大的灵活性。

参数矛盾的示例：

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform' // 与提示矛盾
    }
  }
});

在这种情况下：

• 提示：建议优先使用 hybrid 验证器。
• authenticatorAttachment：指定 platform，这通常将验证器限制在客户端设备上。
• 结果：浏览器会优先考虑提示而不是 authenticatorAttachment，从而聚焦于 hybrid 选项。

目前，WebAuthn 公钥凭证提示仅在 **Chrome（自 128 版本起）**中可用。截至目前，Edge 和 Safari 已表示计划集成此功能，而 Firefox 尚未确认其发布时间表。

需要记住的是，在 Chrome 中，authenticatorAttachment 参数目前仍然受到尊重。这意味着，目前 authenticatorAttachment 是决定性因素，无论设置了哪个提示。然而，我们预计在未来的 Chrome 版本中，公钥凭证提示将成为首选且唯一的处理方式。

尽管最新的 Chrome 版本支持 WebAuthn User-agent 提示，但这些提示并未被 Windows 11 和 Windows Hello / Windows 安全中心所遵循。根本原因在于用户界面是由操作系统（Windows Hello / Windows 安全中心）本身控制的。

此外，对于存储在 Google 密码管理器并同步到 Windows 11 的 Passkey，WebAuthn User-agent 提示也不被遵循，因为在 Windows 11 上的最终本地身份验证是通过 Windows Hello / Windows 安全中心完成的。随着即将通过 Microsoft 账户在 Windows 11 上同步 Passkey，我们也期待 Windows 11 和 WebAuthn User-agent 提示方面会有所改进。

然而，在 Windows 10 上，WebAuthn User-agent 提示是受到尊重的，因为 WebAuthn 用户界面是由 Chrome 而非 Windows Hello / Windows 安全中心处理的。但在我们的测试中，我们没有看到 security-key 的效果。当设置此提示时，其流程看起来与 client-device 的流程相似。

WebAuthn 公钥凭证（User-agent）提示为开发者和用户带来了一系列好处。该功能仍然很新，尚未推广到所有浏览器和操作系统（截至 2024 年 10 月）。

重要的是要意识到当前的限制，尤其是在 Windows 11 上。在 Windows 11 中，Passkey 用户界面由 Windows Hello（Windows Hello 安全弹窗）处理，这目前优先于 Chrome / Edge 对 WebAuthn User-agent 提示的支持。这也适用于从 Google 密码管理器同步到 Windows 的 Passkey（在这里，提示也尚无效果）。

这意味着 WebAuthn 公钥凭证提示真正起作用的仅限于 macOS 和 Windows 10（在主流桌面操作系统中）。

此外，截至 2024 年 10 月，即使在这些操作系统上使用 Chrome / Edge，如果设置了 authenticatorAttachment，它也会优先于 WebAuthn User-agent 提示（正如 Google 所述）。

从用例的角度来看，我们认为以下推荐用例可以最大化地发挥这项新功能的价值。

在构建您的后端和 Passkey 智能分析时，尝试正确使用公钥凭证提示，以简化登录过程并为用户节省不必要的点击。例如，如果您的系统检测到用户在可能拥有本地 Passkey 的设备上登录，请使用 client-device 提示。

如果用户从新设备访问网站，而您的Passkey 智能分析知道用户的移动设备上可能有可用的 Passkey，请将提示设置为 hybrid，这样用户就可以快速扫描二维码并使用混合式 Passkey。

这里的主要目标是提供更无缝、更直观的用户体验。通过指导浏览器哪些验证器可能被使用，开发者可以减少用户在登录过程中的困惑和摩擦。用户不会被不必要的身份验证选项所淹没，而是让浏览器专注于最相关的选择，从而带来更快、更直接的体验。

对于已经标准化使用硬件安全密钥进行用户身份验证的高保障企业或政府机构来说，Passkey 凭证提示尤其有用。通过使用 security-key 提示，他们可以确保浏览器突出显示硬件安全密钥选项。

这对于已经为员工发放硬件安全密钥且不允许使用其他身份验证方法（如平台验证器）的大型组织尤其有用。security-key 提示使企业能够锁定其身份验证流程，同时又不限制其未来改进的灵活性。

在需要跨设备身份验证并因此采用移动优先方法的场景中，或者当用户频繁在设备或平台之间切换时，hybrid 提示大放异彩。

这种用例的一个例子是面向消费者的应用程序，它预计大多数用户会使用智能手机进行身份验证，无论是通过生物识别方法还是基于 Web 的验证器应用（移动优先 Passkey）。通过将 hybrid 指定为提示，开发者可以确保浏览器的用户界面鼓励使用智能手机，从而提高便利性和可访问性。

WebAuthn 公钥凭证提示提供了一种灵活的方式来增强 Passkey 身份验证期间的用户体验。让我们用我们收集到的见解重新审视引言中的问题：

1. 什么是 WebAuthn 公钥凭证提示？

   它们是网站/应用提供的可选建议，用于指导客户端用户最可能使用的身份验证方法——无论是硬件安全密钥、平台验证器，还是像跨设备身份验证这样的混合解决方案。

2. 为什么需要 WebAuthn 公钥凭证提示？

   它们通过缩小呈现给用户的选项范围，减少不必要的摩擦/点击，并改善整体体验，从而简化了身份验证过程。

3. WebAuthn 公钥凭证提示如何工作？

   开发者根据上下文指定 security-key、client-device 或 hybrid 等提示，允许浏览器为用户优先考虑相关的身份验证方法。虽然这些提示并非严格要求，但它们有助于在身份验证期间优化用户界面流程。

4. 有哪些限制和推荐的用例？

   目前，对这些提示的完全支持仅限于 Chrome 和 Edge，而其他浏览器和操作系统（如 Windows 11）的兼容性水平各不相同。最有效的用例包括改善登录用户体验、在高安全环境中强制使用硬件安全密钥，以及在移动优先的应用中启用跨设备身份验证。

总之，WebAuthn 公钥凭证提示允许开发者通过引导浏览器为每个用户场景提供最合适的选项，从而创建更直观、更友好的身份验证流程。虽然仍在发展中，但这一功能可以显著提升 Passkey 实现中的安全性与用户体验。