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

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

最后更新时间：2025 年 11 月 4 日

以下是各大平台对 WebAuthn Signal API 的支持概览：

⚠️ 已知问题： Safari 26+ 存在一个导致 Promise 无法正确解析的 Bug (WebKit Bug #298951)。修复补丁等待合并中。

Passkey (通行密钥) 生态系统正在不断演进。为了适应变化，底层的 WebAuthn 标准也在快速迭代。新功能通常始于 GitHub 上的技术解释说明 (technical explainer)，经过充分讨论后，会转化为标准草案的 Pull Request。最近，这个 Pull Request 已作为 WebAuthn Signal API 被添加到了标准草案中。在本文中，我们将探讨：

• 为什么需要 WebAuthn Signal API： 它支持哪些应用场景？
• WebAuthn Signal API 如何工作： 它的具体工作原理是什么？对依赖方 (Relying Parties) 有哪些建议？

在撰写本文时，WebAuthn Signal API 已在 Chrome 132 及更高版本中默认启用。该 API 曾被称为 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 可能会因为各种原因改变，比如用户更改了邮箱地址。尽管服务器端的账户元数据已经更新，但在凭证选择 UI 中，旧的 user.name 仍然会显示，这会让用户感到困惑。

解决这个问题的一个变通方法是创建一个具有更新后 user.name 但相同 user.id 的新 Passkey，以此覆盖现有 Passkey。然而，这种方法很不方便，原因如下：

1. 冗余：对于特定的 依赖方 ID，认证器只能为每个 user.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 管理列表撤销凭证或删除其账户，因此必须确保这些凭证从客户端 认证器 中移除，以防止它们出现在未来的凭证选择 UI（条件式 UI / Passkey 自动填充）中。

这种功能需求出现在以下几种场景中：

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

从用户的角度来看，很难理解他们在账户设置对话框中的删除操作（如上图），并没有导致该客户端上的 Passkey 被移除。

2. 账户删除：当用户删除其账户时，所有关联的 Passkey 也应被移除。

3. 安全策略：依赖方可能制定了安全策略，要求在一段时间不活动或检测到安全问题后撤销凭证。

如果无法直接在客户端删除 Passkey，这些过时或无效的凭证将继续充斥在选择 UI 中，导致混乱。用户可能会看到并尝试使用已失效的 Passkey，从而导致认证失败和糟糕的用户体验。

请观看此视频，了解如何在 Corbado Connect 管理控制台中删除服务器端的 Passkey：

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

在实现 WebAuthn Signal API 时，务必牢记以下几点：

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

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

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

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

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

WebAuthn Signal API 为依赖方 (RP) 提供了一种简化的机制，用于更新客户端 认证器 上与 Passkey 关联的元数据。这对于确保用户在凭证选择 UI 中看到准确且最新的信息特别重要，而且无需不必要地创建新 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 的元数据在用户进行认证的不同设备和平台上保持一致。这种方法减少了在凭证选择 UI 中显示过时或错误信息的可能性。

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

WebAuthn Signal API 为依赖方 (RP) 提供了从客户端 认证器 标记删除 Passkey 的机制。这对于确保过时或无效的凭证不出现在凭证选择 UI 中至关重要，从而保持精简且安全的用户体验。在本地删除 Passkey 有两种方法：signalUnknownCredential(options) 和 signalAllAcceptedCredentials(options)。前者可用于用户未登录的情况，而后者可用于用户已登录的情况。因此，出于隐私原因，应首选后者。

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

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

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // 用户刚刚尝试使用的凭证 ID, base64url 编码
});

2. 调用方法：RP 只要检测到应该删除某个凭证，就会调用此方法。这可能是在使用无效凭证尝试认证之后立即发生，或者在账户删除期间，又或者当用户通过账户设置撤销凭证时。

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

1. 方法结构： signalAllAcceptedCredentials(options) 方法包含 rpId（依赖方 ID）、userId 和一个有效凭证 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 可以在桌面上使用 Google 密码管理器 进行测试。

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

• 关注 WebAuthn Signal API 的更新和实际实现：随时了解与 Signal API 相关的最新进展和更新。WebAuthn Signal API 已随 Google Chrome 132 启用，其他浏览器也将紧随其后（例如 Safari 也宣布了支持）。定期检查 WebAuthn Signal API 的进度和更新，以确保你的实现符合最新的标准和实践。随着形势的发展，我们会更新这篇博客文章。
• 每次成功登录后使用 signalAllAcceptedCredentials(options) 方法：这种方法可确保在一个方法中更新所有元数据和凭证 ID，简化流程并在设备和平台之间保持一致性，同时也停用了已删除或过时的凭证。
• 在大规模部署中使用 signalUnknownCredential(options) 进行实时消息传递：在 大规模 部署或需要立即更新时，考虑结合实时消息传递使用 signalUnknownCredential(options) 方法。此方法可以提高凭证管理的效率和准确性，确保无效或过时的凭证立即从选择 UI 中移除。

通过遵循这些建议，一旦 WebAuthn Signal API 得到广泛支持，你就能有效地实施它，确保 Passkey 元数据在所有客户端认证器上保持最新和一致，从而为 Passkey 提供流畅且安全的用户体验。

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

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

随着 WebAuthn 标准的发展，它受益于参与者的不同利益，各方共同推动标准的不同部分向前发展。密切关注这些发展对于保持最新状态、确保实施方案符合最新的最佳实践和标准至关重要。WebAuthn 社区将继续推动创新，使认证变得更加安全和用户友好。