「国产安卓用不了 passkey」是个误解,我们自己也判错过

6 阅读9分钟

先说结论,省得你往下翻:

判断一台安卓机能不能用第三方 passkey,看的是系统版本和设置里有没有那个开关,不是看它是什么牌子。 华为是唯一一个框架层面就不支持的,其余主流国产 ROM 的新版本都能用——不能用的是旧版本。

这个结论来得有点曲折。我们自己一开始也判错了,在内部文档里写下过「国产安卓普遍跑不通,不建议赌 OPPO」,后来被一台 Reno 9 Pro 真机打脸,才把结论推翻重写。下面连这个弯路一起讲,因为它恰好说明了这事为什么容易判错。

一、先把两个开关分清楚

这是最多人踩的第一个坑:自动填充和 passkey 是两套独立的系统开关。

autofill_service    → 密码自动填充(Android 8.0 / API 26 起)
credential_service  → passkey provider(Android 14 / API 34 起)

把自己的 App 设成了默认填充服务,不代表它能当 passkey 提供方。两个设置项在系统设置里的位置、走的框架、要实现的 Service 基类全都不一样。

用 adb 一行就能看当前状态:

adb shell settings get secure autofill_service
adb shell settings get secure credential_service

在一台 Pixel 上这两个值是:

com.keymepass.android/com.keymepass.android.autofill.KeyMePassAutofillService
com.keymepass.android/com.keymepass.android.credential.KeyMePassCredentialProviderService

两个服务各管各的。如果你在排查「为什么填充好使但 passkey 不弹」,先看这里。

二、四条命令判断一台机器能不能用

我们把排查流程固化成了四条命令,拿到新机器照着跑一遍就知道结果:

# 1. 系统版本 —— 第三方 credential provider 是 API 34+ 专属
adb shell getprop ro.build.version.sdk

# 2. 当前的 provider 是谁(通常只有 GMS)
adb shell settings get secure credential_service

# 3. 🔴 关键:有没有「选择 provider」的设置页
adb shell cmd package query-activities -a android.settings.CREDENTIAL_PROVIDER

# 4. 系统有没有识别到你的 provider
adb shell dumpsys package <你的包名> | grep -A2 credential

第 3 条是整篇文章里最有用的一条命令。 它返回 No activities found 就说明:这台机器的框架可能活着,但 ROM 把 AOSP 的 provider 选择界面整个删了——用户没有任何入口把你勾选成 passkey 提供方。

代码全对、manifest 全对、系统也识别到你了,但用户就是选不上。这种情况从 App 侧无法绕过。

三、逐厂商实测图景

厂商 / ROM能用?实测情况
Pixel✅ 稳标配 Credential Manager,首选测试机
三星国际版✅One UI 完整实现 provider 选择
vivo(OriginOS)⚠️ 能用但有坑见下方「vivo 的中转层」
OPPO ColorOS 新版✅Reno 9 Pro 实测正常
OPPO ColorOS 14(旧)❌框架在,但 provider 选择 UI 被删(第 3 条命令返回 No activities found)
小米 HyperOS✅ 能用但魔改最多路径:设置 → 更多设置 → 语言与输入法 → 密码和账号。坑:创建时默认调 Google,要点「更多选项」才能存到第三方
华为❌ 框架级不支持纯 HMS 无 GMS,dumpsys credential 根本没有这个服务

来源说明:Pixel、Reno 8(ColorOS 14)、Reno 9 Pro、华为几台是我们或用户的真机结果;三星国际版、小米 HyperOS 的路径来自社区反馈与他人实测,我们没有对应机器,列出来供参照。

华为那条和其余几家不是一个层次的问题。 别家是「UI 入口被删」或「路径藏得深」,升级系统或换个版本就可能好;华为是整个 Credential Manager 框架不存在,不会随版本升级自动解决。

我们判错的那次

最初的结论是基于一台 Reno 8 / ColorOS 14 得出的,当时还顺手写了「不建议赌 OPPO」。后来用户拿 Reno 9 Pro 实测 passkey 正常,才发现问题出在哪:

当时对 ColorOS 15 的措辞是「未见明确加此特性的证据」——那是证据缺失,被我们错记成了否定结论。

一台老机器 + 一句「没查到」,变成了一整个厂商的否定判断。如果你也在做兼容性摸底,这个坑值得记一下:「没找到支持的证据」和「证明了不支持」是两件事。

vivo 的中转层

vivo 不用 AOSP 原生的 CredentialManager,塞了一个自家预装的 com.fido.client 做中转。第三方 App 会撞到这个报错:

The calling app 'com.fido.client' is not on the privileged list

解法是在自己的 CredentialProviderService 里,把 vivo 这个包按包名 + SHA-256 证书指纹加进信任白名单。不改的话 vivo 上注册必失败。

这不是我们独有的坑——Bitwarden 和 Keyguard 都踩过(Keyguard 的 PR #1121 就是修这个)。

四、ROM 这关过了,字节这关还在

假设你运气好,拿到一台 Pixel,provider 也挂上了。接下来会遇到一个极具迷惑性的失败。

症状

网页端注册报 NotAllowedError,提示「操作被用户拒绝」——但用户明明点了允许。再去认证,又报「用户名未注册」。

而本地看一切正常:

completeRegistrationRequest 成功
identity store 登记成功 success=true
pending / 本地库都写入了

本地全绿,RP 不认。 这是 passkey 调试里最容易卡住的地方:你的日志告诉你成功了,但它只能证明「系统回调回来了」,不能证明「RP 接受了」。

根因:authData flags 缺了 BE 和 BS

WebAuthn 的 authenticator data 里有一个 flags 字节:

UP = 0x01   用户在场
UV = 0x04   用户已验证
BE = 0x08   Backup Eligible(这个凭据可被备份/同步)
BS = 0x10   Backup State(当前确实已备份)
AT = 0x40   附带 attested credential data
ED = 0x80   附带扩展数据

我们原本注册时置 UP|UV|AT(0x45),断言时置 UP|UV(0x05)——BE 和 BS 都是 0。

问题在于:我们的 passkey 是跨设备同步的可发现凭据,私钥会同步到用户的其他设备。于是严格 RP(webauthn.io 就是)校验到一个矛盾:

你自称是同步 passkey,可是 Backup Eligible = 0?

判定非法,拒绝注册,navigator.credentials.create() reject 成 NotAllowedError。

修复很简单,但找到它花了很久:

注册 flags = UP|UV|BE|BS|AT = 0x5D   (原 0x45)
断言 flags = UP|UV|BE|BS    = 0x1D   (原 0x05)

三端(iOS / Android / Dart)必须逐字节一致。

一个容易一起做错的事:UV 不能恒置

改完 BE/BS 之后我们差点又犯一个错——把 UV 也恒置成 1。

BE/BS 和 UV 是两种不同性质的位:

  • BE/BS 是属性声明:这个凭据「能不能被同步」「是不是已同步」,是客观事实,置了就对
  • UV 是行为信号:本次操作「有没有真的做过用户验证」

如果为了省事把 UV 也恒置 1,那么在 DEK 缓存命中、本次根本没弹生物识别就直接签名的情况下,你就是在向 RP 谎报。正确做法是按本次是否真的弹了验证动态置位:

缓存直签,没弹验证  → UV=0,断言 flags = 0x19
弹了指纹 / PIN     → UV=1,断言 flags = 0x1D

五、还有七项值得逐条对一遍

定位 BE/BS 之前,我们把字节构造逐项和 Bitwarden 对照了一遍(它的实现在 1Password/passkey-rs,Android 和 iOS 经 UniFFI 共用同一份逻辑,是很好的对照标尺)。

这是最后沉淀下来的清单:

#检查项要求
1AAGUID固定 16 字节,两端逐字节一致。不一致是最隐蔽的拒因
2clientDataHash系统给了就直接签,别自造 clientDataJSON 再 SHA256
3BE / BS同步凭据必置,注册和断言都要
4UV动态置位,别恒 1(见上节)
5COSE x / ycanonical 键序,各固定 32 字节,不要截掉前导零
6fmt / attStmtfmt="none" 时 attStmt 是空 map {},不是 null
7signCount4 字节大端
8签名编码ECDSA P-256 DER,不是 raw r‖s(64 字节)
9challengebase64url 无 padding

第 2 条我们栽过一次相关的:registration / assertion 的 response JSON 漏了 clientDataJSON 字段。Android 官方 credential-provider 文档要求带一个占位符(base64url of {},即 "e30")——系统用 clientDataHash 做真校验,provider 不该自造,但这个占位字段不能缺。

第 9 条附近还有个分歧点值得说:signCount 到底该不该恒 0。

Bitwarden 选择恒 0,理由是同步 passkey 维护递增计数器会和多设备同步打架(RP 的 counter 回退检测可能误判)。我们选了维持递增——递增是 FIDO 规范里的合法做法,而改成恒 0 要动三端字节加存量数据,风险更大。

这个取舍后来在真机上验证了: Pixel 6a 上跑 webauthn.io,注册和登录都通过,RP 返回 You're logged in!。递增 signCount 没有被拒。

两种做法都成立,知道为什么选就行。

六、可以带走的判断清单

如果你也在给自己的 App 接 passkey provider,这几条可以直接用:

  1. 先跑那四条 adb 命令,特别是 query-activities -a android.settings.CREDENTIAL_PROVIDER——返回 No activities found 就别在这台机器上浪费时间了
  2. 别按厂商下结论,按系统版本 + provider UI 是否存在判断。「没查到支持的证据」≠「证明了不支持」
  3. 华为单独归类,它是框架级缺失,不会随版本解决
  4. 同步型 passkey 必须置 BE|BS,否则严格 RP 直接拒
  5. UV 要动态置位,缓存直签时如实报 0
  6. 本地回调成功 ≠ RP 接受,调试时以 RP 的返回为准,别信自己的日志
  7. 测 passkey 必须买真机。云真机实测走不通——要反复进系统设置改 provider、跑浏览器交互、触发生物识别弹窗,云机这几环都卡。二手 Pixel 6a 大约六百到九百块,能升到 Android 16/17,passkey、浏览器填充、autofill 一机全覆盖

本文的实测数据来自我们团队在 KeyMe Pass 上做 Android 端适配的过程。

顺便做个消歧,因为这三个名字实在太像了:KeyMe Pass 是我们做的跨端密码管理器(iOS / Android / 鸿蒙 / macOS / Windows / 浏览器扩展);KeePass 是那个著名的开源本地密码库;至于 KeyPass,网上大多数时候是 KeePass 的误拼。三者没有关系,数据格式也不互通——我们支持从 KeePass 的 XML 导入,但那是导入,不是兼容。

官网在 keymepass.com,上面那些踩过的坑,大部分都写进了产品里。