原生 App Passkeys 的密码管理器测试

1. 简介：原生 App Passkeys 与第三方密码管理器#

随着 iOS 17 和 Android 14 的发布，原生移动应用的 Passkey 格局发生了根本性的变化。第三方密码管理器首次可以充当 Passkey Providers，打破了 iCloud Keychain 和 Google Password Manager 的垄断。这意味着用户可以将他们信任的解决方案（如 1Password、Bitwarden 或 Dashlane）带入原生 App 的认证流程中。虽然这对用户选择权来说是一个巨大的胜利，但也给开发者带来了极大的复杂性。在原生移动应用中，你的 Passkey 实现可能在不同的密码管理器中表现各异。因此，团队必须正确测试原生 App Passkeys 和第三方密码管理器。

这份综合指南分享了我们在原生 App Passkey 测试中针对第三方密码管理器的实战经验。虽然 Passkey 生态系统在 2025 年已经相当成熟，但实际实施仍需要在各种密码管理器之间进行仔细验证。我们将经验总结成了一份实用的测试计划，确保你的原生 App 能与用户偏好的密码管理器无缝协作。

2. 为什么生产环境中的 Passkey 测试至关重要#

2.1 用户自带密码管理器#

密码管理器生态系统已经超越了平台原生的解决方案。用户会根据跨平台同步、企业功能或隐私偏好等特定需求，积极选择 1Password、Bitwarden、Dashlane、Proton Pass 和 NordPass 等第三方密码管理器。你的原生 iOS / Android 应用必须适应这种多样性，而不是强迫用户切换他们信任的密码管理方案。

根据我们在 Corbado 页面上测量的数据，我们发现只有 5-10% 的普通用户依赖第三方密码管理器。虽然这个数字听起来很低，但如果你在大规模环境中工作，这将对你的 Passkey 实现的感知和支持工单的数量产生巨大影响。我们发现，一些密码管理器对 WebAuthn 规范的实现略有不同，导致用户体验甚至 Bug 的细微差异。

2.2 原生 App 中不同的 UX 模式#

原生 iOS 和 Android 应用提供了不同的 Passkey 使用方式。在 Android 上，你会遇到触发 Passkey 流程的 Passkey 叠加层（Overlay）和手动文本字段输入（对于 Web 应用，Android 也支持 Conditional UI）。iOS 展示了它自己的一套 Passkey 叠加层，以及 Conditional UI 和手动文本字段输入。此外，还有其他边缘情况需要检查。总而言之，你的原生应用必须优雅地处理：

• Passkey overlay logins：页面加载时立即出现的登录叠加层
• Conditional UI logins (iOS-only)：自动建议可用 Passkeys 的功能
• Text-field logins：用户在点击按钮前先输入用户名的场景
• Cross-device authentication (CDA)：使用另一台设备进行 Passkey 认证
• Fallback mechanisms：当 Passkey 不可用时的回退机制

2.3 WebAuthn Flags 需要精确配置#

正确的 Flag 配置决定了 Passkeys 是否能在不同设备和平台上按预期工作。关键值包括：

• Relying Party ID (rpID)：必须在 Web 和原生实现之间完全匹配，这是 Passkey 绑定的域名
• User verification：确定用户需要提供本地认证（如生物识别）
• Resident key/discoverable credentials：启用无用户名认证（允许 Conditional UI）
• Backup eligibility (BE) 和 backup state (BS)：允许 Passkeys 的跨设备同步

配置错误的 Flags 并不总是会导致立即失败。但是，它们可能会产生微妙的问题和不一致，例如 Passkeys 在一台设备上可用，但未跨设备同步（即使两台设备上都安装了同一个第三方密码管理器）。我们在测试中的一个发现是，一些第三方密码管理器错误地设置了 BE/BS Flags，这占了 Passkey 问题的一大部分。

2.4 单实例 App 的生命周期管理#

Single-activity (Android) 和 single-scene (iOS) 架构需要细致的生命周期管理。当密码管理器面板出现并被关闭时，你的 App 必须保留状态、处理回调并正确恢复。这在 Android 上尤其关键，因为 launchMode 配置可能会导致意外行为。

例如，我们发现将 MainActivity 设置为 launchMode="singleInstance" 会产生问题。在某些 Android 版本和 OEM 定制系统中，此模式会导致 Credential Manager UI 作为单独的任务打开。这不仅会在“最近任务”屏幕中增加一个令人困惑的额外 App 条目，而且如果 App 在 Passkey 对话框打开时进入后台，还可能导致 App 挂起。

推荐的修复方法是将配置更改为 launchMode="singleTask"。这可以防止 Credential Manager 生成单独的任务，确保在不同 OEM（Samsung、Google、Vivo 等）之间有更可预测的生命周期，并降低特定供应商 Bug 的风险。它为测试导航、叠加层和深度链接（Deeplinks）提供了更稳定的基础。

我们观察到，此类生命周期问题通常被伪装成“密码管理器 Bug”，而实际上是应用层面的问题。在不同提供商之间进行适当的检测和测试有助于及早识别这些模式。

3. 设置你的测试环境#

3.1 目标密码管理器#

将你的原生 App Passkey 测试重点放在最广泛采用的第三方密码管理器上：

主要目标（必须覆盖）：

• 1Password
• Bitwarden
• Dashlane
• Proton Pass
• NordPass

次要目标（基于你的用户群）：

• 区域性提供商（例如，针对 Samsung 设备的 Samsung Pass）
• 企业解决方案（如果针对商业用户）
• 平台默认设置（Google Password Manager, iCloud Keychain）作为基准

避免测试每一个可用的密码管理器的诱惑。专注于代表你 90% 用户群的提供商。我们的分析显示，这五个主要目标覆盖了欧盟/美国/英国/澳大利亚/新西兰 85% 的第三方密码管理器用户。

3.2 预检清单#

在开始每次测试运行之前，确保环境干净、可复现：

1. 清理凭证状态：

• 删除你的 RP ID 的所有现有凭证
• 清除浏览器和 App 缓存
• 完全退出并重新登录密码管理器
• 强制关闭并重新启动目标 App

2. 稳定测试环境：

• 确保网络连接稳定（测试期间不要使用 VPN）
• 如果进行自动化测试，请禁用 UI 动画
• 使用一致的设备方向
• 记录操作系统版本、App 版本和密码管理器版本

4. 综合测试计划#

每个测试都验证 Passkey 功能的特定方面。请系统地记录结果，标记通过/失败状态，并详细记录任何异常情况。

4.1 核心认证流程测试#

测试 1：中止 Passkey 创建（在成功常规登录后）#

验证优雅的取消处理

✓ 密码管理器面板正确打开
✓ 用户取消而不创建 Passkey
✓ App 返回登录屏幕
✓ 密码管理器中没有孤立的凭证
✓ UI 显示适当的重试选项

测试 2：创建 Passkey（在成功常规登录后）#

验证认证流程后的 Passkey 创建

✓ 本地认证可靠启动
✓ 生物识别认证成功完成
✓ 使用正确的 RP ID 创建了凭证
✓ App 转换到已认证状态，没有死循环

测试 3：使用现有 Passkey 认证#

测试标准认证场景

✓ Passkey Overlay UI 出现或用户在文本字段场景中提供用户名
✓ 生物识别扫描和单一生物识别提示导致成功认证
✓ 没有选择循环或面板重新出现
✓ 认证后会话保持稳定

测试 4：从设置中创建 Passkey#

验证应用内 Passkey 管理

✓ 正确的 RP ID、可发现性和 BE/BS Flags
✓ 创建后 App 保持已认证状态
✓ 密码管理器立即更新并显示正确的标签

测试 5：删除 Passkey 并尝试重新登录#

测试凭证生命周期管理

✓ 在设置中删除 Passkey
✓ Passkey 登录不可用
✓ 提供合适的回退选项

4.2 跨平台兼容性测试#

测试 6：在 Web 上使用原生 App 创建的 Passkey（同一设备）#

验证 App 到 Web 的可移植性

✓ 浏览器识别 App 创建的 Passkeys
✓ 选择面板显示正确的 RP 关联
✓ 认证完成，无需 QR/CDA 绕道

测试 7：在原生 App 中使用 Web 创建的 Passkey#

测试 Web 到 App 的凭证共享

✓ App 在选择中显示 Web 创建的凭证
✓ 首次尝试认证成功
✓ 没有强制密码回退

测试 8：跨设备同步（移动端到桌面端）#

验证 Passkey 从原生 App 同步到桌面浏览器

✓ App 创建的 Passkey 同步到桌面密码管理器
✓ 同步的 Passkey 在桌面浏览器中无缝工作
✓ 不触发二维码 / 跨设备流程
✓ 认证完成，无需循环或错误

测试 9：跨设备同步（桌面端到移动端）#

验证 Passkey 从桌面浏览器同步到原生 App

✓ 桌面创建的 Passkey 同步到移动密码管理器
✓ 原生 App 正确显示同步的 Passkey
✓ 认证成功，无需密码回退
✓ 日志将 assertion 绑定到正确的 credential ID

测试 10：手机作为 Web 的认证器#

验证“手机作为安全密钥”场景

✓ 手机提供 App 创建的凭证用于 Web CDA
✓ 没有错误的“无可用 Passkeys”提示
✓ 移动端生物识别后 Web 会话完成

5. 常见问题和缓解策略#

我们的广泛测试揭示了几个影响第三方密码管理器 Passkey 集成的反复出现的模式：

跨设备同步延迟#

问题： 在一台设备上创建的凭证可能不会立即出现在其他设备上。

解决方案： 实现带有指数退避的重试逻辑。为遇到同步延迟的用户提供手动刷新选项。

特定版本的行为#

问题： 密码管理器的行为在不同操作系统版本之间差异很大，尤其是在 Android 14+ 和 iOS 17+ 上。

解决方案： 维护兼容性矩阵，并根据检测到的操作系统版本调整流程。考虑为了最佳体验设置最低版本要求。

6. 结论：构建生产就绪的 Passkey 支持#

成功在原生 App 中实现第三方密码管理器的 Passkey 支持需要有条不紊的测试和对细节的关注。我们经过实战验证的综合测试计划为验证你的 Passkey 集成提供了坚实的基础。

生产部署的关键要点：

1. 系统化测试： 使用我们的测试计划作为基准，并根据你的具体用例进行调整
2. 尊重用户选择： 支持用户喜欢的密码管理器，而不仅仅是平台默认设置
3. 持续监控： 实施全面的日志记录以捕捉生产环境中的边缘情况
4. 详尽记录： 保持对特定提供商行为和变通方法的清晰记录

Passkey 生态系统继续快速发展。密码管理器定期更新其实现，操作系统引入新功能，WebAuthn 规范本身也在进步。通过现在建立一个强大的测试框架，你将做好准备以适应技术的成熟。

随着新模式的出现，我们将继续更新我们的 SDK 和测试方法。对第三方密码管理器进行全面测试的投入将在减少支持负担和提高用户满意度方面带来回报。毕竟，无论用户选择哪种密码管理器，认证都应该简单好用。