WebAuthn Signal API：在客户端更新和删除 Passkey

Passkey 生态系统正在不断发展。为了促进变革，底层的 WebAuthn 标准也在快速演进。新功能通常始于 GitHub 上的技术说明，经过充分讨论后，会以拉取请求的形式并入标准。最近，这个 pull request 已作为 WebAuthn Signal API 添加到标准草案中。在本文中，我们将探讨：

• 为什么需要 WebAuthn Signal API： WebAuthn Signal API 支持哪些用例？
• WebAuthn Signal API 如何工作： WebAuthn Signal API 的具体工作原理是什么？对信赖方有哪些建议？

在 2025 年 1 月更新这篇博客文章时，WebAuthn Signal API 已在 Chrome 132 及更高版本中默认启用。它之前被称为 Reporting API，后来为避免与同名的另一个 API 冲突而更名。

WebAuthn Signal API 解决了与客户端 Passkey 管理相关的特定用例。具体来说，它有助于保持信赖方 (RP) 与作为客户端操作系统一部分的认证器之间的信息同步。存在以下几个重要的用例：

Subscribe to our Passkeys Substack for the latest news.

Subscribe

创建 Passkey 时，它包含几项信息：user.id、user.name 和 user.displayName。Passkey 本身通过唯一的 Credential ID 进行识别。

• user.id： 是一个唯一标识符，代表 Passkey 所关联的账户。这个 user.id至关重要，因为它用于将 Passkey 与用户账户进行实际匹配。
• user.name 和 user.displayName： 这些是仅用于在用户界面中显示的元数据。

下图展示了一个典型的、简单的数据库结构，解释了哪些信息通常会存储在哪个字段中：

重要的是要理解，虽然 user.name（通常是电子邮件地址）和 user.displayName（一个更友好、易读的名称）可以帮助用户在选择界面中识别他们的账户，但 Passkey 和账户之间的真正关联是通过 user.id 和 Credential ID 来维持的：

• 一个账户可以有多个 Passkey，但每个 Passkey 都通过 user.id 进行唯一识别并与该账户匹配。
• 每个 Passkey 本身都有一个由认证器生成的唯一 Credential ID。

当 user.name（可能是一个电子邮件地址）发生变化时，就会出现一个问题。目前，没有机制可以直接在客户端认证器上更新这一变更。user.name 可能会因多种原因而改变，例如用户更新了他们的电子邮件地址。尽管服务器端的账户元数据发生了变化，但旧的 user.name 仍会继续出现在凭证选择界面中，这可能会给用户带来困惑。

这个问题的变通方法是创建一个具有更新后 user.name 和相同 user.id 的新 Passkey，然后覆盖现有的 Passkey。然而，这种方法由于以下几个原因并不方便：

1. 冗余：每个 user.id 在每个信赖方 ID 下只能有一个 Passkey，这意味着必须用一个新的 Passkey 替换旧的，这是一个额外的步骤。
2. 用户体验：用户不会理解为什么他们需要创建一个新的 Passkey。这就是为什么这种变通方法没有被广泛使用的原因。
3. 复杂性：仅仅为了更新元数据而管理 Passkey 创建和替换，增加了不必要的复杂性。

电子邮件地址、电话号码和其他标识符可能会定期更改。如果没有一个直接的方法来更新认证器上的 user.name 和 user.displayName，用户可能会遇到一个持续存在的问题：他们看到并需要选择一个与旧电子邮件地址关联的 Passkey。这种情况破坏了 Passkey 旨在提供的无缝体验。WebAuthn Signal API 旨在解决这个问题，它允许信赖方报告 Passkey 元数据的更新，而无需创建新的 Passkey。在我们解释如何实现 Signal API 之前，我们将探讨它解决的第二个重要用例。

Become part of our Passkeys Community for updates & support.

Join

另一个关键用例是在客户端认证器上删除 Passkey。随着时间的推移，用户可能会通过 Passkey 管理列表撤销凭证或删除他们的账户，因此有必要确保这些凭证从客户端认证器中移除，以防止它们出现在未来的凭证选择界面（Conditional UI / Passkey 自动填充）中。

在以下几种场景中，需要此功能：

1. 通过账户设置删除 Passkey：当一个凭证不再有效时，例如用户通过账户设置明确删除了它：

从用户的角度来看，很难理解在账户设置中（如上图所示的对话框）的删除操作，并不会导致此客户端上的 Passkey 被移除。

2. 账户删除：当用户删除他们的账户时，所有相关的 Passkey 也应被移除。
3. 安全策略：信赖方可能有安全策略，要求在一段时间不活动后或由于检测到安全问题而撤销凭证。

如果没有直接在客户端删除 Passkey 的方法，这些过时或无效的凭证会继续堆积在选择界面中，导致混淆。用户可能会看到并尝试使用不再有效的 Passkey，从而导致认证失败和糟糕的用户体验。

实现 WebAuthn Signal API 涉及几个步骤和注意事项，以确保功能被正确和安全地集成。Signal API 允许信赖方 (RP) 在客户端认证器上更新或删除 Passkey 凭证。本节概述了实现的关键注意事项和步骤。

在实现 WebAuthn Signal API 时，务必牢记以下注意事项：

• 保护隐私：WebAuthn Signal API 的设计旨在保护用户隐私，这是 WebAuthn 的基础之一。这意味着不会向 RP 提供关于请求的更改是否已处理的反馈。该 API 静默运行，以防止任何关于凭证状态的信息泄露。

• 认证器可用性：WebAuthn Signal API 的有效性取决于认证器的可用性。这既包括物理可用性（例如，安全密钥的存在），也包括软件支持（例如，浏览器和操作系统的兼容性）。只有当认证器可访问并支持必要的操作，且无需生物识别认证时，浏览器才能执行操作。

• 域限制：该 API 确保只有与特定域关联的信赖方才能请求更改与该域相关的凭证。这是一种安全措施，以防止第三方进行未经授权的修改。

• 以 Credential ID 为密钥：在引用 Passkey 时，Credential ID 是 WebAuthn Signal API 使用的主键。此 ID 在客户端认证器上唯一标识 Passkey。该 API 允许 RP 更改与 Passkey 关联的元数据，或发出某些 Passkey 不应再被访问的信号，但只能通过 Credential ID 进行。如果认证器不知道某个特定的 Credential ID，它将静默忽略该请求。

这些注意事项对于理解 WebAuthn Signal API 正确运行的最重要方面至关重要。

WebAuthn Signal API 为信赖方 (RP) 提供了一种简化的机制，用于更新客户端认证器上与 Passkey 关联的元数据。这对于确保用户在凭证选择界面中看到准确和最新的信息，而无需不必要地创建新 Passkey 尤为重要。以下是该 API 实现此功能的方式：

使用 signalCurrentUserDetails(options) 更新元数据

Signal API 中的 signalCurrentUserDetails(options) 方法专为更新 Passkey 的元数据而设计。此方法允许 RP 提供 user.name 和 user.displayName 的当前值。

以下是该过程的工作原理（另请参阅 WebAuthn Level 3 标准）。

1. 方法结构： signalCurrentUserDetails(options) 方法包括 rp.id、user.id 以及 user.name 和 user.displayName 的更新值。

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "New user name",
    displayName: "New display name",
});

2. 更新本地元数据：查找本地（在认证器上）可用的、与 rpId 和 userId 匹配的凭证。对于所有匹配的凭证，认证器将更新凭证的 name 和 displayName。

3. 保护隐私： 该过程被设计为保护隐私。Signal API 不会向 RP 提供关于更新是否成功处理的反馈，从而防止任何关于凭证状态的信息泄露。

4. 跨设备一致性： 通过定期运行 signalCurrentUserDetails(options) 方法，RP 可以确保 Passkey 的元数据在用户可能进行身份验证的不同设备和平台上保持一致。这种方法减少了在凭证选择界面中显示过时或不正确信息的可能性。

在上面的截图中，您可以看到 Google Chrome 如何向用户提示此类更新。WebAuthn Signal API 是 Chrome 132 的一部分，可以在桌面版的 Google 密码管理器中进行测试。

WebAuthn Signal API 为信赖方 (RP) 提供了从客户端认证器发出 Passkey 删除信号的机制。这对于确保过时或无效的凭证不会出现在凭证选择界面中至关重要，从而维持简化和安全的用户体验。有两种方法可以在本地删除 Passkey：signalUnknownCredential(options) 和 signalAllAcceptedCredentials(options)。前者可以在用户未通过身份验证的情况下使用，而后者可以在用户通过身份验证时使用。因此，出于隐私原因，应首选后者。

以下是这两种方法的工作原理：

1. 方法结构： signalUnknownCredential(options) 方法包括 rpId（信赖方 ID）和 credentialId（要删除的凭证的唯一标识符）。

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id the user just tried, base64url
});

2. 调用方法：每当 RP 检测到应删除某个凭证时，就会调用此方法。这可能是在使用无效凭证进行身份验证尝试后立即发生，或在账户删除期间，或当用户通过账户设置撤销凭证时。

3. 处理方法：当调用 signalUnknownCredential(options) 方法时，客户端认证器会尝试查找与指定的 rpId 和 credentialID 匹配的凭证以进行忽略。根据认证器的功能，该凭证会被移除，或者采用认证器特定的程序在未来的身份验证仪式中隐藏该凭证。

1. 方法结构： signalAllAcceptedCredentials(options) 方法包括 rpId（信赖方 ID）、userId 和一个有效 Credential ID 的列表 allAcceptedCredentialIds（应保留的凭证的唯一标识符列表）。

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. 调用方法：每当 RP 检测到应删除某个凭证并发出有效凭证列表信号时，就会调用此方法。应优先使用此方法而不是 signalUnknownCredential(options) 来删除凭证。

3. 处理方法：当调用 signalAllAcceptedCredentials(options) 方法时，客户端认证器会匹配 rpId 和 userId。认证器会查找所有与 rpId 和 userId 匹配的本地凭证。将结果与 allAcceptedCredentialIds 进行比较。如果存在不在 allAcceptedCredentialIds 中的本地凭证，则这些凭证将在本地被移除（或根据认证器被隐藏）。

4. 取消隐藏凭证：如果凭证仅被隐藏（取决于认证器）而现在是 allAcceptedCredentialIds 的一部分，那么这些凭证将再次出现在未来的身份验证仪式中。

5. 实用提示：

   • 使用 signalAllAcceptedCredentials(options) 时，需要注意的是，执行此方法时认证器可能并不总是连接状态。因此，信赖方可以考虑定期运行 signalAllAcceptedCredentials(options)，例如在每次登录时，以确保所有凭证都是最新的。
   • 信赖方在指定凭证 ID 列表（allAcceptedCredentialIds）时必须谨慎。未包含在此列表中的凭证可能会被认证器隐藏或移除，且可能无法恢复。为防止有效凭证被错误地忽略，确保列表完整至关重要。如果不小心遗漏了有效的凭证 ID，应尽快将其重新添加到 signalAllAcceptedCredentials(options) 中，以便再次使其可见（假设认证器支持此操作）。
   • 只要有可能，认证器应优先选择暂时隐藏凭证，而不是永久删除它们。这种方法有助于在信赖方意外忽略了有效凭证 ID 的情况下进行恢复，使其能够被恢复而不会永久丢失。

在上面的截图中，您可以看到 Google Chrome 如何发出删除信号。WebAuthn Signal API 是 Chrome 132 的一部分，可以在桌面版的 Google 密码管理器中进行测试。

为了有效地实现 WebAuthn Signal API 并确保 Passkey 元数据在客户端认证器之间无缝同步，请考虑以下建议：

• 关注 WebAuthn Signal API 的更新和实际实现：随时了解与 Signal API 相关的最新发展和更新。WebAuthn Signal API 已在 Google Chrome 132 中启用，其他浏览器（例如 Safari 也宣布了支持）也将陆续跟进。定期检查 WebAuthn Signal API 的进展和更新，以确保您的实现与最新的标准和实践保持一致。我们将会在未来更新这篇博客文章，目前内容基于截至 2025 年 1 月 14 日的可用信息。
• 每次成功登录后，从 signalAllAcceptedCredentials(options) 方法入手：这种方法确保所有元数据和凭证 ID 都在一个方法中更新，简化了流程，并保持了跨设备和平台的一致性，同时还能停用已删除或过时的凭证。
• 对于大规模部署，使用 signalUnknownCredential(options) 进行实时消息传递：在大规模部署或需要立即更新的情况下，可以考虑使用 signalUnknownCredential(options) 方法进行实时消息传递。此方法可以提高凭证管理的效率和准确性，确保无效或过时的凭证能被迅速从选择界面中移除。

通过遵循这些建议，您可以在 WebAuthn Signal API 获得支持后有效地实现它，确保 Passkey 元数据在所有客户端认证器上保持最新和一致，从而为 Passkey 提供流畅、安全的用户体验。

WebAuthn 标准在不断发展，功能每月都在变得更加丰富。WebAuthn Signal API 的引入是在客户端认证器上管理 Passkey 元数据和删除操作方面迈出的重要一步。此 API 解决了保持信赖方 (RP) 和认证器之间信息同步的关键用例，并确保移除无效或过时的 Passkey，从而改善用户体验。

• 为什么需要 Signal API？ Signal API 对于在客户端认证器上更新 Passkey 元数据和删除 Passkey 至关重要。它解决了与过时的 user.name 和 user.displayName 信息相关的问题，这些问题在凭证选择界面中显示时可能会引起混淆。此外，它通过移除已撤销或已删除的 Passkey，有助于维护一个干净、安全的凭证选择界面。
• Signal API 如何工作？ Signal API 的工作原理是允许 RP 调用关于凭证当前状态的方法，包括元数据更新和发出 Passkey 删除信号。这些报告由客户端认证器处理，确保呈现给用户的信息是准确和最新的。该 API 的设计旨在保护隐私，并且在运行时不会向 RP 提供有关更新成功与否的反馈。

随着 WebAuthn 标准的发展，它得益于其参与者的不同利益，他们共同推动标准的不同部分向前发展。密切关注这些发展对于了解最新的增强功能至关重要，并能确保实现方式与最新的最佳实践和标准保持一致。WebAuthn 社区将继续推动创新，使身份验证变得更加安全和用户友好。