WebAuthn 传输方式：内部传输与混合传输

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

注意：根据 WebAuthn 规范，空的传输方式列表意味着支持所有传输方式。

在跨平台实现 Passkey 时，开发者面临一个重要决策：

• 我们应如何处理 WebAuthn 传输方式，特别是内部 (internal) 和混合 (hybrid) 传输方式，以确保最佳的跨设备认证体验？

答案在于理解 WebAuthn 传输方式——这是一个技术细节，它决定了验证器如何与信赖方通信。虽然传输方式在理论上看似简单，但它们在网页浏览器、原生 iOS 和原生 Android 应用中的实现差异很大，尤其是在内部和混合传输方式的处理上。

本文将探讨 WebAuthn 传输方式在不同平台上的工作原理，并提出两种处理内部和混合传输方式的不同方法——每种方法都有其优缺点。

本文涵盖内容：

1. WebAuthn 传输方式：Web、iOS 和 Android 上的内部、混合和平台验证器
2. 两种方法：遵循规范与优化的内部和混合传输方式处理
3. 跨设备认证实施的最佳实践和建议

WebAuthn 传输方式定义了验证器和客户端设备之间的通信方法。WebAuthn Level 3 规范定义了六种传输类型：

usb：用于通过 USB 端口连接的硬件安全密钥，例如 YubiKeys 或其他 FIDO2 安全令牌。

nfc：通过近场通信 (Near Field Communication) 与验证器进行通信，允许用户轻触其安全密钥或支持 NFC 的设备。

ble：通过低功耗蓝牙 (Bluetooth Low Energy) 进行认证，实现与外部验证器的无线通信。

smart-card：用于智能卡读卡器，允许通过智能卡进行认证。

hybrid：实现跨设备认证，通常是用户扫描 QR 码在不同设备间进行认证——例如用手机在桌面浏览器上认证，反之亦然。这种传输方式可能会在桌面和移动设备上都触发 QR 码提示，这在某些情况下可能不是我们想要的结果。注意：hybrid 是在 WebAuthn Level 3 中新增的。

internal：验证器嵌入在设备本身内部——例如 iPhone 上的 iCloud 钥匙串（通过 Face ID 或 Touch ID 验证）、PC 上的 Windows Hello，或 Android 设备上的 Google 密码管理器。这些都属于平台验证器。

当创建 Passkey 时，验证器会表明它支持哪些传输方式。这些信息会发送到信赖方（我们的后端），后端应将其与凭证一起持久化存储。在认证期间，信赖方会将这些传输方式在 allowCredentials 列表中返回给客户端，帮助浏览器或平台决定向用户提供哪些认证方法。

不同平台对传输方式的处理方式差异很大，这给开发者带来了兼容性挑战。

浏览器从验证器接收传输信息，并在认证流程中遵循这些信息。当我们在 Chrome、Safari 或 Edge 中创建 Passkey 时，浏览器的凭证管理器会提供传输数据，这些数据根据底层的验证器而有所不同：

平台验证器：Windows Hello 只提供 ["internal"]，反映了其设备绑定的特性。然而，当 Chrome 使用 Google 密码管理器作为验证器时，它会提供 ["internal", "hybrid"]，因为 Google 密码管理器支持通过 Android 手机进行跨设备认证。

硬件安全密钥：根据其实际能力提供特定的传输方式，如 ["usb", "nfc"]。

云同步的凭证管理器：Safari 中的 iCloud 钥匙串和 Chrome 中的 Google 密码管理器通常提供 ["internal", "hybrid"]，以支持本地和跨设备认证流程。

在 Web 环境中，这些信息流动是可靠的，尽管具体的传输方式取决于浏览器选择哪个验证器来存储凭证。

文档： W3C WebAuthn 规范

Android 的 Credential Manager API 的行为与网页浏览器类似。在原生 Android 应用中创建 Passkey 时，Credential Manager 提供的传输信息与 Web 行为一致——平台验证器会准确报告其能力，系统对传输数据的处理也保持一致。Android 开发者可以依赖这些信息而无需特殊处理。

文档： Android Credential Manager

iOS 的情况更为复杂。Apple 的 AuthenticationServices 框架处理传输方式的方式取决于验证器类型：

平台验证器（iCloud 钥匙串，通过 Face ID 或 Touch ID 验证）：在创建 Passkey 期间通常返回空的传输方式数组。这并不意味着 Passkey 缺乏传输能力——只是 iOS 没有明确报告它们。根据 WebAuthn 标准，省略传输方式意味着任何传输方式都是可接受的，因此混合认证仍然有效。

安全密钥：与 iOS 设备一起使用时，会提供传输信息（例如 ["usb"]、["nfc"]），遵循预期的模式。

文档： Apple AuthenticationServices

开发者面临一个选择：是严格遵循规范，还是为了用户体验优化内部和混合传输方式。每种方法都有其优缺点。

这种方法与 WebAuthn 规范保持一致：完全按照验证器在凭证注册时提供的传输方式来使用，并在认证时原封不动地将它们发回。

实现：当创建 Passkey 时，持久化存储来自验证器响应的 transports 数组。在认证期间，将这些确切的传输方式包含在 allowCredentials 列表中：

{
    "allowCredentials": [
        {
            "id": "credential-id-base64",
            "type": "public-key",
            "transports": ["internal", "hybrid"]
        }
    ]
}

优点：

• 符合规范：精确遵循 WebAuthn 标准，确保与未来的平台更新兼容。
• 安全密钥的可靠性：对硬件安全密钥（YubiKeys 等）完美适用，因为它们总是提供准确的传输信息。
• 防止无效选项：避免提供实际上不支持的认证方法——例如，不会为 Windows Hello 凭证触发 QR 码。

缺点：

• iOS 空数组行为：iOS 上的平台验证器返回空的传输方式列表，根据规范这意味着“任何传输方式”——这可能会显示所有认证选项，包括安全密钥。
• 可能显示不想要的选项：在消费者应用中，可能会出现用户不期望看到的硬件安全密钥选项（USB、NFC）。
• 不一致的用户体验：不同平台为同一账户提供不同的认证选项。

最适用于：优先考虑标准符合性的应用、拥有多种验证器类型的企业环境。

这种方法通过根据特定的优化目标有选择地修改内部和混合传输方式来优先考虑用户体验。与其采用一刀切的规则，不如考虑这些常见的优化场景：

问题：iOS 平台验证器返回空的传输方式数组。如果将该数组留空或由后端填充，用户可能会在平台选项旁边看到安全密钥提示（USB、NFC），这在消费者应用中会造成混淆。

解决方案：为 iOS 平台验证器明确设置传输方式为 ["hybrid", "internal"]。这确保只提供平台认证和跨设备流程，隐藏安全密钥选项。

// 持久化存储 iOS 平台验证器凭证时
if (platform === "iOS" && authenticatorAttachment === "platform") {
    transports = ["hybrid", "internal"];
}

结果：为 iOS 创建的 Passkey 提供简洁的认证界面，没有安全密钥提示。

问题：在移动设备上进行认证时，显示用于跨设备认证的 QR 码会造成糟糕的用户体验——用户已经在使用拥有 Passkey 的移动设备了。

解决方案：当用户从移动设备进行认证时，移除 hybrid 传输方式，只留下 ["internal"]。

// 构建用于认证的 allowCredentials 时
const transports = isMobileDevice
    ? credentials.transports.filter((t) => t !== "hybrid")
    : credentials.transports;

结果：移动用户只会看到直接的认证选项，而没有不必要的 QR 码提示。

⚠️ 注意：操控传输方式并不总能在所有平台上产生一致的结果。广泛的测试表明，浏览器和操作系统的组合对传输方式的处理方式不同：

• 某些平台即使在传输方式中排除了 hybrid，仍然会显示 QR 码。
• 其他平台即使包含了 hybrid，也会隐藏 QR 码。
• 在 Windows、macOS 和 iOS 上的 Chrome、Edge、Safari 和 Firefox 之间，行为差异显著。

认证死角的风险：过于严格的传输方式过滤可能会造成认证死角，导致用户根本无法登录。例如，移除 hybrid 可能会阻止用户需要从借用设备进行认证的合法跨设备认证场景。在部署传输优化之前，务必提供备用认证方法，并在目标平台上进行全面测试。

这些是优化提示：WebAuthn 提供了除操控传输方式之外的其他机制来优化认证用户体验，例如 hints。

传输行为不可预测：通过 hybrid 传输方式进行的跨设备认证 (CDA) 在不同的浏览器和操作系统组合中表现出不一致的行为。真实世界的测试表明，传输值并不能保证特定的 UI 行为——平台会以不同的方式解释和处理传输方式，导致意想不到的结果。

平台特定的复杂性：当明确控制传输方式时，必须考虑到平台的差异：

• iOS：为平台验证器发送空数组；需要填充。
• Windows Hello：必须保持仅为 ["internal"]；添加 hybrid 会触发不想要的 QR 码。
• Web 和 Android：通常提供准确的传输信息。
• CDA 差异：无论 transports 数组中是否存在 hybrid，QR 码提示都可能出现或消失。

需要端到端的理解：明确控制传输方式意味着要对整个流程负责。我们必须了解每种传输组合在所有目标平台上的行为，并进行彻底测试。操控传输方式可能会造成认证死角，使用户没有有效的认证路径。

优点：

• 定制化的用户体验：精确控制用户在特定情境下看到的认证选项。
• 解决 iOS 空数组问题：在 iOS 未提供传输方式时明确定义它们。
• 情境感知优化：根据设备类型调整认证界面。

缺点：

• 行为不可预测：操控传输方式并不能保证一致的 UI 行为——广泛的测试表明，平台对传输方式的解释不同，有时会显示或隐藏选项，而不考虑传输值。
• 认证死角的风险：过于严格的传输方式过滤可能会完全阻止用户进行认证，尤其是在跨设备场景中。
• 偏离规范：偏离了规范的建议，可能会导致未来平台变更时出现问题。
• 维护负担：随着平台的发展，需要持续的平台特定逻辑和更新。
• 复杂性：必须手动处理 iOS 空数组、Windows Hello 的限制以及其他平台特性。
• 测试开销：每个优化规则都需要在所有平台组合中进行验证。

最适用于：具有特定用户体验要求的消费者应用、有资源维护平台特定逻辑的团队、优先考虑简化认证流程而非严格遵循规范的场景。

WebAuthn 传输方式的处理并非孤立存在——它是我们整体 Passkey 实施策略的一部分。在生产部署中，出现了两种常见的方法，每种方法对内部和混合传输方式的使用有不同的影响。

这种方法优先考虑灵活性和标准符合性，允许用户使用任何兼容的验证器进行认证。

实现特点：

• 认证界面：Passkey 按钮与现有登录选项（用户名/密码）并存。
• allowCredentials：设置为空数组 []，允许任何凭证匹配。
• 验证器类型：支持安全密钥、跨设备认证（QR 码）、平台验证器。
• 原生应用要求：必须支持所有认证方法，包括安全密钥。
• preferImmediatelyAvailableCredentials：不能使用，因为它定义上排除了安全密钥和 QR 码登录。
• 传输方式处理：必须适应所有传输类型，包括安全密钥的传输方式（usb、nfc、ble）。

对传输方式的影响：

由于 allowCredentials 为空，传输方式在认证过程中的重要性降低了——平台会显示所有可用的选项。然而，这意味着用户可能会同时看到安全密钥提示、QR 码和平台选项，这在消费者应用中可能导致决策瘫痪。

最适用于：企业环境、拥有多样化用户群且需要安全密钥支持的应用、优先考虑最大认证灵活性的场景。

这种方法通过将 Passkey 创建限制在平台验证器并使用“标识符优先”流程来优化消费者用户体验。

实现特点：

• Passkey 创建：通过 authenticatorAttachment: "platform" 只允许平台验证器。
• 认证流程：标识符优先——用户在认证前输入邮箱/用户名。
• allowCredentials：一旦标识符已知，就用用户的特定凭证填充（非空）。
• 验证器类型：平台验证器和跨设备认证；通常排除安全密钥。
• 原生应用优化：可以使用 preferImmediatelyAvailableCredentials，它定义上排除了安全密钥和跨设备认证。
• 跨设备认证：在 Web 上可用；在原生应用中使用 preferImmediatelyAvailableCredentials 时不可用，但这种情况很少见（用户通常在他们正在使用的设备上就有 Passkey）。
• 传输方式处理：仅关注 internal 和 hybrid 传输方式。

对传输方式的影响：

由于 allowCredentials 包含带有其传输方式的特定凭证，传输方式的处理变得至关重要。

最适用于：消费者应用、原生移动应用、优先考虑简化用户体验而非验证器灵活性的场景、已经存在标识符优先流程的平台。

对于那些已经泄露账户存在性或使用标识符优先流程（用户在看到登录选项前输入邮箱）的平台来说，面向消费者的定制化方法自然契合。一旦用户提供了他们的标识符：

1. 后端查询现有 Passkey。
2. 返回包含特定凭证及其传输方式的 allowCredentials。
3. 平台可以根据传输方式优化认证界面。
4. 没有额外的账户枚举风险（标识符已提供）。

在这些场景中，传输方式可以成为一个优化工具，而不是一个安全问题。我们可以根据设备环境（移动端 vs. 桌面端）和凭证能力来定制认证选项。

建议：对于已经使用标识符优先流程或不担心账户枚举的平台，采用明确处理传输方式的面向消费者的定制化方法能提供卓越的用户体验，尤其是在原生移动应用中，preferImmediatelyAvailableCredentials 可以实现无缝的生物特征认证。

无论我们选择哪种方法来处理内部和混合传输方式，都应遵循以下实践以减少问题：

在注册时持久化传输方式：始终将来自验证器响应的 transports 数组与凭证 ID 和公钥一起存储。这些数据对于认证流程至关重要。

优雅地处理空数组：当从 iOS 平台验证器收到一个空的传输方式数组时：

• 遵循规范：留空或省略 transports 属性——意味着“任何传输方式”都是可接受的。
• 优化方法：用 ["internal", "hybrid"] 填充，以控制显示哪些认证选项。

在所有目标平台上进行测试：创建一个覆盖所有组合的测试矩阵：

• 注册：Web、iOS 原生、Android 原生
• 认证：Web、iOS 原生、Android 原生
• 验证 QR 码在预期时出现，在不适当时隐藏。

理解空数组与缺失属性：根据规范，空传输数组 [] 和缺失的 transports 属性通常都被视为“任何传输方式都是可接受的”。然而，各平台的实现细节有所不同。

监控平台变化：WebAuthn 的实现是不断发展的。Apple、Google 和 Microsoft 会定期更新其验证器行为。请随时了解可能影响传输方式处理的变化。

WebAuthn 传输方式——尤其是内部和混合传输方式——是技术细节，但对跨设备认证有重大的实际影响。我们的传输方式处理策略应与我们更广泛的 Passkey 实施方法和目标平台保持一致。

传输决策是更广泛策略的一部分：我们如何处理传输方式取决于我们是为了最大化灵活性（空的 allowCredentials）还是为了消费者用户体验（标识符优先，使用特定凭证）。后者使传输方式成为优化的关键。

平台差异需要处理：Web 和 Android 提供可靠的传输信息，而 iOS 平台验证器返回空数组。Windows Hello 只发送 ["internal"]。理解这些差异对于生产部署至关重要。

两种有效的传输方式处理方法：遵循规范（信任验证器传输方式）适用于企业和最大化灵活性的场景。明确控制（优化传输方式）适合于具有标识符优先流程和原生移动应用的消费者应用。

标识符优先流程助力传输优化：当用户首先提供其标识符时，传输方式处理就成为一个强大的用户体验工具。我们可以防止在移动设备上出现不想要的 QR 码，隐藏安全密钥选项，并简化认证——而无需担心额外的账户枚举问题。

对于企业/最大化灵活性：

• 使用空的 allowCredentials 来支持所有验证器类型。
• 信任验证器提供的传输方式。
• 接受用户会看到更多认证选项。
• 实现更简单，兼容性更广。

对于消费者应用/原生应用：

• 实施标识符优先的认证流程。
• 限制为平台验证器（authenticatorAttachment: "platform"）。
• 使用包含特定凭证和优化后传输方式的 allowCredentials。
• 在原生应用中启用 preferImmediatelyAvailableCredentials。
• 用 ["hybrid", "internal"] 填充 iOS 的空数组。
• 在移动设备上过滤 hybrid 以防止 QR 码。
• 通过简化的认证选项提供卓越的用户体验。

对于已经有标识符优先流程的平台：

• 账户枚举已不成问题。
• 面向消费者的定制化方法与现有用户体验自然契合。
• 传输优化能立即带来用户体验上的好处。
• 推荐给大多数消费者应用的方法。

从遵循规范开始，然后根据我们的策略进行优化：

1. 在注册时完全按照接收到的方式持久化传输方式。
2. 决定我们的整体策略（最大化灵活性 vs. 面向消费者的定制化）。
3. 如果选择面向消费者的定制化：实施标识符优先流程并优化传输方式。
4. 根据所选策略适当处理 iOS 的空数组。
5. 在 Web、iOS 原生和 Android 原生平台上进行彻底测试。

WebAuthn 的生态系统在不断演进。平台供应商会定期更新其实现，而像 WebAuthn Level 3 这样的规范也会引入新功能。构建灵活的系统，使传输方式处理与我们更广泛的认证策略保持一致，可以确保我们的 Passkey 实现在生态系统成熟的过程中保持稳健，并提供卓越的用户体验。