WebAuthn 条件 UI（通行密钥自动填充）技术详解

Q: 在开始通行密钥自动填充流程之前，如何检查浏览器是否支持条件 UI？

调用 `PublicKeyCredential.isConditionalMediationAvailable()` 并且仅在返回 true 时继续。这种检查可以防止在不支持的浏览器和设备组合上出现用户可见的错误。应在每次页面加载时，在调用带有 `mediation: "conditional"` 的 `navigator.credentials.get()` 之前对该方法进行评估。

Q: 当用户切换到模式通行密钥登录时，如何取消正在进行的条件 UI 请求？

创建一个全局作用域的 `AbortController`，并将其 signal 传递给 `navigator.credentials.get()`。当用户启动模式登录流程时，调用控制器上的 `.abort()`。每次条件 UI 重新启动时都必须实例化一个新的 `AbortController`，因为重复使用已中止的控制器会导致 WebAuthn 请求立即取消。

Passkeys 速查表. 面向 passkey 项目的实用指南、推广模式和 KPI。

获取速查表

关键事实

条件 UI 需要可发现凭据（常驻密钥）：身份验证器不会为非常驻密钥存储用户特定数据，这使得它们无法进行自动填充。
在启动任何条件 UI 流程之前必须调用 isConditionalMediationAvailable()，以防止在不支持的浏览器或设备上出现用户可见的错误。
HTML 输入字段上的 autocomplete="username webauthn" 令牌向浏览器发出信号，在自动填充下拉列表中将通行密钥与密码建议一起显示。
在 navigator.credentials.get() 调用中设置 mediation: "conditional" 会激活通行密钥自动填充，而不会用阻塞式模式对话框打断用户。
取消正在进行的条件 UI 请求需要一个 AbortController，因为自动填充下拉列表与模式提示不同，没有内置的取消按钮。

1. 引言#

随着通行密钥（以及底层的 WebAuthn 协议）的快速普及，对许多用户来说，身份验证变得更加安全和友好。通行密钥最突出的进步之一是集成了条件 UI（Conditional UI），通常被称为“通行密钥自动填充（passkey autofill）”或条件中介（Conditional Mediation）（在下文中我们将继续使用条件 UI 这个术语）。

尽管它最近才被引入并且浏览器正在不断采用，但在条件 UI 的技术文档和实现建议方面存在明显的空白。本文旨在通过解释什么是条件 UI、它是如何工作的以及如何解决其实现过程中的常见挑战，来弥补这一空白。

条件 UI 代表了通行密钥 / WebAuthn 登录过程的一种新模式。它只在用户拥有存储在其设备（如笔记本电脑、智能手机）的身份验证器中且在该依赖方（在线服务）注册的可发现凭据（常驻密钥，通行密钥的一种）时，才有选择地在用户界面 (UI) 中显示通行密钥。通行密钥显示在一个与自动填充密码混合的选择下拉列表中，提供了传统密码系统和高级通行密钥身份验证之间的无缝过渡，因为用户在相同的上下文中看到两者。这种智能的方法确保用户不会被不必要的选项淹没，并且可以更顺畅地浏览登录过程。

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

条件 UI 的基础建立在三大支柱之上：

尊重用户隐私：通过防止披露可用凭据或未经用户同意就泄露这些凭据，确保用户隐私。
即使没有通行密钥也能提供良好的用户体验：使依赖方能够机会性地实现 WebAuthn，确保即使无法使用通行密钥，用户体验也保持良好。
从密码到通行密钥的平滑过渡：将通行密钥与基于密码的身份验证相结合，以平滑地向无密码身份验证方法过渡，充分利用用户熟悉的 UX 范例。

3. 条件 UI 的优缺点#

3.1 优点#

简化的身份验证：该过程更加精简和高效，消除了通常与多种身份验证方法相关的复杂性。
减少用户错误：通过仅提供相关选项，用户在身份验证过程中犯错的可能性更小。
提升用户满意度：消除不必要的步骤意味着用户可以更快、更轻松地登录，从而提高用户满意度。
简单的前端集成：条件 UI 最突出的特点之一是其易于集成。开发人员只需几行代码就可以将其无缝合并到前端（见下文）。
无密码和无用户名登录：巨大的好处之一是条件 UI 不仅促进了无密码身份验证，还促进了无用户名或无账户体验。用户无需承担回忆其特定电子邮件地址或注册时用户名的精神负担。相反，他们可以依赖浏览器的建议，这些建议在自动填充菜单中包含了与适当通行密钥配对的电子邮件地址/用户名。
解决引导困境：从传统的用户名-密码系统过渡到通行密钥可能会令人生畏。条件 UI 解决了这个过渡挑战。如果设备缺乏所需的凭据，网站可以启动通行密钥 / WebAuthn 调用以及常规密码提示，而无需担心潜在的模式对话框错误。

订阅我们的 Passkeys Substack，获取最新消息。

3.2 缺点#

开发人员的学习曲线：条件 UI 引入了一种新范式，这意味着对于不熟悉其复杂性的开发人员来说存在学习曲线。
设备/浏览器依赖性：条件 UI 的成功取决于用户的设备或浏览器兼容性。鉴于目前并非所有浏览器或设备都支持它，这可能会限制其应用。
密码管理器禁用自动完成：一些现代密码管理器及其浏览器扩展会修改网站的 DOM，并禁用或覆盖输入字段中的 autocomplete 标签，以支持它们自己的自动完成功能。这可能会导致不一致和不令人满意的用户体验。由于条件 UI 的标准相对较新，我们希望情况会有所改善，例如，不会叠加两个自动填充菜单或不显示所需的菜单。

4. 条件 UI 是如何工作的？#

下面，我们将逐步分析整个条件 UI 流程的各个步骤：

通常，条件 UI 的流程可以分为两个阶段。在页面加载阶段，条件 UI 逻辑在后台进行，而在用户操作阶段，用户必须主动执行某些操作。

条件 UI 可用性检查：客户端（浏览器）调用 isConditionalMediationAvailable() 函数来检测当前的浏览器/设备组合是否支持条件 UI。只有当响应为 true 时，进程才会继续，否则条件 UI 进程将被中止。
调用条件 UI 端点：接下来，客户端调用服务器的条件 UI 端点，以获取 PublicKeyCredentialRequestOptions。
接收 PublicKeyCredentialRequestOptions：服务器返回包含 challenge 和更多 WebAuthn 服务器选项（例如 allowCredentials、extensions、userVerification）的 PublicKeyCredentialRequestOptions。
启动本地身份验证：通过调用带有接收到的 PublicKeyCredentialRequestOptions 且将 mediation 属性设置为 conditional 的 credentials.get()，设备上本地身份验证的进程开始。
显示自动填充选择：弹出通行密钥的自动填充菜单。具体的样式取决于浏览器和设备（例如，有些要求用户将光标放在输入字段中，有些则在页面加载时自动显示菜单，见下文）。
本地用户身份验证：用户从自动填充菜单中选择他们要使用的通行密钥，并通过其设备的身份验证对话框（例如，通过 Face ID、Touch ID、Windows Hello）进行身份验证。
向服务器发送身份验证器响应：如果本地用户身份验证成功，则将身份验证器响应发送回服务器。
用户已登录并被重定向：一旦服务器收到身份验证器响应，它就会根据数据库中对应用户帐户的公钥验证签名。如果验证成功，用户将被授予访问权限、登录并重定向到登录后页面。

通过遵循此流程，条件 UI 提供了无缝且用户友好的身份验证体验。

5. 条件 UI 的技术要求#

5.1 一般要求#

为了使条件 UI 正常工作，需要考虑一些一般方面：

凭据规范：条件 UI 专门设计为仅与常驻密钥 / 可发现凭据配合使用。其背后的原因是，身份验证器不会为非常驻密钥 / 不可发现凭据存储用户特定数据（例如，姓名、显示名称）。因此，无法将后者用于通行密钥自动填充。
凭据过滤：allowCredentials 功能仍然受支持，有助于已经知道用户身份的网站（例如，如果在初始中介调用中发送了用户名，因为它可能存储在浏览器的 LocalStorage 中）来细化在自动填充期间向用户展示的凭据列表。

加入我们的 Passkeys Community，获取更新和支持。

加入

5.2 客户端#

为了使条件 UI 在客户端工作，必须满足以下要求：

兼容的浏览器：确保用户使用支持条件 UI 的现代浏览器（有关最新浏览器覆盖范围，请参见此处）。
启用 JavaScript：必须启用 JavaScript 以促进条件 UI 操作。
测试条件 UI 可用性：当依赖方（服务器端）收到 WebAuthn 中介调用时，应确定条件 UI 在客户端是可用的，避免在不支持条件 UI 的情况下触发任何用户可见的错误。为了解决这个问题，建议使用 isConditionalMediationAvailable() 方法并检查条件 UI 的技术可用性（有关更多详细信息，请参见下文）。
需要 HTML 输入字段：要使条件 UI 工作，你的网页中需要有一个 HTML 输入字段。如果没有，你需要提供对常规通行密钥 / WebAuthn 登录过程的支持，该过程由用户交互（如按钮点击）触发。
移除超时协议：在这种设置下，应忽略超时参数（例如，用户在自动填充菜单中决定使用通行密钥的时间非常长）。

5.3 服务器端#

为了使条件 UI 正常工作，服务器端也必须满足一些要求：

运行 WebAuthn 服务器：由于我们仍处于通行密钥 / WebAuthn 的上下文中，因此需要运行一个管理身份验证过程的 WebAuthn 服务器。
提供中介启动端点：与常规的 WebAuthn 登录端点相比，提供另一个功能类似但可以处理可选用户句柄（例如，电子邮件地址、电话号码、用户名）的端点是有用的。

6. 实用编码技巧#

自 2022 年底条件 UI 的正式推出和早期的测试版以来，我们一直在广泛地测试和使用它。下面，我们将与你分享在实现条件 UI 期间有所帮助的实用技巧。

在 Passkeys Debugger 中体验 passkey 流程。

免费试用

6.1 完整的条件 UI 示例#

条件 UI 方法的完整、极简的代码示例如下所示：

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Conditional UI</title>
    </head>
    <body>
        <input type="text" id="username" autocomplete="username webauthn" />
 
        <script>
            async function passkeyLogin() {
                try {
                    // retrieve the request options (incl. the challenge) from the WebAuthn server
                    let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
                    const credential = await navigator.credentials.get({
                        publicKey: options.publicKeyCredentialRequestOptions,
                        mediation: "conditional",
                    });
 
                    const userData = await WebAuthnClient.sendSignedChallenge(credential);
                    window.location.href = "/logged-in";
                } catch (error) {
                    console.log(error);
                }
            }
 
            passkeyLogin();
        </script>
    </body>
</html>

6.2 浏览器兼容性检查#

实现条件 UI 检测，以确保条件 UI 仅在当前设备/浏览器组合支持时才被使用。这应该在缺乏条件 UI 支持的情况下不会呈现用户可见的错误。在用户界面中合并 isConditionalMediationAvailable() 方法可以解决这个问题。如果支持条件 UI，则可以启动条件 UI 登录过程。

// source: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable#examples
 
// Availability of `window.PublicKeyCredential` means WebAuthn is usable.
if (window.PublicKeyCredential && PublicKeyCredential.isConditionalMediationAvailable) {
    // Check if conditional mediation is available.
    const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
    if (isCMA) {
        // Call WebAuthn authentication start endpoint
 
        let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
        const credential = await navigator.credentials.get({
            publicKey: options.publicKeyCredentialRequestOptions,
            mediation: "conditional",
        });
        /*
        ...
        */
    }
}

6.3 输入字段中的 WebAuthn Autocomplete 令牌#

输入字段应该接收一个 webauthn HTML 自动填充令牌。这向客户端发出信号，将通行密钥填充到正在进行的请求中。除了通行密钥，还可能展示其他自动填充值。这些自动填充令牌可以与其他现有令牌配对，例如：

autocomplete="username webauthn"：除了显示通行密钥外，还会建议用户名自动填充。
autocomplete="current-password webauthn"：除了显示通行密钥外，还会进一步提示密码自动填充。

<label for="name">Username:</label>
<input type="text" name="name" autocomplete="username webauthn" />
<label for="password">Password:</label>
<input type="password" name="password" autocomplete="current-password webauthn" />

了解更多细节，我们建议阅读此博客文章，其中提供了有关通行密钥和密码的自动填充 / 自动完成令牌的更多详细信息。

6.4 WebAuthn API Get 调用中的 Mediation 属性#

要在收到 PublicKeyCredentialRequestOptions 对象后检索可用的通行密钥，应调用 navigator.credentials.get() 函数（它同时提供通行密钥和密码）。PublicKeyCredentialRequestOptions 对象需要将 mediation 参数设置为 conditional 以激活客户端上的条件 UI。对于你想要一个模式通行密钥提示的情况，请参见 immediate mediation。

const credential = await navigator.credentials.get({
    publicKey: options.publicKeyCredentialRequestOptions,
    mediation: "conditional",
});

6.5 取消条件 UI 流程#

如果没有可用的通行密钥，或者用户忽略了建议的通行密钥并输入了他们的电子邮件，则条件 UI 流程将停止。这强调了始终通过模式对话框支持标准通行密钥 / WebAuthn 登录的重要性。

在这里需要强调的一个关键点是停止正在进行的条件 UI 请求的潜在需求。与模式体验相反，自动填充下拉列表缺少取消按钮。根据 WebAuthn 的设计，在任何给定时刻只能有一个活动的凭据请求正在进行中。WebAuthn 标准建议使用 AbortController来取消 WebAuthn 过程，这适用于常规和条件 UI 登录过程（有关详细信息，请参见此处）。

在生产遥测中，这种取消路径通常是预期的控制流结果，而不是系统故障。如果你看到大量的错误，在将它们视为回归之前，你需要根据操作类型和时间对预期与意外情况进行分类（参见 WebAuthn 错误）。

一旦用户登陆页面，条件 UI 登录过程就会被激活。首要任务应该是创建一个全局范围的 AbortController 对象。这将作为你的客户端终止自动填充请求的信号，特别是如果用户决定执行常规通行密钥登录过程的话。请确保其他函数可以调用 AbortController，并在必须重新启动条件 UI 过程时将其重置。在 navigator.credentials.get() 调用中使用 signal 属性，合并你的 AbortController 信号作为其值。这向通行密钥 / WebAuthn 函数发出信号，如果信号被中止，必须停止该请求。切记每次触发条件 UI 时都要设置一个新的 AbortController。使用已经中止的 AbortController 将导致通行密钥 / WebAuthn 函数立即取消。其余步骤与常规通行密钥登录过程一致。在下面，你将看到所提到步骤的代码示例：

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Conditional UI</title>
    </head>
    <body>
        <input type="text" id="username" autocomplete="username webauthn" />
 
        <script>
            async function passkeyLogin() {
                try {
                    // retrieve the request options (incl. the challenge) from the WebAuthn server
                    let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
                    const credential = await navigator.credentials.get({
                        publicKey: options.publicKeyCredentialRequestOptions,
                        mediation: "conditional",
                    });
 
                    const userData = await WebAuthnClient.sendSignedChallenge(credential);
                    window.location.href = "/logged-in";
                } catch (error) {
                    console.log(error);
                }
            }
 
            passkeyLogin();
        </script>
    </body>
</html>

在缺乏条件 UI 支持的情况下，引导用户进行常规通行密钥登录过程。为依赖硬件安全密钥（例如 YubiKeys）的用户或由于身份验证器限制而被迫使用非常驻密钥 / 不可发现凭据的用户提供此路径非常重要。

查看实际有多少人在使用 passkeys。

查看采用数据

6.6 本机应用中的条件 UI#

当你开发原生应用程序（例如针对 iOS 或 Android）时，条件 UI 也能工作。无论你是使用 Flutter、Kotlin 还是 Swift 进行原生开发，或者如果你决定采用 Chrome Custom Tabs (CCT) 或 SFSafariViewController 或 SFAuthenticationSession / ASWebAuthenticationSession，都没关系。两种方法都支持条件 UI。

6.6.1 iOS 应用中的条件 UI#

通常，我们几乎没有找到有关如何为 iOS 应用添加条件 UI 支持的文档。然而，在我们的研究过程中，我们发现了向 iOS 应用添加条件 UI 支持的两种方式，因为用户体验也会有所不同。

类型 A：覆盖几乎整个屏幕的叠加层 / 弹出窗口

第一种类型 A 会显示一个跨越几乎整个屏幕的叠加层 / 弹出窗口。在这里，你将看到该依赖方的所有可用通行密钥。以这种方式实现条件 UI 的一个著名例子是 KAYAK。当用户打开正确的屏幕时，会自动弹出叠加层 / 弹出窗口。

类型 B：键盘自动填充

第二种类型 B 会在键盘的自动填充部分（这里通常也会建议自动填充密码）显示一个合适的通行密钥。点击建议的值将执行 Face ID 身份验证并让你登录。在 Corbado 开发者面板目前的 iOS 应用程序版本中，我们是以这种方式实现的（参见带有 WebAuthn 用户名的针对 <relying party ID> 消息使用通行密钥登录的提示）。要显示出来，用户需要点击进入输入字段：

当全新安装 iOS 时，键盘部分的通行密钥自动填充功能可能会出现问题，因为显然在后台进行了一些缓存操作，用于查找该依赖方的所有可用通行密钥。

点击建议通行密钥右侧的钥匙图标将进入 iOS 中众所周知的选择密码/通行密钥页面：

请注意，我们尚未找到官方文档，我们的见解基于我们的经验和假设，而不是具体证明的适当实现。

6.6.2 Android 应用中的条件 UI#

在 Android 系统中，关于条件 UI 的说明要清楚得多，因为只有一种利用 Android Credential Manager API（请参阅此处的文档）进行条件 UI / 通行密钥自动填充的类型。由于 Android 的提供商可能有所不同，请将 Credential Manager 通行密钥错误与纯浏览器的 WebAuthn 失败模式分开监控。

打开实现条件 UI 的页面会显示以下屏幕，在这里你可以找到不同的登录方式：

点击**更多保存的登录信息（More saved sign-ins）**将提供更多登录选项供选择（包括跨设备身份验证以及选择其他通行密钥同步平台，例如 Samsung Pass 或 1Password）：

7. 不同设备/浏览器中的条件 UI 示例#

为了说明条件 UI 在最终用户面前的样子，我们添加了几张使用 https://passkeys.eu 的条件 UI 自动填充菜单截图。

在实时 demo 中试用 passkeys。

试用 passkeys

7.1 Windows 11 (22H2) + Chrome 118 中的条件 UI#

7.2 macOS Ventura (13.5.1) + Chrome 118 中的条件 UI#

7.3 macOS Ventura (13.5.1) + Safari 16.6 中的条件 UI#

7.4 Android 13 + Chrome 118 中的条件 UI#

7.5 iOS 17.1 + Safari 17.1 中的条件 UI#

8. 边缘情况下的条件 UI#

让我们来看看实际应用中的一些常见场景。

8.1 没有可用通行密钥时的条件 UI#

如果没有为站点保存通行密钥，根据浏览器和操作系统的不同，条件 UI 的行为将会有所不同。

8.1.1 在 macOS 上的 Chrome 中没有通行密钥时的条件 UI#

在 macOS 的 Chrome 上，点击进入输入字段将显示一个空的自动填充下拉列表：

8.1.2 在 macOS 上的 Safari 中没有通行密钥时的条件 UI#

在 macOS 的 Safari 上，不显示下拉列表，仅在输入字段中显示一个不起眼的图标：

8.1.3 在 Android 或 iOS 上没有通行密钥时的条件 UI#

在 Android 或 iOS 上，仅当用户点击字段且操作系统找到匹配的凭据后，才会出现自动填充界面。

这种差异性是经过深思熟虑的，也是 WebAuthn 隐私模型的一部分：除非用户主动选择，否则网站无法检测到通行密钥是否存在。

8.2 条件 UI 与多个凭据管理器/通行密钥提供商#

如果用户安装了多个通行密钥提供商（例如 iCloud Keychain、Google Password Manager、1Password），浏览器或操作系统通常会默认使用用户的主要凭据管理器。

如需获取支持通行密钥的不同通行密钥提供商/凭据管理器列表，我们建议查看以下 GitHub 链接。

8.2.1 Android 上的条件 UI 和多个凭据管理器#

在 Android 上，Credential Manager 会暴露不同的提供商，如 Samsung Pass 或 1Password。

点击用户标识符输入字段时，会弹出此菜单供用户选择通行密钥。

如果用户在之前的屏幕中点击“更多通行密钥”，将出现预选的其他通行密钥提供商/凭据管理器及通行密钥：

如果用户在之前的屏幕中点击了“更多保存的登录信息”，会跳出一个完整的可用列表供用户选择要使用的通行密钥。

8.2.2 iOS 上的条件 UI 和多个凭据管理器#

在 iOS 上，钥匙图标会打开来自各个源的完整通行密钥列表。

首先，在 iOS 18+ 上，将出现带有默认通行密钥提供商的常规条件 UI。

点击键盘图标后，将出现以下选择菜单。

选择凭据管理器/通行密钥提供商后，用户可以选择要使用的通行密钥。

作为一款应用或网站，你无法控制使用哪种凭据管理器——操作系统会管理该选择以维护用户隐私。

9. 结论#

通行密钥及其条件 UI / 通行密钥自动填充功能，提供了一种在线身份验证的新方法。随着我们向密码越来越被通行密钥取代的时代过渡，对强大且用户友好的过渡机制的需求是不可否认的。本文帮助了解了如何正确实现条件 UI（在过渡过程中有很大帮助）以及应特别注意哪些方面。

关于 Corbado

Corbado 是面向大规模运行 consumer 身份验证的 CIAM 团队的Authentication Intelligence Platform。我们让你看到 IDP 日志和通用 analytics 工具看不到的内容：哪些设备、操作系统版本、浏览器和 credential manager 支持 passkey，为什么注册没有转化为登录，WebAuthn 流程在哪里失败，以及什么时候操作系统或浏览器更新会悄悄破坏登录 — 而且无需替换 Okta、Auth0、Ping、Cognito 或你自有的 IDP。两款产品：Corbado Observe 提供 针对 passkey 及任何其他登录方式的 observability。Corbado Connect 提供 内置 analytics 的 managed passkey（与你的 IDP 并存）。VicRoads 通过 Corbado 为 500 万以上用户运行 passkey（passkey 激活率 +80%）。与 Passkey 专家交谈 →