源试用：WebAuthn 立即中介，实现顺畅登录

José Luis Zapata

发布时间：2025 年 8 月 19 日

WebAuthn 立即中介是一项新的 Web 功能，旨在简化用户登录流程。此源试用版概述了该功能、其优势和实现细节，并邀请您参与其中，帮助塑造 Web 身份验证的未来。

背景

Web 上的身份验证通常会带来摩擦，使登录流程变得复杂。 现有的 WebAuthn 流程虽然功能强大，但在处理“登录”按钮时却存在问题，尤其是在凭据无法立即使用时，会导致回退到标准表单。

这项新功能引入了顺畅的登录流程，类似于移动设备上的 preferImmediatelyAvailableCredentials API。它通过减少摩擦和提升用户体验，简化了登录流程（通常在标准登录表单之前）。

运作方式

WebAuthn 立即中介可实现更直接高效的登录体验。这样一来，浏览器可以立即提供可用的凭据，或者立即指示凭据不存在，而无需提示进行跨设备或安全密钥身份验证，从而简化了开发者的实现。

immediate 中介类型

我们将为 navigator.credentials.get() 请求引入 immediate 中介类型。如果设置了此选项，但未找到本地可用的凭据，则 Promise 会以 NotAllowedError 为参数拒绝。如果存在凭据，浏览器会像往常一样处理身份验证过程。

这种灵活性使网站能够调整其登录流程，在无法立即提供凭据时提供替代方法。

重要的是，浏览器仍然可以返回 NotAllowedError，以维护用户隐私和安全，防止出现指纹识别或跟踪等问题。

功能检测

您可以使用 PublicKeyCredential.getClientCapabilities() 检测即时中介是否可用。开发者可以检查返回的 capabilities 对象是否具有 immediateGet 功能。

async function checkImmediateMediationAvailability() {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    if (capabilities.immediateGet && window.PasswordCredential) {
      console.log("Immediate Mediation with passwords supported.");
    } else if (capabilities.immediateGet) {
      console.log("Immediate Mediation without passwords supported.");
    } else { console.log("Immediate Mediation unsupported."); }
  } catch (error) {
    console.error("Error getting client capabilities:", error);
  }
}

注意：为了帮助实现更广泛的浏览器支持，getClientCapabilities() 的填充区可从 WebAuthn Polyfills GitHub 代码库中获取。

实现示例

如需使用该 API，请使用 mediation: 'immediate' 调用 navigator.credentials.get()。我们建议在请求中包含 password: true，因为大多数用户现在可能都保存了密码，可以立即从这种体验中受益。

button.addEventListener('click', async (event) => {
  event.preventDefault();
  event.stopPropagation();
  const cred = await navigator.credentials.get({
    password: true,
    publicKey: {
      challenge, // Your server-generated challenge
      rpId: 'example.com' // Your Relying Party ID
    },
    mediation: 'immediate',
  });
});

开发者应在 catch 代码块中处理 NotAllowedError，以提供优雅的后备登录体验。

立即中介的分步流程

WebAuthn 立即中介支持两种主要使用情形，可简化用户登录流程：启用专用的“使用通行密钥登录”按钮，以抑制不需要的后备选项；以及促成动态登录流程，在用户执行关键操作之前主动提供凭据。

用例 1：使用登录按钮进行显式登录

此方案侧重于提供专用登录按钮，确保用户体验顺畅，不会出现意外提示或需要通过登录页面。

1. 用户发起登录：用户点击“登录”按钮。然后，信赖方会使用 mediation: "immediate" 调用 navigator.credentials.get()。
2. 浏览器提示选择凭据（如有）：浏览器会检查是否有任何本地可用的通行密钥或所请求的密码。如果找到任何账号，系统会立即显示一个模态界面，供用户选择账号。账号按上次使用时间戳排序，然后按字母顺序排序。 注意：如果为同一账号找到了多个密码管理工具中的密码和通行密钥，浏览器会优先使用通行密钥。如果同一账号有来自不同提供商的多个通行密钥，系统会优先使用上次使用的通行密钥。
3. 成功登录：用户从浏览器界面中选择通行密钥。如果浏览器需要验证，它会提示用户使用之前设置的方法（例如 PIN 码、生物识别输入或解锁图案）验证自己的身份。登录成功完成。
4. 回退路径：没有通行密钥或用户关闭了浏览器界面：如果网站没有本地通行密钥或请求的密码，或者用户关闭了浏览器界面，浏览器会向信赖方抛出 NotAllowedError，并且不会显示任何用于跨设备或安全密钥选项的界面。 然后，信赖方可以继续使用其标准登录页面或提供替代身份验证机制。

用例 2：用户操作之前的隐式登录流程

在此场景中，系统会在用户执行需要经过身份验证的操作（例如结账）之前主动提供通行密钥和密码，从而实现主动登录体验。

1. 用户发起需要登录的操作：用户点击某个按钮，以执行需要登录才能完成的操作（例如“结账”按钮）。然后，信赖方会使用 mediation: "immediate" 调用 navigator.credentials.get()。

2. 浏览器提示选择凭据（如果可用）：浏览器会检查是否有任何本地可用的通行密钥或密码。如果找到，系统会立即显示一个模态界面，供用户选择账号。账号按上次使用时间戳排序，然后按字母顺序排序，并进行去重处理，以便每个账号只显示一个条目。 注意：如果为同一账号找到了来自多个密码管理工具的密码和通行密钥，浏览器会优先使用通行密钥。如果同一账号有来自不同提供方的多个通行密钥，系统会优先使用上次使用的通行密钥。

3. 成功登录：用户从浏览器界面中选择凭据。如果浏览器需要验证，则会提示用户使用之前设置的方法（例如 PIN 码、生物识别输入或解锁图案）验证自己的身份。登录成功完成。

4. 回退路径：无凭据或用户关闭：如果网站没有本地凭据，或者用户关闭了浏览器界面，浏览器会向信赖方抛出 NotAllowedError，并且浏览器不会显示任何界面。用户的登录体验与目前相比保持不变。然后，信赖方可以向用户询问更多详细信息（例如电子邮件地址），或显示其他身份验证机制，例如密码表单、短信验证或支持跨设备身份验证器的 WebAuthn 模态请求。

优势

WebAuthn 立即中介功能为开发者和用户带来了多项关键优势：

• 顺畅的登录体验：如果用户有可立即使用的通行密钥或已在浏览器或密码管理器中保存密码，则可以获得更顺畅、更轻松的登录体验。
• 智能登录：当用户想要执行需要登录才能完成的活动时，该 API 会启用登录流程。这些按钮会根据用户的凭据状态智能调整。它会在可能的情况下立即进行身份验证，从而避免不必要的重定向并简化流程。
• 改进了凭据管理：当多个密码管理器为同一账号提供凭据时，浏览器会智能地选择最合适的选项，从而简化用户的凭据管理。
• 减少用户困惑：通过直接显示已知凭据，此功能可最大限度地减少用户在面对多个登录选项或标准表单时经常出现的困惑。
• 无缝回退：它可确保在用户没有即时凭据的情况下无缝回退到标准登录页面，这意味着他们的体验与当前流程保持不变。

隐私权和安全

借助 WebAuthn 立即中介，网站可以在用户明确授权登录尝试之前识别立即可用的凭据。为保护用户隐私并防止潜在的滥用行为，我们采取了多项关键措施：

• 用户手势要求：API 调用需要用户手势（任何暂时性用户激活）。这使得网站难以进行静默探测和指纹识别。
• 无痕会话和不公开会话：在无痕会话或不公开会话中，任何即时中介请求都会抛出 NotAllowedError。
• 对 allowCredentials 列表的限制：使用 allowCredentials 列表的请求会抛出 NotAllowedError。这可防止网站推断用户互动历史记录或跨会话跟踪用户。
• 取消：在采用即时中介的请求中设置 signal 参数是无效的。这样可防止网站以程序化方式关闭任何浏览器界面。

试试看

我们建议您尝试使用 WebAuthn 立即中介。

Chrome 中的状态

此功能正在经历 Chromium 开发周期：

• 桌面设备：Chrome 136 中的开发者试用，Chrome 139 至 141 中的源试用。
• Android：Chrome 140 中的开发者试用。

对于本地测试

如需在本地测试 WebAuthn 立即中介，请执行以下操作：

1. 下载 Chrome 139：在桌面设备上获取并打开最新版本的 Chrome。
2. 启用“立即中介”标志：在地址栏中前往 chrome://flags/#web-authentication-immediate-get，然后启用“Web 身份验证立即获取”标志。
3. 准备凭据：确保您已保存可用的通行密钥和密码：
   • 保存在 Google 密码管理工具中的密码。
   • 保存在 Google 密码管理工具（需要登录 Google 账号并将 Chrome 与该账号同步）、Windows Hello 或 iCloud 钥匙串中的通行密钥。

对于公开测试（源试用）

如需在公开环境中通过源试用测试 WebAuthn 立即中介，请执行以下操作：

1. 注册：访问 Chrome 源试用页面，然后注册“WebAuthn 立即中介”试用。
2. 将令牌添加到 HTTP 标头：在网站的 HTTP 标头中添加提供的源试用令牌： HTML Origin-Trial: [YOUR_TRIAL_TOKEN]

注意：您还可以使用 JavaScript 以编程方式提供令牌。

测试场景

我们提供了一个参考实现，并建议您构建自己的原型来测试各种场景。

• 参考演示：您可以访问 https://deephand.github.io/webauthn-immediate-demo/ 试用参考实现。
  • 实现原型：在网站上实现原型时，请确保在用户点击（例如“登录”按钮或任何需要用户登录的互动）后，使用 mediation: 'immediate' 进行 navigator.credentials.get() 调用。
• 流程 1：不使用密码或通行密钥登录：如果您没有可用于相应网站的通行密钥或密码，点击“登录”会直接进入标准登录页面，而不会显示浏览器界面。
• 流程 2：使用可立即使用的本地通行密钥登录：如果您已为相应网站保存通行密钥，点击“登录”应会触发“立即中介”界面，并提供通行密钥供您选择。
• 流程 3：使用本地通行密钥或密码登录：如果您同时保存了通行密钥和密码，请启用“请求密码”选项（通过在代码中设置 password: true）。点击“登录”后，立即中介界面应同时提供通行密钥和密码选项。