原生应用通行密钥 (Passkey)：原生 vs WebView 实现

注意： 通常会将系统 WebView 和嵌入式 WebView 结合使用，其中系统 WebView 处理登录（具有自动凭据共享功能），然后嵌入式 WebView 在设置中呈现通行密钥管理。

关键决策因素：

• 基于 OAuth 的登录？ → 系统 WebView（ASWebAuthenticationSession、Chrome Custom Tabs）
• 想要在原生外壳中重用 Web 身份验证？ → 嵌入式 WebView（WKWebView、Android WebView 搭配 WebKit 1.12.1+）
• 构建原生优先应用？ → 原生实现（Apple AuthenticationServices、Google Credential Manager）

现代移动平台提供了三种不同的方法将通行密钥集成到您的原生应用中，每种方法在用户体验、技术复杂度和 OAuth 兼容性方面都有不同的权衡：

1. 原生实现：使用平台 API（iOS AuthenticationServices、Android Credential Manager）直接在应用的 UI 中构建通行密钥流程。通过无缝的生物特征验证提供最佳的用户体验，但需要中等至较高的技术实施工作量。

2. 系统 WebView：使用平台的浏览器组件（iOS ASWebAuthenticationSession / SFSafariViewController、Android Chrome Custom Tabs）来处理身份验证。非常适合基于 OAuth 的登录流程，并与系统浏览器共享凭据。

3. 嵌入式 WebView：在您的应用中嵌入一个可自定义的 Web 视图（iOS WKWebView、Android WebView），以在原生应用骨架中重用 Web 身份验证。提供类似原生的外观，没有 URL 栏，并完全控制 Web 视图 UI。需要额外的设置，包括权限和授权 (iOS)，以及在 Android 上使用 AndroidX WebKit 1.12.1+ 配置 WebView 以启用通行密钥功能。

正确的选择取决于您的应用的身份验证架构、您是否使用 OAuth 提供商、您需要对 UI 有多大的控制权，以及您是在构建原生优先应用还是在重用 Web 组件。

原生通行密钥实现提供最佳的用户体验，使用平台特定的 API 直接在应用的 UI 中构建身份验证流程。用户受益于平台原生的对话框、无缝的生物特征验证和最快的登录速度。

何时选择原生实现：

• 构建新的原生应用或重构身份验证至原生屏幕
• 想要获得最佳的用户体验，实现即时、静默身份验证
• 应用启动时的自动通行密钥提示：原生实现可以使用 preferImmediatelyAvailableCredentials 在通行密钥可用时自动显示通行密钥覆盖层，从而提供最快的登录体验，而无需输入标识符
• 需要完全控制身份验证 UI 和流程
• 愿意投资特定平台的实现（iOS Swift、Android Kotlin）

关键优势：preferImmediatelyAvailableCredentials()

原生实现可以利用 preferImmediatelyAvailableCredentials() 在通行密钥可用时，立即在应用启动时创建一个自动通行密钥覆盖层。这种无用户名的流程提供了最快的登录体验——用户无需先输入标识符即可立即看到他们的通行密钥。此功能是原生实现独有的，不可在 WebView 变体中使用。

下图说明了与 WebView 的 Conditional UI 方法相比，原生身份验证如何提供更快的用户旅程：

原生的自动覆盖层提供了更优越的用户体验和更高的通行密钥使用率，因为在应用启动时即刻开始身份验证，而 WebView 实现则要求用户首先与输入字段交互。

技术要求概述：

原生通行密钥集成需要您的应用和 Web 域之间的加密信任。如果没有它，操作系统将拒绝所有 WebAuthn 操作。主要要求：

1. 托管在 /.well-known/ 的应用-域关联文件
2. 与您的 Web 域匹配的正确的依赖方 ID (Relying Party ID)
3. 平台特定的功能（详见第 4 节）

主要好处：在您的网站上创建的通行密钥可以在您的应用中无缝使用，反之亦然。

在 iOS 上原生实现通行密钥涉及 Apple 的 AuthenticationServices 框架，该框架提供了用于 WebAuthn 操作的 API：

关键组件：

• ASAuthorizationController：管理身份验证流程
• ASAuthorizationPlatformPublicKeyCredentialProvider：创建通行密钥请求
• 处理通行密钥登录的三种不同 UI 模式：
  • 文本字段登录：传统的用户名输入框，在按钮提交时开始通行密钥登录
  • 通行密钥模态覆盖层：列出可用通行密钥的操作系统对话框
  • Conditional UI：键盘上方 QuickType 栏中的通行密钥建议

开发提示

• AASA 缓存：Apple 积极缓存 AASA 文件（长达 24 小时），这可能会阻碍测试。解决方案：在您的测试设备上启用开发者模式，并在您的 AASA URL 附加 ?mode=developer 以强制获取最新内容
• 性能测试：使用包含数百个凭据的 iCloud 帐户进行测试，以观察真实世界的延迟。如果存储了大量通行密钥，系统覆盖层可能会显示轻微的延迟

Android 的原生通行密钥实现使用 Credential Manager API（或者旧的 FIDO2 API 以保持向后兼容）：

关键组件：

• CredentialManager：所有凭据操作的核心 API
• CreatePublicKeyCredentialRequest：用于通行密钥注册
• GetCredentialRequest：用于通行密钥身份验证
• 两种主要的 UI 模式：
  • 文本字段登录：传统的用户名输入框，在按钮提交时开始通行密钥登录
  • 通行密钥模态覆盖层：列出可用通行密钥的操作系统对话框

注意：Android 原生应用目前缺乏 iOS 在键盘上的 Conditional UI 建议（尽管 Conditional UI 在 Web 应用中有效）

原生实现通行密钥有重大的挑战和经验教训：在操作系统层面进行集成可能会暴露跨不同设备和操作系统版本的问题。

1. 例如，我们的团队遇到了一些问题，如 Apple 对 apple-app-site-association 文件（用于应用/Web 凭据链接）的积极缓存，以及某些 Android OEM 生物特征提示中细微的 UI 差异。
2. 此外，请考虑在某些企业场景中，受管设备可能通过策略禁用了通行密钥同步。在企业环境中，如果关闭了 iCloud 钥匙串或 Google 密码管理器同步，通行密钥将绑定到设备且不会漫游——这是需要规划的一个重要场景（例如确保用户拿到新手机时仍能登录）。
3. 此外，第三方凭据管理器应用可能会影响流程。例如，如果用户将 1Password 等密码管理器设置为活动的凭据提供程序，它通常会拦截通行密钥的创建和存储，其优先级高于平台的原生凭据管理器。

虽然您可以使用原始平台 API 实现通行密钥，但专用 SDK 可以通过处理 WebAuthn 的复杂性、边缘情况并提供内置遥测功能，显著加快开发速度。SDK 还提供用于单元测试的模拟接口（这很关键，因为您无法在模拟器中测试生物特征）。

建议： 对于原生实现，我们建议使用 Corbado SDK（iOS Swift Passkey SDK、Android Kotlin Passkey SDK），它们处理在生产部署中发现的大量边缘情况，并提供额外的遥测和测试。

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

系统 WebView 使用平台的原生浏览器组件来处理您的应用内的身份验证。与完全原生实现不同，系统 WebView 使用实际的系统浏览器（iOS 上的 Safari，Android 上的 Chrome）显示 Web 内容，维护共享的 cookie、保存的凭据和熟悉的浏览器安全指示器。

何时选择系统 WebView：

• 您的应用使用基于 OAuth 的登录：系统 WebView 是 OAuth2/OIDC 流程的推荐方法，可提供安全的身份验证
• 您想在移动应用中重用现有的基于 Web 的身份验证
• 需要支持多种身份验证方法（密码、社交登录、通行密钥）而无需重新原生构建
• 希望跨 Web 和移动应用维护单一的身份验证代码库

关键优势：

• OAuth 兼容性：专为 OAuth/OIDC 身份验证流程构建
• 安全指示器：用户看到实际的 URL 和 SSL 证书，建立信任
• 实施工作量低：所需原生代码极少
• 一致的用户体验：用户已经信任的熟悉浏览器界面

平台组件：

• iOS：ASWebAuthenticationSession（推荐用于身份验证流程）或 SFSafariViewController（常规浏览）
• Android：Chrome Custom Tabs (CCT)

像 Google 和 GitHub 这样的主要公司采用了这种方法，通过在其现有 Web 身份验证页面的 WebView 覆盖层，将通行密钥登录添加到他们的移动应用中。当完全原生的身份验证重构不能立即进行时，这种方法效果很好。

iOS 提供两个主要的系统 WebView 组件用于身份验证：

企业 Passkey 白皮书. 面向 passkey 项目的实用指南、推广模式和 KPI。

获取白皮书

ASWebAuthenticationSession（推荐用于身份验证）：

• 专为 OAuth/OIDC 和安全登录流程构建
• 自动提示用户该应用想要进行身份验证
• 与 Safari 共享 cookie 和凭据
• 通过 iCloud 钥匙串支持通行密钥

SFSafariViewController（常规浏览）：

• 在应用内提供完整的 Safari 体验
• 显示 URL 栏和安全指示器
• 在 iOS 11+ 上不共享 Safari cookie；当需要 Safari 会话共享时使用 ASWebAuthenticationSession
• 定制性较弱，但在用户看来更值得信赖

如果您的应用使用基于 OAuth 的登录，ASWebAuthenticationSession 是推荐的选择，因为它是专门为身份验证场景设计的，并且在安全性和用户体验之间提供了最佳平衡。

Chrome Custom Tabs (CCT) 在您的应用内提供由 Chrome 驱动的身份验证体验：

主要功能：

• 与 Chrome 浏览器共享 cookie 和凭据
• 显示 URL 和安全指示器
• 可以自定义工具栏颜色和品牌推广
• 预热功能以实现更快的加载时间

OAuth 集成：Chrome Custom Tabs 是相当于 iOS ASWebAuthenticationSession 的 Android 版本，提供出色的 OAuth 支持，同时保持对存储通行密钥的访问。

在实时 demo 中试用 passkeys。

试用 passkeys

嵌入式 WebView 提供对在您的应用中呈现 Web 内容的完全控制，允许直接操作 cookie、会话和导航，且没有 URL 栏。然而，这种控制带来了额外的技术要求，以启用通行密钥功能。

何时选择嵌入式 WebView：

• 类似原生的体验：您的应用已经将身份验证嵌入在可自定义的 Web 视图中，以保持原生的外观和感觉，并且您希望保持这种一致的用户体验
• 需要会话/cookie 控制：您的应用需要在 OAuth 身份验证完成后直接操作身份验证令牌和会话状态
• 现有的身份验证流程中，系统 WebView 身份验证返回授权码，但在嵌入式上下文中不返回会话
• 必须在多个嵌入式 Web 屏幕之间维护身份验证状态
• 仅限第一方身份验证：您的应用直接处理身份验证，对于第三方通行密钥实现请参阅此处
• AndroidX WebKit 1.12.1+ 和运行时功能检测
• 接受用于登录的 Conditional UI 限制（在嵌入式 WebView 中不支持），这对于管理设置不相关

重要背景：

许多应用采用混合方法：系统 WebView 处理初始的 OAuth 身份验证（通行密钥在其中无缝工作），然后切换到嵌入式 WebView 进行身份验证后的操作以在设置中管理通行密钥。当尝试直接在嵌入式 WebView 中使用通行密钥时，挑战就会出现。

技术要求：

与系统 WebView 相比，嵌入式 WebView 需要额外的设置：

1. iOS：Associated Domains 授权，AASA 文件配置
2. Android：带有 WebView WebAuthn 配置的 AndroidX WebKit 1.12.1+（需要功能检测）
3. 两者皆是：正确配置了众所周知的关联文件和 Digital Asset Links

平台组件：

• iOS：WKWebView
• Android：android.webkit.WebView

权衡：

• 中等复杂性：需要 WebView 配置 (Android WebKit 1.12.1+) 和授权设置 (iOS)
• 通行密钥采用率较低：与原生相比，用户可能会遇到更多摩擦
• 不支持 Conditional UI：输入字段中的通行密钥自动填充在 Android 嵌入式 WebView 中不起作用
• 平台支持有限：某些功能可能无法一致运行（例如自动创建通行密钥）

通过 WebView 实现通行密钥时，理解系统 WebView 和嵌入式 WebView 之间的区别至关重要。上面概述的三种方法（原生实现、系统 WebView 和嵌入式 WebView）分别服务于不同的用例。

在 iOS 上，您有多个选项用于在应用内显示 Web 内容：

• WKWebView 是一个可定制的 WebView，属于 WebKit 框架（在 iOS 8 中引入）的一部分。它使您能够高度控制 Web 内容的外观和行为。
• SFSafariViewController 是 Apple 提供的一个视图控制器，在您的应用中充当轻量级 Safari 浏览器。它使用 Safari 的引擎。在 iOS 11+ 上，它具有独立的 cookie 存储区，不共享 Safari cookie。当需要 Safari 会话共享时请使用 ASWebAuthenticationSession。
• SFAuthenticationSession / ASWebAuthenticationSession 是专门针对 OAuth/OpenID 或其他安全登录流程设计的专用 Web 身份验证会话（自 iOS 11/12 起可用）。这些也会在底层利用 Safari，但专注于身份验证流程，并自动处理共享 cookie 和单点登录 (SSO) 等事宜。

在 Android 上，主要选择是：

• Android WebView 是标准的 WebView 小部件 (android.webkit.WebView)，它本质上是一个可以嵌入在您的活动 (Activities) 中的迷你浏览器。它高度可定制，但在您的应用进程中运行。
• Chrome Custom Tabs (CCT) 是一项允许在您的应用上下文中打开由 Chrome 提供支持的标签页的功能。Custom Tabs 显示为应用的一部分，但由 Chrome 浏览器（如果已安装）提供支持，具备预加载、共享 cookie 以及让用户信任的熟悉 URL 栏等功能。

在接下来的章节中，我们将更深入地探讨 iOS 和 Android 的这些 WebView 类型，并讨论哪一种最适合通行密钥身份验证流程。

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

订阅

Apple 的平台提供了上面列出的三种 WebView 选项。您的选择将影响应用内通行密钥的使用流畅度：

为了测试 iOS 中不同的 WebView 行为，我们推荐该应用 WebView - WKWebView and UIWebView rendering。

WKWebView 是 iOS 的多功能 WebView 组件。开发人员可以嵌入 WKWebView 来呈现具有对 UI 和行为的高度控制权的 Web 内容。WKWebView 使用与 Safari 相同的渲染引擎，因此性能非常好并支持现代 Web 功能。从理论上讲，如果配置正确，WKWebView 可以处理 WebAuthn（从而处理通行密钥），但请注意，出于安全考虑，某些高级浏览器功能可能会受到限制。需要注意的一点是，默认情况下 WKWebView 不与 Mobile Safari 共享 cookie 或钥匙串数据。用户可能需要重新登录，因为他们的 WebView 会话与 Safari 的会话是隔离的。此外，因为应用可以完全自定义 WKWebView 的内容，用户不会看到地址栏或 Safari UI——这对于品牌推广来说非常棒，但这意味着用户验证页面合法性的线索减少了（对网络钓鱼的担忧）。有些应用甚至滥用 WKWebView 注入脚本或更改内容（例如，有人指出 TikTok 通过其应用内浏览器注入跟踪 JS），因此在使用 WKWebView 时务必要谨慎以确保安全且值得用户信任。

SFSafariViewController 提供了应用内的 Safari 体验。当您使用 SFSafariViewController 打开 URL 时，它几乎就像在真正的 Safari 浏览器中打开它一样，只是用户停留在您应用的 UI 中。这对于通行密钥的优势是巨大的：因为它本质上就是 Safari，所以可以访问用户的 iCloud 钥匙串和保存的通行密钥。请注意，cookie 在 iOS 11+ 上是不共享的。这意味着如果用户已经拥有您网站的通行密钥，Safari 可以找到它，甚至可以显示 Conditional UI 自动完成功能以便于登录。SFSafariViewController 的可定制性较差（您不能过多更改其工具栏），但它会自动处理大量安全和隐私功能。显示了 URL 栏以及 HTTPS 的挂锁图标，这让用户确信他们在正确的域上。通常，SFSafariViewController 被认为比原始 WKWebView 更安全，并且实现起来更简单（Apple 将其作为一个拖放组件提供）。主要的权衡是您牺牲了对外观和感觉的一些控制。对于身份验证流程，这通常是可以接受的。此处的优先级是安全性和登录便利性，SFSafariViewController 通过使用 Safari 的上下文在这些方面表现出色。

SFAuthenticationSession / ASWebAuthenticationSession – 这些类（后者是较新的更加 Swift 友好的名称）专门用于登录流程，例如 OAuth 或 OpenID Connect。当您需要通过网页验证用户（可能是对外部 IdP）时，这些会话是 iOS 上的首选。它们与 SFSafariViewController 非常相似，都在底层使用 Safari 浏览器，并与 Safari 共享 cookie/存储区。关键区别在于 SFAuthenticationSession 将始终提示用户，该应用想要使用网页进行身份验证（为了让用户知情），并且如果可用，它将自动使用用户现有的 Safari 会话。

其好处是无缝的 SSO 体验——如果用户已经在 Safari 中的提供商那里登录，此会话可以使用该 cookie 以避免再次登录。对于通行密钥而言，这一点很重要，因为这意味着此处也可以使用任何存储在 Safari/iCloud 钥匙串中的通行密钥凭据。Apple 的官方指南是建议对于任何看起来像登录流程的操作使用 ASWebAuthenticationSession。优点是增强的隐私保护（您的应用永远看不到凭据或 cookie，由 Safari 处理）以及内置的 SSO 支持。缺点是它仅限于身份验证流程（您不会用它来仅仅在您的应用中呈现任意 Web 内容）。总而言之，如果您在 iOS 上选择 WebView 方法，ASWebAuthenticationSession 通常是实现通行密钥的最佳选择，因为它安全、与 Safari 共享状态并且是专为身份验证构建的。

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

查看采用数据

在 Android 上，关于 WebView 的决定在于经典 WebView 和 Chrome Custom Tabs 之间：

为了测试 Android 中不同的 WebView 行为，我们推荐该应用 WebView vs Chrome Custom Tabs。

Android WebView (android.webkit.WebView) 是一个允许您在活动布局中嵌入网页的组件。它与 WKWebView 相似，赋予您完全控制权：您可以拦截导航、注入 JavaScript、自定义 UI 等。它也在您的应用进程中运行。将 WebView 用于通行密钥意味着您的应用加载您的 Web 登录页面，而该页面可以发起 WebAuthn 通行密钥验证。现代 Android WebView 确实支持 WebAuthn（前提是设备的 WebView 实现已通过 Android System WebView 或 Chrome 组件更新）。一个主要的考虑因素：默认情况下，Android WebView 不与用户的 Chrome 浏览器共享 cookie 或存储的凭据。因此，在 WebView 中创建或使用的任何通行密钥可能都不为 Chrome 所知，反之亦然。这种隔离对安全性有好处（您的应用无法读取浏览器 cookie），但这可能会迫使用户在 Chrome 中已经完成身份验证的情况下再次登录。另一个问题是信任。一个普通的 WebView 不会显示 URL 或 SSL 锁图标，因此用户必须完全信任您的应用不会进行网络钓鱼。出于潜在的网络钓鱼风险，Google 甚至已禁止使用 WebView 进行 Google OAuth 登录。性能方面，WebView 不错，但可能会比使用用户默认浏览器更慢或消耗更多内存，特别是在加载重型页面时。

Chrome Custom Tabs (CCT) 是一种混合方法。它们允许您的应用打开由 Chrome 呈现的页面，使其看起来就像是您应用的一部分。您可以定制工具栏颜色，添加应用标识等，但内容在独立的进程中由 Chrome 渲染。对于通行密钥，CCT 有几点好处：它们与 Chrome 共享用户的 cookie 和凭据，这意味着如果用户已经通过 Chrome 存储了通行密钥（Google 密码管理器），Custom Tab 就能访问它。用户还能看见真实的 URL 和安全指示，这建立了信任。性能通常更好——Chrome 可以在后台“预热”以便更快地加载。最重要的是，安全性强：由于它本质上就是 Chrome 应用，像 Google Safe Browsing 这样的功能保护了会话，而且您的应用不能将任意脚本注入到页面中（防止某些攻击）。

缺点是它要求用户已安装并更新了 Chrome（或支持的浏览器）。大多数 Android 用户都有，但在某些地区某些设备上，这可能是个问题。总体而言，如果您在 Android 上采用嵌入式 Web 方案，推荐为通行密钥流程使用 Chrome Custom Tabs，因为它们提供了整合与安全性之间的良好平衡。事实上，在很多方面，它们类似于 iOS 的 SFSafariViewController/ASWebAuthSession——利用默认浏览器进行身份验证。

（旁注：Apple 的 WKWebView 对应 SFSafariViewController 以及 Android 的 WebView 对应 CCT 之间有许多相似之处。Safari VC 和 Chrome Tabs 共享浏览器状态并提供更好的安全性，而 WKWebView/Android WebView 提供更多控制权但隔离了 Web 内容。对于通行密钥，共享状态（cookie、凭据存储）通常是人们所希望的，以确保能无缝地访问和创建通行密钥。）

无论您选择哪种实现方法，都必须满足特定的技术要求以启用通行密钥功能。本节提供有关配置众所周知的关联文件、iOS 授权和 Android WebView 配置的全面指南。

有关受管设备的注意事项： 在移动设备管理 (MDM) 策略控制凭据存储的受管设备上，通行密钥行为发生显着变化。有关在受管设备上测试通行密钥的信息，请参阅“在受管 iOS 和 Android 设备上的通行密钥”。

原生和嵌入式 WebView 流程需要关联文件，在您的应用和 Web 域之间建立加密信任。系统 WebView (ASWebAuthenticationSession) 和 Chrome Custom Tabs 不需要应用到站点的关联。

AASA 文件建立您的 iOS 应用和 Web 域之间的连接，使通行密钥可以跨两个平台工作。

文件位置：https://yourdomain.com/.well-known/apple-app-site-association

配置要求：

• 在您的域上的 /.well-known/apple-app-site-association 托管
• 通过带有有效 SSL 证书的 HTTPS 提供服务
• Content-Type：application/json
• 在 .well-known 路径上无重定向
• 包含您的应用的 Team ID 和 Bundle ID

示例 AASA 文件：

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

AASA 缓存和测试：

Apple 使用 CDN 积极缓存 AASA 文件（长达 24-48 小时），这可能会给开发和测试带来麻烦。在开发期间为了绕过缓存：

1. 在您的测试设备上启用开发者模式
2. 在 Xcode 中的关联域附加 ?mode=developer
3. 这会迫使 iOS 绕过缓存直接从您的服务器抓取最新的 AASA 文件

⚠️ 重要提示：不要在正式发布版本中使用 ?mode=developer。此参数仅供开发使用——在生产环境中使用它将阻止 iOS 正常检测您的 AASA 文件，从而破坏通行密钥功能。

验证：使用 Apple 的 AASA 验证器验证您的配置。

Android 使用 Digital Asset Links 验证您的应用与网站之间的关系。

文件位置：https://yourdomain.com/.well-known/assetlinks.json

配置要求：

• 在您的域上的 /.well-known/assetlinks.json 托管
• 通过带有有效证书的 HTTPS 提供服务
• Content-Type：application/json
• 包含您的应用的 SHA256 指纹（来自签名证书）

示例 assetlinks.json 文件：

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

验证：使用 Google 的 Digital Asset Links 生成器创建并验证您的配置。

iOS 应用需要正确的授权 (Entitlements) 以访问通行密钥功能。根据您的实施方法不同，其需求稍有差别。

授权文件（在 Flutter 应用中通常命名为 Runner.entitlements 或者在原生 iOS 项目中命名为 YourApp.entitlements）定义了由 Apple 系统授予的特定权限和功能。对于通行密钥，此文件配置 Associated Domains（关联域）。

文件位置：通常在您的 Xcode 项目中位于 ios/Runner/Runner.entitlements

原生实现和嵌入式 WebView 要求具备 Associated Domains 功能，以便将应用与您的网站域相链接。由于系统 WebView (ASWebAuthenticationSession) 是在 Safari 的环境下运行，因此不需要该功能。

在 Xcode 中的设置：

1. 在 Xcode 中打开您的项目
2. 选择您的应用目标 (target)
3. 导航至 "Signing & Capabilities" 选项卡
4. 单击 "+ Capability" 并添加 "Associated Domains"
5. 添加带有 webcredentials: 前缀的域

示例配置：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

多个域：如果您的应用需涉及多个域进行工作，您可能需要借助相关源请求 (Related Origin Requests, ROR)。

Android 嵌入式 WebView 支持通过两种截然不同的方式来实现通行密钥：基于 WebKit 的较新方式（5.3.1节）以及旧版的 JavaScript 桥接方式（5.3.2节）。系统 WebView (Chrome Custom Tabs) 不需要任何配置，凭证功能将自动运行。

Android 提供了官方 WebView 通行密钥样例，其展示了这两种实现途径。

集成包含原生通行密钥处理支持的现代版 WebKit。这种方法不仅提供了原生层次的 WebAuthn 支撑，还免去了自编桥接代码的工作。

官方样例： Webkit WebView MainActivity

要求：

• AndroidX WebKit 1.12.1 及其更高版本（推荐使用 1.14.0+）
• 已正确配置的 Digital Asset Links
• 具备支持 WebAuthn 能力的 WebView APK（需通过功能检测进行校验）
• 请注意：AndroidX Credentials 库对于实现 WebView WebAuthn 并无强制要求，它只在纯原生的实现环境下必须具备

具体实现：

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Check if Web Authentication is supported
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Enable Web Authentication
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Enable JavaScript
    webView.settings.javaScriptEnabled = true
}

关键点：

• 无需 JavaScript 桥接：WebAuthn 在 WebView 中原生运行
• 需要进行功能检测：请始终在运行期间通过 WebViewFeature.WEB_AUTHENTICATION 校验功能特性
• 不支持 Conditional UI：在嵌入式 WebView 下，mediation:"conditional"（输入框里的通行密钥自动填入功能）无法生效
• 后备策略：万一所需要素未能具备时，即可启用 Chrome Custom Tabs 来作替代方案

版本注记：

• 请使用 WebKit 1.12.1 或更新版本（1.12.0 版存留运行时可用性瑕疵）
• 具体的特性兼容性取决于客户侧设备里 WebView APK 的更新状态——倘若设备的 APK 版本过于陈旧，则无法将其特性暴露出来

在 AndroidX WebKit 1.12.0 发布之前，嵌入式 WebView 中并不存在原生的 WebAuthn 支持机制。这种传统的策略须使用一套自建的由 Web 层向 Native 层进行通信桥接的设计手法，用来应对那些仍缺失了原生 WebView WebAuthn 处理能力的终端设备的通行密钥验证问题。

官方样例：

• PasskeyWebListener (Bridge Handler)
• JavaScript encode utilities

适用场景：必须兼顾兼容较旧层级的 Android 系统平台或者是采用旧款 WebView 方案设备的那些场景。

研发团队须从下面择一操作：

1. 使用 Chrome Custom Tabs 或 Auth Tab（推荐方案）
2. 构建自设的定制版 JavaScript 桥梁以维系交互运行

要获取深入实施操作详述资料，务请细览 Android's Credential Manager WebView Integration guide。可是，在当前最新款型的应用软件开发里，我们强烈推崇采纳基于 AndroidX WebKit 1.12.1+ 所主导的具有原生属性的新途径作为开发准线。

推荐：使用带有 AndroidX WebKit 1.12.1+ 的原生 WebAuthn 支持。如果在运行时不可用，则回退到提供出色的共享凭据通行密钥支持的 Chrome Custom Tabs。

在原生应用中落地实施有关通行密钥验证的时候，构建起你的应用以及 Web 域间充分可被确认且相互能够保障信任的工作基石十分紧要。本节内容涉及怎样具体掌控单一作用域场景的问题应对法则，还有处置拥有众多相联系站点的复杂境况所需用到的相关源操作（ROR）。不仅如此，这里还将一并解答您如何验证您的“众所周知 (well-known)”关联配置文件的确得到精准部署并正稳健发挥功效的问题。

当应用程序仅依存于单一个独立域名运转的情况时（如：kayak.com），您的环境必需拥有如下配置项：

• 为 iOS 提供的一份 AASA 格式专用文件，其需位于 https://kayak.com/.well-known/apple-app-site-association
• 属于 Android 的一份 assetlinks.json 格式清单档，存放于 https://kayak.com/.well-known/assetlinks.json
• 配置 Associated Domains 授权属性为 webcredentials:kayak.com

相关源 (ROR) 是 WebAuthn 提供的一个特性，其能允许一组通用的通行密钥通用于多个有着联系的相关域（举例如：kayak.com、kayak.de 以及 kayak.co.uk 之间相互流通）。 ROR 使用各个对应站点中的 /.well-known/webauthn 端点来指定一系列已建立联系的确切源，注意这并非使用 AASA 或者 assetlinks 文件。

关键点：

• ROR 配置：每个域各自存管其位于 /.well-known/webauthn 目录底下的含有各种建立联系关联源属性的信息清单
• 专门应对应用程序所依赖的关联支持文件（比如：AASA/assetlinks）：只仅仅扮演映射对应关系的工具从而去把众多应用和他们对口相关联的站址进行捆绑挂钩
• iOS 18+ 的嵌入式 WebView：如果在所有相关细节都正确无误设定时，支持 ROR
• 授权使用关联域相关权限选项的 Associated Domains 属性：在里面列出需要您的应用能够正常实现相互鉴别操作认证的站点域名

配置示例：

假设您的应用程序能同时支持且运行在带有 kayak.com 以及属于另一个网域 kayak.de 时，那么必须符合如下两个网域：

• 各自网域需要放置拥有同样的 Team ID 及 Bundle ID 的专属独立 AASA 文件
• 在关联至您应用程式的相关 Associated Domains 属性的权利许可授予内作详尽清晰的注册条目罗列
• 拥有已经作过妥当的针对性部署处理并且保证确实具有被顺利提取并访问的能力的有关环境必须项众所周知的关联文件

在实际上线对外公布前，务必需检查去进行一系列周密的查证及评估等举措以便验核你那些关联配置里的必需件均得到严密及合适的精准架设部署安排以及能通过正常的获取调用进行运转。Apple 和 Google 给出各自用于依托 CDN 网路的有效测算核验链接 URL 方法用来核定文件能不能访问：

使用这些测试 URL：

• 单击各种相关的连接链点去检验是否属于 Apple/Google 所控制管理的访问获取服务已经顺利取得到相关配套文件
• Apple 其自带的 ?nocache=1 设置条件可直接指令强制提取其最新的一份记录信息内容进而避开原有可能从内容传送分配器 CDN 内产生阻碍的存储内容
• 只要关联的文件并非通过从上边那些连接链点的机制渠道路径取得到的内容信息那便无从被成功利用，同时你的应用端内的通行密钥功能也将不会生效
• 将上面 URL 模式里的 kayak.com 或 kayak.de 更换为您自身的网域名称

测试陷阱：确保所有域都具有正确配置的众所周知的文件。任何一个域中丢失的或配置错误的文件都会破坏该域的通行密钥功能。

更多信息：原生应用中的 WebAuthn 依赖方 ID

选择正确的实现方式依赖于你自身应用的架构、OAuth 条件及处理需求以及到底需要多大量的对当前通信状态会话的把握管控权能因素影响。依靠下面的这个抉择判断逻辑图，将给您引航，找到最为合用的那一条路径。

以下的判定参考流程结构旨在指引您如何依照属于您本身的应用架构特性所需及条件限定，从而选取一种能够贴合所期望要求的方法手段：

每条路径的快速参考：

• 基于 OAuth 的登录？ → 系统 WebView（ASWebAuthenticationSession / Chrome Custom Tabs）
• 在原生外壳中重用 Web 身份验证？ → 带配置的嵌入式 WebView（WKWebView / Android WebView + WebKit 1.12.1+）
• 构建原生优先？ → 原生实现（AuthenticationServices / Credential Manager）
• 有现成的 Web 身份验证需要重用？ → 采用系统 WebView 快速实现；否则使用原生的以获得最佳 UX

这是各种手段于至关要紧评判准则上的优劣展示评析表单：

维度解释：

• 创建通行密钥：指依靠这部分运作设计，对普通人群而言去构建自身所拥有的通行密钥是如何的轻便容易程度
• 使用通行密钥：运用早已存放现成有记录可用状态的通行密钥期间，身份认证操作运转的具体实际直观的用户体验环节
• 管理通行密钥：使用者借此观察检验、或者施予更新调节变更乃至完成删除清理操作等等过程状况
• 技术复杂度：包含前期构建开发投入精力的数量以及随之长久必须应付耗去的维系修理养护负担量
• OAuth 支持：对应评估手段处置调配诸如针对 OAuth2 或者 OIDC 安全通信准入许可凭条的操作处置是否能够做得游刃有余
• 设置时间：实施部署常规所需花去的阶段时期表

我们对此给予强力推介的首选方案：系统 WebView

当你的所属研发应用程序依附使用诸如 OAuth2、OIDC 这个级别的通行协定或者是依赖众多现行第三方社交平台诸如（类似 Google，GitHub 或者是 Microsoft 这类）当作实现账户注册凭据服务工具提供厂商渠道进行操作登录功能：

• iOS：建议优先利用 ASWebAuthenticationSession 其为了 OAuth 这一特殊运作准入认证做过极其针对性专业部署
• Android：选用可以毫无顿挫瑕疵接入并紧密对接各类所需服务保障 Chrome Custom Tabs
• 优点获益：缩减掉针对属于底层原始逻辑的原生代码，拥有极其通顺全自动运作特性的通行权限身份证书交接分配分享特性
• 部署运用：首先让负责对外部实现信息验证核对保障页添加配置进有关于 WebAuthn 功能，随即将它们通通经系统 WebView 接管并实施完整顺利调入及演示工作环节

实例：旅行应用（例如 kayak.com 和 kayak.de）使用 OAuth 进行身份验证。系统 WebView 允许他们通过其 Web 身份验证页面维护现有的 OAuth 基础架构，同时增加对通行密钥的支持。

我们对此给予强力推介的办法是采取：混合使用方式

初期先依靠着系统的 WebView 的机能用来进行一开始进行的带有附带各种相关信息的验证许可授权机制身份认证机制（OAuth）环节操作运作然后为了处置已经经历完毕顺利证实获准状态以后接手维持掌控接续工作的开展请过渡移交由给由嵌入式 WebView 当做主角负责来接力。

1. 初步初始进行的认证把关环节工作：这里安排依靠由隶属给到在系统之中的 WebView 所能贡献释放的一切职能专门只为了对于诸如涵盖有由其附带来的关于完成通行密钥的成功进入之类有关连属性在内的对应工作职责流程的完美执行。
2. 保持维系并管控通信互动过程的维持运作（会话操作状态之管理安排）：转换接棒给交由给归入到拥有深度附带性质所存在的所谓处于被处于内置状况性质的那类型式当下的被称其为嵌入式属性存在的这部分 WebView 担任处理那一些关于已被确保拥有被许可证实拥有权限获取的内容及后续相关事宜之用，在这里你可以实施你关于能够拥有权限能够自由随意掌握并指挥对由其关联生成出来相关附带着含有有关联附属性质属性关联特性的那个属于那些称呼叫作“cookie”，或者有关维持双方状态那些有指代意味代指通信全长连贯情况信息进行随意控制掌控。
3. 牵涉到底层搭建环境布置相关的具体实现所必要的硬性准则条项：对需要把对于系统的，再加上一并囊括关于内置属性的这两项全都必须被严格地彻底依照规范设置妥当不可含糊大意——关于对属于那个被称为隶属于是归入给在 Android 旗下范畴运作使用的应用体系中必须要注意并不能忽视对于是否在底层应用上是否含有被命名称为 AndroidX WebKit 并且级别必须处于或至少高于 1.12.1+ 以上之级号，（详请烦请再次查阅浏览翻看第 5 节的阐释细节）。

此方案对应能契合起能起到作用产生绝佳契机的场合境遇时机指代包括在什么时候什么特定时间背景节点情况等特定时候被运用进去： 此场景对专门属于被指代拥有那些需要利用依托借助经在已经利用并实施完成关于拥有基于有依靠对于对利用有具有 OAuth 通道身份性质方式认证之后的程序去负责操作验证处理过程后接续仍然有存在需要专门对于已获取准许被允许通过身份验明证身查验许可资格那些特指具有相关信息资料性质特质的资料信息属性的网页呈现内容，以及需要在期间存在一种带有必须且一定要进行某种极度具有直接性质能施予一定强力管治调度手法的能发挥对于操作能够有着主观管控行为能施展发挥干预权限能力的时候。

给予的最佳指导意见：直接奔向拥抱那些彻底采用具有全面原装纯正特性的方案，实行完全以走属于拥有由底层驱动机制所完全提供纯原生手段方式

若是直接开展一切由从最基本的初始基石源头之处直接构筑建立而起的话，或者是本就已经存在着具备那些具有带有直接性关联底层的呈现页界面的情况呢？那么就应该要坚决毫不迟疑彻底放开手脚去完全尽情地全面走上和尽数接纳全情融入纯原生之正道：

• iOS：尽情大胆利用具有名叫属于其阵营里的一套称之为能发挥相关功效功用机能体系架构机制框架称作为是名唤 AuthenticationServices。
• Android：这里就要去运用属于称作是被用来调遣负责管理掌握各种身份许可权资格证明的能起发挥调用作用机能在属于 API 里的那一套被唤作 Credential Manager API 去发号施令。
• 从中斩获能起着最为巨大效果作用益处及得到收效：可以斩获那种能称作得上市面能提供能够算得上属于最佳最优级层极优享的用者绝佳之感受，还有就是能做到让确认环节能够实现在时间点上能有着能呈现极为有着极高速反应特质拥有不需进行需等待并能具有瞬间极速完成属性等效能特质，而且能够做到让人享有着极为透彻到底全盘都掌控操持拿捏稳固在手中能操控大局不脱盘全面掌管性质特权。
• 专属其具有能占据决定性压倒性质专有独特能够带来的绝大优势特点： 请用那个有着叫做 preferImmediatelyAvailableCredentials 如此这样一项有着相关作用机能去直接负责呈现带有所谓能够自动运行并可进行提示遮罩覆盖能够展现出通行密钥提示覆盖功能模块面板的这样一种能附带在只要一开始启用了应用程序当刻便即时弹出显示自动出现提示覆盖通行密钥之层功能机制——像如此拥有这般这般极为特殊功效属性那可是绝对能够称得算是专门特意属于只能让在采用进行那些原装性质完全是由彻底在原生底层逻辑实行搭建操作手法方法的情况下，才可以专享特供能去独自占有享受拥有的特属专有的一类福利优待专属权呢！并且能有着绝对可以促使并能带携可以得到拥有能提升达成获取收获拥有极具带有高度极其夸张属于超高级别程度在最终有着那些具有极大比重极大规模转化率层级层面比数之保证喔
• 推荐相关那些属于具有带有那些拥有附带着那些对于软件具有能在协助可以实现快速方便完成构建开发性质的带有能起作用的提供协助相关带有提供属于相关起帮助作用工具的具有附带开发包功能的 SDK 工具集包包之推荐指南及有关的极力建言献策部分：非常建议能够多加采用借由 Corbado 提供相关对应不同阵线各自专有的一套 SDK 工具箱套件集包（譬如包含针对有对属于 iOS 以及有关于还有在 Android 这两端皆有提供对应的相符适配专属之用的开发协助功能包）的援助来极大地帮助推进加快加催使得那有关在进行各种相关的建造生成有关事宜进度得以大跨步加速向前推进迈步进行提升能够极大地促使提升有关于这研发之进程步调能有极其明显加速效果，附带着拥有那能针对曾对经曾历各种应对去处于那些极具严酷极其严峻真实实际在实地工作第一现场里处于在面临各种极为恶劣极严峻实际操作运营真切生产境地环境条件中有着能有能够曾经验证受受得过考验并能极其顺利摆脱妥当化解极其冷僻极为刁钻属于那种极度带有偏颇及带有边缘性质特性的棘手麻烦怪诞特殊少见少有发生罕有情况的应对解决处置能给予帮助摆脱窘迫困境难堪脱解摆脱能手并拥有应对如此困顿能起解决功效之能力能给予支持援助帮助的附带特优专属优质本领的优良品质的极佳功能特性附在上面呢！

针对那部分才刚刚出炉属于全新研发的新面市的各类软件和新式应用项目情况方面： 非常严肃及郑重地极其极其建议应该需能够把可以做到直接由在程序运行所依附依靠之源头底层那里入手实施建立构建组建构筑操作去安排实现登录工作相关处理操作行为等相关事项给全部在一开始之第一阶段首当其冲第一天里就把这相关事情通通给全部包办完成做好处理妥妥当当。借由这种这般做法去实施那是直接能使得您去获取可以享受占据占有处于那个可以获取夺得最最顶级绝妙最佳超优级优等能提供极致良好感受有着最优待遇的最顶级用户体验（UX）的绝对最佳位置而且还能够避开在之后在未来往后将不可避免可能会遭遇需要被面对的将会可能发生需要进行去迫使要实行实行要使得那些本属于在本来一直使用那些依赖通过借由属于处在那个由在通过使用那部分是借助是由使用了借助在基于由于使用了通过处于属于是建立构建在其之上之那个处于其上方上面之上属于带有被统称为是由这在那个处于这个被划入那在这是这被叫这是这是这个那这这这个在那那个这个是由它去借助是依赖的 WebView 上进行再往向向处于是在原生性质方向上去进行转变移植挪移改变操作转变移植。

给予最极力强力大力给出的方案及建设性给出之建言之最佳推荐应对处置之策之方法及对策办法：请采用逐步循序渐进逐渐慢慢过渡逐层分段分期分步有计划进行过渡移交方式办法手法手段策略计策谋划方式处理

下面呈现出的这一副图形示意解说图案将具体展现演示讲解出具体实施一步一脚印稳扎稳打一步步递进逐步逐阶段渐进式步步推进展开进行执行落实的整个具有带有着进行迁移过档过渡转移转变移步移动演进发展过程变迁的路径指示脉络指导图：

每一期的实施进程都是紧密搭建奠基于前一个阶层的基础之上作为根基来不断拔高，从而可以允准去进行逐渐积累稳健一点一滴日积月累去渐进缓慢提升实施各种各样的不断一点一滴增加积攒逐步进步的微小改进操作手法而能做到并可以确保丝毫也绝不轻易去对现如今仍在使用仍在当前进行活动现有使用人群造成干扰破坏搅乱带来负面惊扰的不佳情况发生。

参阅第 5 节以了解详情。

在原生应用里实施通行密钥相关的校验验证检测工作必须有赖建立起一套非常有调理有次序多层面复合架构多层次架构具有系统且完备的一套结构完整的方法理论支撑机制体系架构。务必请遵循以下关于测试工作的这个被称为检测理论之金字塔原则的这种被冠名冠以有如一种属于呈阶梯式具备有有着犹如某种某种像这类别类型的在上面犹如呈现有着形同有着这种被有着这样有这种这种像这样这类似如同像那像这是这被那一种被冠以有着犹如有着被称作有着是这那那种种测试这种具有被称为被命名这是那样有有着像金字塔那种式样的这么一种架构层级的有如像被像有有着这是在那样这是那种这样那么有着像这种具备的这种一种被称为叫那这样被称为那种叫有这是：单元测试（unit tests）（那些属于是针对只在隔绝在单一独立状态中处于封闭单独脱离状态中的局部具体运作功能运作之隔离部分的单独孤立状态的运作指令逻辑的封闭检测环节）、集成测试（integration tests）（那涉及在有关于需要需涵盖囊括起在关于对于处在需要在处在包含在涵盖于对涉及处在于有着处于是在要关于需要涵盖在属于存在于需要去应对进行模拟处在于需进行处理有关于存在需要涵盖需要针对在有需进行对于有包含需涉及在模拟的环境或仿真环境中需进行执行的有关关于需涉及进行实行之 WebAuthn 验证等整个的一套整个的各种一整套仪式的有关整体验证测试动作）以及系统层级之全方位总括验证整体运作功能运转综合统筹全通盘系统级别层级统揽系统连结运作全面系统级端至端全面测试（system tests）（针对处在于有着需要在拥有存在能够需要在关于处于那存在于关于那处于在实际现实拥有具备物理实体实际存有真实质地的实实在在具体实在真实物理环境实体物理设备现实硬件实机身上由一端到另一端彻底地贯通首尾端至端完全彻底到底端对端验证整个操作流程运作测试过程检验过程运作运作流程的全面全过程首尾接通顺畅度检验）。

不容错失必备关键主要不可或缺要紧不能忽略之绝对必要肯定必不可少肯定必须的各样各项核心核心类别分类必查主要要紧核查校验验证检测核心测验核验必要测试项目：

• 中心关键的核心的主轴运作骨干体验经历之经过主线的关键必经旅途体验经历阶段过程路线的核心必测必看骨干运行主干历程途径流转途径行程主要流转流程运转通道流程经过：包括对于进行那些所谓关于进行要完成处理诸如对于完成需要注册操作有关事项，涉及相关对应实施关于身份方面对确认检验识别等有关认证证明身份工作验证有关事务事宜环节，还有涉及有牵涉能够需要进行去需要有能实施横跨跨越穿插贯穿穿透不同各种不同设备跨设备之间流转沟通传输运转机制情况下的各种运作流通转接流通传递交换沟通流程流转运转操作动作，以及有针对有关需要需要把相关已经存有已经被存在那里已经存在已经被建立了的通行密钥把它给抹除抹消把它将其予以进行予以除掉实行抹除予以消除清理清理删除操作等各项操作。
• 对有关针对针对在各家对于各大各大关于处于针对在于对于隶属不同各类在各家在针对在关于属于对处于属于在各大各种平台平台所给予提供的支持支撑支持覆含涵盖面支持范围涵盖范围支持度平台层面遮盖涵盖覆及之情况进行覆盖之广泛度的检查：iOS（原生的部分属于原生范畴内原生那部分原生环境下原生形态机制下的），Android（属于原生范畴内的环境下的原生原生的），以及还需要去面对各种各样各式针对各种那些存在于拥有各类在运行处于运行运转状态于不同版本之间存在的存在拥有的在针对各种拥有各类种种各种版本处于各类有着属于种种的针对对关于各类型各种不同种有着种种处在拥有不同的系统层级各式种不同系统操作底层的运行系统操作系统环境当中的各式形形式式有各种具有存在各式版本不同的网页版浏览在页面网页上进行显示浏览器。
• 与所属相连相配套有关有牵涉关系关联领域有关系之对应挂钩结合有着涉及对于相互挂钩涉及域之间所属的域有联系挂靠隶属所属绑定联系有牵联关系的网域域联机关联关系关联联系对接联结绑定连接配置关系有无进行绑定联系之关联绑定关系挂钩连接关系：核验确认属于有关于在关于在是否对于是否去证明需要有关需要用于证明那些专门为了在苹果系统平台用来给针对在苹果平台上的（iOS）而准备设置设置装备妥当存放准备去被提供去使用的用上的叫做那个那用上那提供那准备在那用那叫那那些叫做属于名叫属于那个叫做名叫 AASA 的文件还有就是专属于用于是在为了属于是在用在属于那用于在针对有关针对在这在用在这个这在有关这在这个针对为了用在提供在那个专门提供这属于针对在这个那用于属于那个这个那这在给为用这个名叫专为用在此这个在这这个这针对用在那给为给是属于那给那 Android 这方属于这阵营的用来使用的那个名为名唤叫做数字资产链接 (Digital Asset Links) 的这些个那些个这部分文件究竟到底能不能能不能是否能否可不可是否可被确实可被获取有能够有可被可以具备有这有没有有着能去能否有着确实能能够能够有着能能够能够有确实是否是可以能能够被可确能被能能有着能被正常提取成功调阅获取提取拿得到可可被可获可得可获取调用去拿到存取获取查阅取得能够拿得到这能力权限能访问读取取得的权限能力状态能访问。
• 针对用户如果去产生执行发出一些关于中途要去中止叫停涉及终止对于做出中止要求提出取消退出对于取消有对于实行需要进行涉及到做出进行打断针对有关需要进行对于执行取消需要涉及对于进行进行有实行在实行取消退出的流转退出退出退出撤回叫停等打断终止退出停止中断放弃退出取消中止有关的流程对于用户取消流程运转情况时退出撤出流程等处理过程的操作测试：在遭遇被处于操作系统给进行有弹出提供出来所给出的提示窗口要求进行有关对由操作系统弹出进行要求提出询问提示有关在操作系统提出要求提示提示弹窗对话询问对话提问的弹出操作系统窗口的地方还有就在那些需要依靠有去要求涉及到要面对要去面对对依靠进行涉及到关于对于生物识别特征涉及要面对进行提供那些由涉及在呈现出有去面对需要有生物特征辨识生物信息识别识别画面界面的这些界面处，对进行关于去验证关于在此情况下有去执行去对于去测试实施测验有关有关于针对对于那些那些属于在那如果在此时此刻在如果此时发生用户决定做出去决定选择了需要提出取消退出实行放弃进行操作叫停进行做有做出进行选择放弃退出放弃决定的那种各种情形各种情况进行检验考察状况进行各种各类进行各种那些种种需要测试种种各类各种种种测试测验去校验各种情况这种情形去进行进行执行各种测试核验执行检验对于执行退出中止各种取消中断等各种各样的各类种种反应情况进行测试检验。
• 错误处理：后端故障、网络超时、凭证不匹配。
• 边缘情况：禁用屏幕锁、禁用 iCloud/Google 密码管理器。
• OAuth 流程：完整的端到端 OAuth + 通行密钥集成。
• 受管设备：MDM 控制的环境（参见受管设备测试）。
• 第三方管理器：1Password、Bitwarden、Dashlane 兼容性。
• 跨设备身份验证：QR 码流程和混合传输测试。
• 嵌入式 WebView 特定：如果使用嵌入式 WebView，请在 Android 上验证 WebKit 1.12.1+ 配置。
• 生产监控：成功率、故障和延迟仪表板。

要获取关于包含有实施去构建实行构建建立各种在包含进行搭建建立去进行对于构建执行落实自动化自动运行方式对策有关种种实施方案去关于自动去进行制定落实自动规划实施自动化建立战略种种自动化建立策略，包含囊括应对各种在各自不同的那在专属于那各类种各类各种不同属于各种那不同那有着在各种那不同种拥有不同各类平台各种具有存在属于在各有着在针对各样专属那各平台平台上拥有的各带有其独有专有那各异的独有的会遇上存在会发生存在发生的各类那各自会发生的会遇到的隐藏那些难以发现会在各种会遇到有有着会有发生那容易发生会在各种那容易掉入在有着存在那些坑在容易发生有有在有会在这在那些平台那些各种会存在容易犯错在有有关于种种那那会有陷阱各各各那些陷阱那些各种特殊会踩各种坑陷阱平台特定的一些容易踩坑容易踩中在会容易存在那有容易遇到有有在这那些有会有关于在这在那些有在这个在关于有各种特殊会踩的坑在这方面有在会有发生坑陷阱还有就是附送一份涵盖完整齐备彻底完整包罗所有的各种在事先进行在进行事前事在实施实行在进行在执行实行在在事在一开始最起初在一开始之前一开始先事前事前先事先一开始事前事在最最初先事先一开始就事前在去在实施事前开始实施操作在飞之前最先事先一开始事前进行事先实施的最先第一步前第一步一开始最先前第一先首先在事前先在实施在此前进行事前先在事前实施进行事先先最开始一开始的第一在此最先在这个这先在准备出发起飞在进入在进入到准备飞在开始在这个开始最起首准备进入实施之前准备之准备最先最起首最开始准备进行正式执行准备进行之前的那需要准备的在这在此之前在进入在这在开始那那那在这个这个在这在开始那在事先前实施之前事前事前实施之前起飞前在正式起飞前事前起飞前要在实施这起飞事前起飞之前在最先在这实施在事前飞行最前事前需在要起飞前的在起飞前的在飞行前在实行起飞前实施准备最最开始准备去检查在这起飞的各项要起飞前要在准备进行在这在事先需进行这最在这在飞行起飞前的事在起飞之前需要准备的事在要在正式起跑之前在准备起跑那最在正式准备发车起跑发车前那事最在这那在此事先那那事先起步那最在去最开始准备开始在最先第一那最初要在事先起先首先最要在去在这首先那去在这个在要在事先之前首先那需要这先在事前要在起之前的那最初起先在最先事前最初在之前那在最早以前在最先开始之前的需要去最先去要在事先在之前要先需要在之前事前在进行前所需事前在事前要在事前先在这个最初最前最起先去做的在这个需要那先这要在事先事前先在在在在在的事前起先最初在这个事先准备要在事前事前要在这事前起飞在这事前事要事前需要在此事需事在在这个要在在这个这在这个要在事在这要在事前要在事要在事前前事需在这在这在事在这事前在需事前这在这事这在事在这事前在这要在需事要事要事需事在这个要在需事前在此之前事前事前事前在在这事要需事要在这是要在准备就绪之前在这准备在这个需要事先起飞之前的在这个需要在这是这这是一个需要在之前要在这是这就是在要在事前先事事前去这在要在事前要在事前要在事前需要事这这在要在事前在这个要要在在这要在事在事前要需事在这要事前在这个在这事先需事要在要在事前事在要在事前前要在这个要事要在要在要在事前事前需要在这个这这在事前事在要在在这事需事事在在这个在事前在这个在这个在这事事前要在事先进行排查在这需要事先在飞行前在事前起飞事前事前起飞前在准备起飞前起飞前的事前起飞前的整个大全套清单在内的各样方方面面非常有着极其详尽提供极为细致的方方面面全部内容的一整套具备具备极其详尽指导的全面指南指引性质的各种指引有关详细各种相关提供全套完善细节指引指南详细极其详尽包含极其完整有着最详尽极详尽指南：在原生 iOS 与 Android 应用中测试通行密钥流程。

考虑在用户成功进行传统的登录（密码、OAuth）之后，提示用户创建通行密钥。这种循序渐进的转换方法：

• 不会破坏现有的身份验证流程
• 允许在用户拒绝时优雅地降级
• 随着时间的推移增加通行密钥的采用，而无需强迫用户更改
• 非常适合所有三种实施方法

示例：通过系统 WebView 进行 OAuth 登录后，显示原生提示：“使用面容 ID 启用更快的登录？” 如果接受，则通过系统 WebView 加载的网页创建通行密钥。

决定如何实施通行密钥（通过原生实施、系统 WebView 或嵌入式 WebView）是一项至关重要的设计选择，它会影响安全性、用户体验和开发复杂性。没有一种放之四海而皆准的答案。

对于基于 OAuth 的应用：系统 WebView（ASWebAuthenticationSession、Chrome Custom Tabs）是建议的起点。它提供出色的 OAuth 支持、最小的实施工作量和自动共享凭证。

对于原生优先的应用：越早原生化越好。原生通行密钥登录可提供最无缝的用户体验，并具有独家功能，如 preferImmediatelyAvailableCredentials，它可实现应用启动时的自动通行密钥覆盖——这是 WebView 实施无法提供的。随着 iOS 和 Android 现在为通行密钥提供一流的支持，实际的成功证明了其高采用率。工具（包括开源 SDK 和平台库）已经成熟，可以在合理的时间内完成原生集成。虽然您必须注意设备管理策略、跨设备同步和第三方提供商，但可以通过精心的工程设计和测试来管理这些挑战。结果是，应用登录以其轻松和快速让用户感到愉悦，同时显着提高了安全性。

对于嵌入式 WebView 框架要求：嵌入式 WebView 通常用于两种实际场景。首先，基于 OAuth 的应用通常使用系统 WebView 进行初始登录流程，然后切换到嵌入式 WebView 在需要会话控制的设置屏幕中呈现通行密钥管理选项——尽管有些应用通过对两个流程保持使用系统 WebView 来简化此过程。其次，在采用通行密钥之前就已将身份验证流程嵌入 WebView 框架中的应用将继续这种模式以保持一致性。具有原生 WebAuthn 支持的嵌入式 WebView (AndroidX WebKit 1.12.1+) 需要配置和设置（权限、授权、WebView 设置），但不再需要自定义 JavaScript 桥接代码。请注意，嵌入式 WebView 不支持 Conditional UI。当维护现有嵌入式身份验证模式或身份验证后屏幕需要会话/cookie 控制时，请选择此方法。

最终，原生应用中的通行密钥在用户便利性和安全性方面代表着巨大的飞跃。无论通过原生、系统 WebView 还是嵌入式 WebView 实施，它们都消除了用户的网络钓鱼风险和密码管理负担。像 VicRoads 的原生应用通行密钥集成等实际实施表明，当结合使用自动通行密钥覆盖等功能时，原生优先方法可提供最高的用户采用率和满意度。遵循用户友好型身份验证的最佳实践，并选择与应用架构匹配的实施方法（新应用的原生优先、OAuth 流程的系统 WebView 或现有嵌入式模式的嵌入式 WebView），您可以提供无密码的生物识别登录，从而真正实现通行密钥的愿景：为每个人提供简单、安全且令人愉悦的身份验证。

如果通行密钥在您的原生应用中不起作用，请根据实施方法检查以下常见问题：

• 通过带有有效证书的 HTTPS 提供服务
• 正确的 MIME 类型：application/json
• .well-known 路径上无重定向
• iOS：AASA 文件中的 Team ID 和 Bundle ID 完全匹配
• Android：SHA256 指纹与 assetlinks.json 中的签名证书匹配
• 依赖方 ID（Relying Party ID）与您的域匹配（无协议，无端口）
• RP ID 中没有尾部斜杠
• WebAuthn 源：https://your-domain.com（而不是 app://）

• iOS：在 Xcode 中使用 webcredentials:yourdomain.com 启用 Associated Domains 功能
• Android：在 AndroidManifest.xml 中声明 Digital Asset Links
• 用户启用了屏幕锁（生物识别或 PIN）
• 使用 Apple 的 AASA 验证器和 Google 的 Digital Asset Links 工具进行测试
• 验证 Runner.entitlements 文件包含正确的关联域

• iOS：使用 ASWebAuthenticationSession（推荐）或 SFSafariViewController
• Android：使用 Chrome Custom Tabs（不是普通 WebView）
• iOS：如果需要，请验证关联域已配置
• 测试 cookie/凭证是否与系统浏览器共享
• 验证 Web 身份验证页面具有适当的 WebAuthn 实现

• iOS：配置有适当的权限
• iOS：关联域包含所有相关域
• iOS：AASA 文件可访问且格式正确
• iOS：在开发期间使用 ?mode=developer 进行测试（在生产环境中将其删除）
• Android：项目中包含 AndroidX WebKit 1.12.1+（或更新版本）
• Android：对 WebViewFeature.WEB_AUTHENTICATION 的运行时功能检查
• Android：使用 WEB_AUTHENTICATION_SUPPORT_FOR_APP 调用 setWebAuthenticationSupport()
• Android：在 WebView 设置中启用 JavaScript
• Android：用户的 WebView APK 版本支持 WebAuthn 功能（使用功能检测，而不是操作系统版本）
• 不使用 Conditional UI（嵌入式 WebView 中不支持）
• 如果 WebAuthn 功能不可用，则回退到 Chrome Custom Tabs

• 检查用户是否处于活动状态（1Password、Bitwarden 等）的非默认凭证提供程序
• 验证提供程序是否支持通行密钥（并非所有密码管理器都支持）
• 使用平台原生的凭证管理器（iCloud 钥匙串、Google 密码管理器）进行测试

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• 通常意味着：缺少权限 (iOS) 或 WebView 功能不可用/未启用（Android 嵌入式 WebView）
• 检查：关联域配置、AASA 文件可访问性、WebKit 版本、功能检测、setWebAuthenticationSupport() 调用

没有显示通行密钥提示

• 可能意味着：AASA/assetlinks.json 未加载，WebView 类型错误，缓存了 AASA 文件
• 尝试：验证关联文件，在 iOS 上使用 ?mode=developer 进行测试，验证 WebView 类型

有关详细的调试，请参阅我们有关原生应用中的依赖方 ID (Relying Party IDs) 的文章。

一个常见的陷阱：具有受限访问权限（IP 白名单、仅限 VPN）的暂存环境将失败，因为 Apple 和 Google CDN 必须能够获取您的关联文件。

• AASA/assetlinks 文件可公开访问（无 IP 白名单，无 VPN 要求）
• 验证 Apple CDN 可以访问您的文件：https://app-site-association.cdn-apple.com/a/v1/your-staging-domain.com?nocache=1
• 验证 Google 可以访问您的文件：https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://your-staging-domain.com&relation=delegate_permission/common.handle_all_urls

具有生产 rpID 的暂存子域：

如果您的暂存环境（例如，stg.login.example.com）使用生产域作为 rpID（例如，example.com），AASA 查找将发生在 rpID 域，而不是您的暂存子域。这意味着：

• 将暂存应用包 (Bundle ID) ID 添加到您的生产 AASA 文件中
• 请注意，在暂存环境中创建的通行密钥将出现在生产登录流程中（可能引起混淆）

示例（多个环境共享一个 AASA）：

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

建议： 使用与其暂存域匹配的单独暂存 rpID，以避免在环境之间发生凭证重叠。这要求暂存域上有可公开访问的 AASA 文件。

?mode=developer 澄清说明：

关联域 (Associated Domains) 中的 ?mode=developer 参数绕过 Apple 的 CDN 缓存，但不会绕过可访问性要求。您的 AASA 文件仍必须可从设备中访问（不是通过 Apple 的 CDN，而是直接访问）。这在开发迭代 AASA 更改时有所帮助，但如果您的暂存服务器列入了 IP 白名单，这也没有任何帮助。

Corbado 原生 SDK：

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Flutter Package

平台文档：

• Apple: 支持通行密钥
• Google: 凭据管理器

验证工具：

• Apple AASA 验证器
• Google Digital Asset Links 生成器

关于 Corbado

Corbado 是面向大规模运行 consumer 身份验证的 CIAM 团队的Passkey 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 专家交谈 →

选择取决于您的身份验证架构。如果您的应用使用 OAuth2 或 OIDC，系统 WebView（iOS 上的 ASWebAuthenticationSession 或 Android 上的 Chrome Custom Tabs）实现的开发工作量最小，且无需设置关联文件。对于全新的原生优先应用，原生实现能提供卓越的用户体验；而嵌入式 WebView 则适合那些已经将身份验证嵌入到 WebView 框架中，并需要在登录后控制会话或 cookie 的应用。

SFSafariViewController 利用 Safari 的引擎，显示带有 SSL 指示器的 URL 栏，并提供网络钓鱼保护，使其在身份验证流程中更值得信赖。WKWebView 提供更多的 UI 定制，但其 cookie 存储与 Safari 隔离，需要 Associated Domains 权限和 AASA 文件来启用通行密钥，并且不显示 URL 栏，这降低了用户的信任信号。

Chrome Custom Tabs 会与用户的 Chrome 浏览器共享 cookie 和存储的凭据，这意味着在身份验证期间可以访问保存在 Google 密码管理器中的通行密钥。标准 Android WebView 具有隔离的 cookie 存储，不显示 URL 或 SSL 指示器，且由于存在网络钓鱼风险，Google 已明确禁止使用它进行 Google 帐户登录。

如果用户将 1Password 等第三方凭据管理器设置为其活动提供程序，它通常会拦截通行密钥的创建和存储，其优先级高于平台的原生凭据管理器（iCloud 钥匙串或 Google 密码管理器）。这意味着通行密钥可能存储在第三方应用而不是平台钥匙串中，从而影响跨设备同步和通行密钥管理行为。

当 MDM 策略禁用凭据同步时，通行密钥将绑定到设备，并且无法漫游到替换设备，这与典型的消费者场景不同。针对企业环境的应用应该规划后备的身份验证机制（例如密码或魔术链接登录），以处理用户收到新受管设备的情况。