为您的 Android 应用选择合适的通行密钥实现方式

通行密钥已成为安全、人性化身份验证的标准,越来越多的服务在网站和 Android 应用中采用通行密钥。不过,当您开始向 Android 应用添加通行密钥时,通常会面临一个关键的架构问题:是直接调用原生 API、在浏览器标签页中打开现有的网页登录页面,还是在应用内 WebView 中运行通行密钥?

概览

您可以通过三种主要方法在 Android 应用中支持通行密钥:Credential Manager、Auth Tab 和 WebView。官方文档涵盖了每个选项的分步实现详情。选择一种既能最大限度地减少用户阻力,又能将开发和维护成本控制在可控范围内的架构,关键在于从宏观层面了解每种方案的特点和限制。本指南介绍了如何根据应用的设计和现有身份验证基础架构选择合适的方法。下表对这些方法进行了比较:

功能 Credential Manager “身份验证”标签页 WebView
推荐的使用场景 具有原生登录界面的应用 重复使用现有的网页登录页面,或 OAuth 或 OpenID Connect (OIDC) 身份提供方 (IdP) 现有混合 WebView 应用(仅限第一方网域)
界面和用户体验 原生操作系统底部动作条和键盘自动填充集成 用于身份验证的专用、精简浏览器标签页 带有原生操作系统底部动作条的嵌入式网页
自动填充和条件式界面 支持(Credential Manager 自动填充) 支持(WebAuthn 条件式界面) 不支持
会话和凭据共享 使用 assetlinks.json 和共享的 rpId 在网站和应用之间共享通行密钥(不共享 Chrome Cookie) 与 Chrome 共享 Cookie 和凭证状态(可使用无痕浏览功能停用) 使用 assetlinks.json 共享通行密钥,但会隔离 Chrome 中的 Cookie 和会话
Digital Asset Links (assetlinks.json) 需要在依赖方网域上提供 重定向 URI 网域必须支持 HTTPS 重定向(建议使用 HTTPS 重定向,而不是不需要 HTTPS 重定向的自定义 scheme) 必须在依赖方网域上使用(不能与外部或第三方 IdP 搭配使用)

Credential Manager

如果您的 Android 应用具有原生登录或注册界面,Credential Manager Jetpack 库是首选方法。

Credential Manager 的主要优势在于,它将通行密钥、密码和“使用 Google 账号登录”整合到一个精简的系统底部动作条中。用户登录时,只需点按一下即可完成生物识别验证,无需离开您的应用,从而减少登录阻碍。即使在用户关闭初始底部动作条并点按用户名或密码输入字段后,您也可以使用 PendingGetCredentialRequest 直接在键盘或下拉式自动填充建议中显示通行密钥、密码和“使用 Google 账号登录”选项。此回退机制提供与 WebAuthn 条件界面等效的原生自动填充集成。

Credential Manager 底部动作条,显示了通行密钥、“使用 Google 账号登录”和密码选项。
图 1. Credential Manager 将通行密钥、“使用 Google 账号登录”和密码整合到一个系统底部动作条中。

Credential Manager 还提供与现代 Web 通行密钥生命周期功能完全相同的功能。借助 Credential Manager,您可以执行以下操作:

搭载 Android 9(API 级别 28)及更高版本的设备支持通行密钥,而较低 Android 版本仍通过 Google Play 服务支持其他凭据(例如密码)。在 Android 14(API 级别 34)及更高版本中,Credential Manager 还可与用户选择的任何第三方凭据提供程序搭配使用。其他功能(例如基于 View 的自动填充集成 [PendingGetCredentialRequest] 和 Signal API)需要 Android 15(API 级别 35)及更高版本。

在网站和应用之间共享凭证

首先,请按照前提条件在您的网域中托管 Digital Asset Links (assetlinks.json) 文件,以关联您的网站和 Android 应用。通过 assetlinks.json 关联网站和应用意味着它们共享相同的依赖方 ID (rpId),因此在 Chrome 中通过您的网站创建的通行密钥可通过 Credential Manager 在您的原生 Android 应用中使用,而在您的应用中创建的通行密钥可在您的网站上使用。Credential Manager 会在您的网站和应用之间共享凭证;只有在您想要重复使用 Web 登录界面或 IdP 页面时,才需要使用 Auth Tab。

如创建通行密钥中所述,您还必须将服务器配置为验证 Android 应用来源(android:apk-key-hash:ENCODED_SHA256_HASH,使用 APK 签名证书的非填充式 Base64URL 编码 SHA-256 哈希进行格式设置)。如果您的应用具有原生界面,并且您希望通过与操作系统集成的体验使用通行密钥登录,请选择 Credential Manager。

“身份验证”标签页

许多服务都运行基于 OAuth 或 OpenID Connect (OIDC) 构建的身份提供方 (IdP) 微服务,或者希望在移动应用中重复使用现有的支持通行密钥的网页登录页面。过去,应用会使用自定义标签页来实现这些流程。从 Chrome 137 和 AndroidX Browser 1.9.0 开始,Auth Tab 提供了一个专门针对身份验证流程量身定制的专用浏览器标签页。

Auth Tab 显示了一个极简的浏览器登录界面,其中不包含通用浏览器菜单项。
图 2. Auth Tab 提供了专为身份验证流程量身定制的浏览器界面。

标准自定义标签页旨在作为通用应用内浏览器,会显示与登录无关的界面元素(例如分享菜单、书签和在 Chrome 中打开),这可能会分散用户的注意力。此外,您还需要在清单文件中声明 intent 过滤器,以接收身份验证后重定向、添加样板代码,并需要采取防范措施,防止恶意应用拦截 intent。

Auth Tab 解决了这些身份验证特有的挑战。它会移除不必要的浏览器界面(例如最小化按钮和分享菜单),并呈现一个仅包含基本登录功能(包括通行密钥和密码自动填充)的专注界面。Auth Tab 不通过操作系统 intent 进行路由,而是使用自定义架构或通过 Digital Asset Links 验证的 HTTPS 网址,将身份验证重定向直接传递到应用内回调,从而增强安全性并减少实现样板。

会话共享和自定义标签页回退

默认情况下,Auth Tab 还会直接与系统 Chrome 浏览器共享 Cookie 和凭据状态。通过这种共享,您的应用可以利用 Chrome 中活跃的登录会话,并按原样运行现有的 WebAuthn 实现,包括条件式界面和即时界面模式(相当于 Credential Manager 的 preferImmediatelyAvailableCredentials 的 Web 模式)。相反,如果您的用例需要不与浏览器共享 Cookie 或浏览记录的隔离身份验证会话,您可以通过调用 AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true) 来启用临时浏览。

虽然您将 androidx.browser:browser(1.9.0 或更高版本)与应用捆绑在一起,但 Auth Tab 是否在运行时运行取决于用户的默认浏览器。如果默认浏览器是低于 137 的 Chrome 版本或不支持 Auth Tab 的第三方浏览器,Auth Tab 会自动回退到启动标准自定义标签页。发生这种回退时,身份验证后的重定向会通过 AndroidManifest.xml 中的 intent 过滤器返回,就像在标准自定义标签页中一样,而不是通过 Auth Tab 的回调 (ActivityResultCallback) 返回。在生产环境中,Google 建议您事先使用 CustomTabsClient.isAuthTabSupported(context, provider) 检查默认浏览器支持情况,以便分支您的流程,或者保留清单 intent 过滤器,以便您的应用可以处理来自任一路径的结果。如需查看具体的后备实现示例,请参阅 Android 浏览器帮助程序。

OAuth 和 OIDC 安全要求

Auth Tab 仅保护和简化从浏览器返回应用的客户端重定向渠道,而不会自动保护 OAuth 或 OIDC 协议本身。尤其是考虑到自定义标签页的回退行为,您必须遵循适用于原生应用的 OAuth 2.0 (RFC 8252)。具体而言,结合使用 PKCE(用于代码交换的证明密钥,RFC 7636)以及 code_challenge 和 code_verifier 参数来防止授权代码被拦截,使用 state 参数验证来防止跨站请求伪造 (CSRF) 和会话固定攻击,并在 OpenID Connect 中使用 nonce 参数生成和验证来防止 ID 令牌重放攻击。有了这些保护措施,Google 建议将基于 Web 的登录架构从标准自定义标签页迁移到 Auth Tab。

WebView

有些应用是基于混合 WebView 架构构建的,在这种架构中,仅将登录界面拆分为原生界面 (Credential Manager) 或浏览器标签页 (Auth Tab) 是不切实际的。在这种情况下,您可以直接在 WebView 中启用 WebAuthn 支持。

如需在 WebView 中使用通行密钥,请将 AndroidX WebKit 库(androidx.webkit:webkit 1.12.0 版或更高版本)和 Credential Manager 依赖项(androidx.credentials:credentials 和 androidx.credentials:credentials-play-services-auth)添加到 build.gradle 文件中。接下来,使用 WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) 检查功能支持情况,并通过调用 WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP) 明确启用 WebAuthn 支持。 此配置会自动将 WebView 中网页的通行密钥创建和身份验证请求桥接到 Credential Manager。

网域和用户体验限制

与原生 Credential Manager 集成一样,您必须按照前提条件在依赖方网域中托管 Digital Asset Links (assetlinks.json) 文件,以便关联您的应用。您的服务器会收到 android:apk-key-hash:ENCODED_SHA256_HASH(采用 Base64URL 编码的 SHA-256 证书哈希)作为来源。由于此方法需要在依赖方网域上托管 assetlinks.json,以信任 Android 应用的签名证书,因此仅当您控制依赖方网域(第一方 Web 登录)时,此方法才有效。如果您的身份验证流程会重定向到外部或第三方 IdP,而您无法在其中为应用包托管 assetlinks.json,则必须使用 Auth Tab(或通过 Credential Manager 使用原生 Google 账号登录),而不是 WebView。

请注意两个用户体验和功能限制:WebView 不支持条件界面(当用户聚焦于输入字段时,mediation: "conditional" 自动填充集成),并且不会与系统 Chrome 浏览器共享 Cookie 或登录会话。由于这些限制,Google 建议在设计新的身份验证流程时使用 Credential Manager 或 Auth Tab。不过,如果您想在不进行重大架构更改的情况下,为现有的第一方混合应用添加通行密钥支持,可以将通行密钥与 WebView 集成。

摘要

从应用当前的界面和身份验证基础架构入手,有助于您选择合适的通行密钥方法:

  • 如果您的应用具有原生登录界面,并且您希望获得与操作系统集成的体验,而无需切换到浏览器界面,请选择 Credential Manager 以使用通行密钥登录。
  • 如果您运营 OAuth 或 OIDC IdP 微服务、重定向到外部 IdP,或者想要重复使用现有的已启用通行密钥的网页登录页面(包括条件式界面)并与 Chrome 共享活跃浏览器会话,请采用身份验证标签页,并实现适用于原生应用的 OAuth 2.0 (RFC 8252) 中的安全要求,特别是 PKCE、state 和 nonce。
  • 如果您的应用基于混合 WebView 架构构建,其中登录必须在嵌入式第一方 Web 界面中进行,请使用 WebView,同时考虑缺少条件界面支持和隔离 Cookie 的情况。

后续步骤