Digital Credentials API 详解:网站如何连接身份钱包
面向企业的 W3C Digital Credentials API:网站如何在无需重定向的情况下向钱包请求数字身份,2026 年的浏览器支持情况,跨设备二维码,隐私,iframe 以及 Didit 如何将其用于 Google Wallet。

简而言之
Digital Credentials API 是一个 W3C 浏览器 API,允许网站通过单次调用(带有 digital 成员的 navigator.credentials.get())向数字钱包请求身份数据。浏览器和操作系统会显示钱包提示,随后钱包返回经签名且加密的响应。[1][2]
- 正如 Google 于 2025 年 10 月 3 日所宣布,Chrome 从版本 141 开始默认启用该功能;Safari 26 则支持该 API 用于 ISO mdoc 请求。[2][3]
- 它承载 OpenID4VP 或 ISO/IEC 18013-7 Annex C 请求,无需重定向,也无需您自建二维码。[1]
- Didit 使用它在五个国家/地区接受 Google Wallet 数字身份证件。[8]
长期以来,在线证明身份都意味着提供身份证件照片和自拍。手机钱包中的数字身份凭证改变了这一点,但网站仍需要一种安全的方式来连接钱包。Digital Credentials API 就是这座桥梁。
本指南为产品经理和架构师讲解该 API:请求流程、当前适用的平台、跨设备共享、隐私保护、iframe 以及 Didit 如何将其用于 Google Wallet。协议内部机制请见我们的 OpenID4VP 验证方指南,凭证格式请见 SD-JWT VC 与 mdoc。
什么是 Digital Credentials API
Digital Credentials API 是 W3C 联合身份工作组(Federated Identity Working Group)的一项规范。其最新版本是处于建议书(Recommendation)轨道上、日期为 2026 年 11 月 19 日的工作草案。[1] 该规范定义了一个 API,允许浏览器“协调数字凭证的出示与签发,例如驾照、政府签发的身份证件”。它基于 Credential Management Level 1 构建,且“旨在不依赖于凭证格式”。[1]
实际上,它就是网站已经用于通行密钥(passkey)的那次浏览器调用所支持的又一种凭证类型。在源试用期间,该 API 位于 navigator.identity.get();Chrome 正式推出时将其移至 navigator.credentials.get()。[2] 该 API 仅负责将请求传递给钱包并将响应传回;具体内容则属于底层协议。
| 层级 | 作用 | 示例 |
|---|---|---|
| 浏览器 API | 传递来自页面的请求并将响应传回 | W3C Digital Credentials API |
| 出示协议 | 定义钱包能够理解的请求与响应 | OpenID4VP 1.0, ISO/IEC 18013-7 Annex C |
| 凭证格式 | 响应内部经签名的数据结构 | ISO mdoc, SD-JWT VC |
| 平台 | 查找可以响应的钱包并显示选择器 | Android Credential Manager, iOS |
| 钱包 | 持有凭证,询问用户,对答复进行签名 | Google Wallet |
单个 Digital Credentials API 调用背后的技术栈。[1][2][4]
Digital Credentials API 请求流程
验证过程只需在您的网页与钱包之间往返一次。您的服务器构建请求,网页在用户点击时将其传给浏览器,加密后的答复再返回您的服务器进行核验。[2][6]
浏览器添加源信息,显示选择器
用户审核并批准
解密,核验签名
通过 Digital Credentials API 进行同设备出示的简化流程。[1][2][6]
每个请求都会指定一种协议,并携带该协议的 data 对象。浏览器必须支持规范表格中的所有出示协议:[1]
| 标识符 | 协议 | 请求结构 |
|---|---|---|
openid4vp-v1-unsigned | OpenID4VP 1.0 | 未签名请求 |
openid4vp-v1-signed | OpenID4VP 1.0 | 已签名请求 |
openid4vp-v1-multisigned | OpenID4VP 1.0 | 由多方签名的请求 |
org-iso-mdoc | ISO/IEC 18013-7:2025 Annex C | ISO mdoc 请求 |
W3C 注册表中的出示协议,2026 年 11 月 19 日的工作草案。[1]
在显示按钮之前,页面会检查 typeof DigitalCredential 和 DigitalCredential.userAgentAllowsProtocol()。[2][3] 响应以带有加密 data 有效负载的 DigitalCredential 对象形式返回,页面将其转发至后端。[2] 请求语法和响应模式属于协议问题,详见OpenID4VP 验证方指南。
为什么没有重定向
在此 API 出现之前,网站通过让用户离开页面来调用钱包:重定向,或交给应用的自定义 URI(在桌面端通常以二维码形式呈现)。Digital Credentials API 使用户停留在当前页面,并将响应返回至同一标签页。[2]
旧路径
重定向或自定义 URI
- 用户离开您的页面进入应用程序或托管页面
- 您的页面在桌面端自行绘制二维码
- 钱包从请求内容中获知发起请求的一方
- 每个钱包需要各自的链接格式
特定于方案
浏览器中介路径
Digital Credentials API
- 用户停留在您的页面上,浏览器显示提示
- 浏览器在桌面端绘制二维码
- 浏览器自行确定发起请求的源
- 单次调用,平台找到的任何钱包
W3C Digital Credentials
在使用该 API 之前与之后,页面如何调用钱包。[1][2]
最关键的区别在于源。规范要求浏览器使用“自身对文档源的判定”,而不是页面提供的源,因此“向用户展示的参与方”就是浏览器检测到的参与方。[1] 已签名的 OpenID4VP 请求也可以列出其预期的源;Google 的指南指出,这样设置是为了“防止中继攻击”。[6] 欧盟钱包架构对跨设备的自定义 URI 流程也指出了同一点,正如我们的依赖方指南所解释的那样。
2026 年末的浏览器与平台支持情况
支持情况取决于浏览器、操作系统以及请求的协议。该表格反映了 2026 年 11 月 20 日查阅的公开资料。
| 浏览器或平台 | 适用环境 | 出示 | 协议 | 来源 |
|---|---|---|---|---|
| Chrome | Android、Windows、macOS、Linux、ChromeOS | 自版本 141(2025 年 10 月 3 日)起默认开启 | OpenID4VP 和 Annex C | Chrome、W3C CG[2][5] |
| Edge | Android、Windows、macOS | 从版本 141 起 | OpenID4VP 和 Annex C | W3C CG[5] |
| Safari | iOS 26、iPadOS 26、macOS 26 | 已支持 | 仅支持 Annex C(org-iso-mdoc) | WebKit、W3C CG[3][5] |
| 其他 iOS 浏览器 | iOS 26 | 与 Safari 一样,它们基于 WebKit 运行 | 仅 Annex C | Chrome、W3C CG[2][5] |
| Firefox | macOS | 从版本 149 起 | 仅 Annex C | W3C CG[5] |
| Firefox | Android、Windows、Linux | 开发中 | 尚未支持 | W3C CG[5] |
| Android 应用 | Android 9(API 级别 28)及更高版本 | Credential Manager | 适用于 Google Wallet 的 OpenID4VP | Android、Google[4][6] |
W3C CG = W3C Web Identity and Credentials Adoption Community Group 的支持情况表。[5]
用户还需要一台兼容设备:搭载 Google Play services 24.0 或更高版本的 Android,或 iOS 26 或更高版本,以及支持该 API 的钱包应用。[2] Google Wallet 在 Android 9 及更高版本上通过 OpenID4VP 1.0 响应基于 ISO mdoc 的数字身份证件。[6] WebKit 指出,它尚无法在 iOS 应用的 Web 视图 WKWebView 中运行。[3] WebKit 还列出了一个已知问题:用手机扫描 macOS 上 Chrome 显示的二维码时,同时包含 OpenID4VP 和 Annex C 的请求可能会让 iOS 一直停留在加载指示器上。[3]
注意
支持情况随每次发布而变化。请在运行时检测功能和协议,并为其他所有用户保留备用路径。
同设备与跨设备
当钱包位于同一设备上时,Android 会显示匹配凭证的选择器。当钱包不在同一设备上时,浏览器会提示在手机上继续操作。[2][7]
1页面在点击事件中调用 API
在任何情况下请求均相同。
匹配的凭证在此设备上
同设备
平台选择器列出凭证;钱包在页面上方打开。
跨设备
浏览器显示自己的二维码;手机扫描该二维码并通过蓝牙近距离检查。
2响应返回到同一页面
经过加密,通过浏览器传输。
钱包提示出现的位置。[2][6]
Chrome 表示,扫描二维码会在计算机和手机之间建立“安全、端到端加密且防网络钓鱼的连接”,通过低功耗蓝牙(Bluetooth Low Energy)上的 CTAP 协议检查用户是否身在现场并控制这两台设备。[2] Google 针对 Google Wallet 补充了两个条件:必须开启蓝牙才能找到附近的设备,且跨设备流程“仅在合作伙伴实现 Signed Requests 时可用”。[7]
您的页面绝不绘制二维码。限制来自平台本身:iOS 不支持出示来自另一台设备的凭证,而 macOS 上的 Safari 仅传递 Annex C 请求,因此 OpenID4VP 请求无法经 Safari 到达 Android 钱包。[5]
隐私与安全:该 API 保护的内容
钱包不会返回完整文件的图像,而仅返回请求中指定的声明,并由签发方签名。Chrome 将这一原则称为“选择性披露”:网站“仅接收所需的最低限度信息”。[2]
| 保护措施 | 实际意义 | 来源 |
|---|---|---|
| 选择性披露 | 仅请求的字段离开钱包 | Chrome[2] |
| 用户手势 | 请求需要点击;网站无法静默或重复发起请求 | W3C[1] |
| 每次均需中介确认 | 平台选择器在每次请求时都会询问用户 | W3C[1] |
| 由浏览器设定的源 | 页面无法冒充其他网站 | W3C[1] |
| 加密响应 | 使用您的密钥加密;只有您的服务器才能解密 | W3C、Chrome[1][2] |
| 批准共享 | Google Wallet 在共享前会要求验证生物识别、PIN 或图案 | Google[7] |
Google 声明其不会在服务器上保存凭证相关数据。[7] 同意屏幕由钱包控制:Google Wallet 会显示验证方提供的名称、徽标和隐私政策,因此用户在共享前能看到发起请求的主体。[7]
有效签名可证明数据真实,但 Chrome 提醒开发者必须为其使用场景“验证签发方是否合适且可信”。[2] 按照 Google 的指南,处理 mdoc 响应的服务端工作包括:[6]
- 使用与请求匹配的密钥解密响应。
- 根据受信任的签发方根证书验证签发方的证书链。
- 对照签名的摘要核对每一个返回的值。
- 检查针对该会话的设备签名,该签名绑定了您的源。
在 iframe 内使用该 API:digital-credentials-get
许多验证流程在客户网站的 iframe 内运行。规范通过名为 digital-credentials-get 的策略控制功能涵盖了此情况,其默认允许列表为 'self'。[1] 仅当嵌入页面通过 iframe 的 allow 属性授予权限时,来自其他源的页面才可调用该 API:[1]
<iframe src="https://verifier-service.example.com" allow="digital-credentials-get"></iframe>
请注意
若无此权限,浏览器会拒绝 iframe 内的钱包请求,用户将无法看到任何提示。若在 iframe 中使用 Didit 的托管流程,请在 allow 属性中添加 digital-credentials-get,或使用 Web SDK 0.5.1 或更高版本。[10]
目前有哪些钱包支持响应
在 Android 上,系统会绘制选择器,具体显示哪些凭证取决于各钱包在 Credential Manager 中的注册方式以及请求内容。[7] Chrome 团队将 Google Wallet 称为早期采用者。[2]
注意
由于其他钱包也可以响应相同的调用,Google 建议使用通用按钮(例如“使用数字身份验证”),而不是具体某个钱包的名称。[7]
在 iOS 上,WebKit 表示该 API 可以接入 Apple Wallet 或注册为身份证件提供方(Identity Document Provider)的其他应用。[3] 在欧洲,EUDI Wallet 架构将基于 Digital Credentials API 的 OpenID4VP 和 ISO/IEC 18013-7 列为远程出示路径。有关注册方面的内容,请参阅 EUDI Wallet 依赖方指南。
Didit 如何帮助您通过 Digital Credentials API 接入 Google Wallet
Didit 负责运行 Google Wallet 的 Digital Credentials API 验证方端,作为其数字身份钱包产品支持的方法之一。Google Wallet 已在 Didit 的生产环境和沙盒环境中上线,支持在美国、英国、巴西、新加坡和台湾地区使用由护照创建的数字身份证件以及受支持的美国各州的移动驾照。[8] 产品详情:Google Wallet 身份验证。代码:集成指南。
- 托管流程。用户会看到“使用数字身份验证”,并在浏览器或 Android 原生提示中进行确认,无需重定向。该方式仅在浏览器可以发送已签名的 OpenID4VP 请求时显示;在其他情况下仍保留证件核验。[8][9]
- 独立 API。Didit 会返回一个就绪请求,供您的页面在点击事件中传递给
navigator.credentials.get(),或传递给 Android 上的 Credential Manager;完整流程请参阅集成指南。[9] - 核验项。Didit 根据受信任的签发方根证书核验签发方签名,根据已签名的摘要核验每个值,并核验针对您的源和此请求的设备签名。响应数据会加密传输给 Didit。[9]
- 结果。对于身份证件,在保证级别 Substantial(实质性)下提供姓名、出生日期、证件号码、到期日、签发国家和机构以及国籍。不会共享肖像照片。[8]
沙盒环境无需注册。每个生产环境应用只需在控制台中向 Google 注册一次(ID Verification 步骤、受支持国家/地区对应的 Google Wallet 行,以及 Register with Google),一次性设置耗时约一分钟。Google 自身的验证方 API 是免费的;Didit 运行该验证的费用为每次完成验证 $0.20,已取消、已过期或被拒绝的登录不收费。请查看定价。[7][8]
Didit 提供
- 已签名的请求以及向 Google 的注册
- 解密以及所有签名与源检查
- 同一会话中作为后备方案的证件核验
由您负责
- 您页面上的按钮和用户手势操作
- 嵌入该流程时的 iframe 权限
- 入驻决定及您的相关政策
核心要点
- Digital Credentials API 是一项 W3C 工作草案,通过
navigator.credentials.get()传递钱包请求。 - Chrome 和 Edge 支持 OpenID4VP 和 Annex C;Safari 仅支持 Annex C。
- 浏览器会设定源并绘制跨设备二维码。
- 在 iframe 内部,嵌入页面必须授予
digital-credentials-get权限。 - Didit 在五个国家/地区将其用于 Google Wallet 身份证件,并提供证件核验后备方案。
常见问题解答
什么是 Digital Credentials API?
一个 W3C 浏览器 API,允许网站通过 navigator.credentials.get() 从钱包请求数字凭证(如政府身份证件)。浏览器和操作系统会显示钱包提示。[1][2]
哪些浏览器支持 Digital Credentials API?
Chrome 从版本 141 起在 Android 和桌面端默认启用该 API,Edge 从版本 141 开始支持。Safari 26 仅支持 ISO mdoc 请求,Firefox 从版本 149 起在 macOS 上支持该 API,同样仅支持 Annex C。查阅于 2026 年 11 月 20 日。[2][3][5]
Digital Credentials API 可以在 iPhone 上运行吗?
iOS 26 上的 Safari 支持该 API 用于 ISO mdoc(Annex C)请求,且所有 iOS 浏览器均使用相同的引擎。Didit 的 Google Wallet 方式使用已签名的 OpenID4VP 请求,托管流程仅在浏览器能够发送此类请求时才显示该方式,因此在 iPhone 上该钱包选项会被隐藏,并转而使用证件核验。[3][5][8]
Digital Credentials API 和 OpenID4VP 是一回事吗?
不。该 API 是浏览器通道;OpenID4VP 是通过它传输的协议之一,此外还有 ISO/IEC 18013-7 Annex C。请求中指定其协议,钱包则以该协议进行响应。[1]
使用它需要源试用吗?
不需要。正如 Google 于 2025 年 10 月 3 日宣布的那样,Chrome 从版本 141 开始默认启用该 API。试用代码必须从 navigator.identity.get() 迁移到 navigator.credentials.get()。[2]
为什么该 API 需要用户手势?
规范要求瞬态激活(transient activation),因此网站无法静默或重复请求凭证。请在点击处理程序中调用该 API;在用户手势之外调用将会失败。[1]
不使用自建二维码时,跨设备共享是如何实现的?
浏览器绘制二维码,蓝牙检查确认手机在附近,钱包通过加密连接进行响应。Google Wallet 对此需要一个经过签名的请求。[2][7]
哪些钱包响应 Digital Credentials API?
目前包括 Google Wallet,以及通过 Credential Manager 接入的其他 Android 钱包。在 iOS 上,Safari 可以访问已注册的身份证件提供方。[3][7]
Digital Credentials API 可以免费使用吗?
是的。它是一项浏览器标准,并且 Google 表示其 Google Wallet API 完全免费。运行验证方端则另计费用:Didit 仅对已完成的验证计费。[7][8]
来源
- Digital Credentials,W3C Federated Identity Working Group,2026 年 11 月 19 日工作草案。
- Digital Credentials API: Secure and private identity on the web,Chrome for Developers,2025 年 10 月 3 日。
- Safari 26.0 中的 WebKit 功能,WebKit 博客,Digital Credentials API 章节。
- 请求数字凭证,Android Developers。
- 生态系统支持,digitalcredentials.dev,W3C Web Identity and Credentials Adoption Community Group,查阅于 2026 年 11 月 20 日。
- 在线接受来自 Google Wallet 的身份证件,Google for Developers。
- 通过 Google Wallet 验证数字身份证件,Google for Developers。
- 数字身份钱包,Didit 文档。
- 数字身份钱包独立 API,Didit 文档。
- 上下文内 iframe,Didit 文档。
Digital Credentials API 将钱包检查转化为单次浏览器调用;难点在于验证方端。在数字身份钱包页面查看 Didit 接受的每一个钱包,并在eID 验证页面查看各国 eID。