正在接受 Google 钱包中的身份证件

在线

在应用内和网站流程中均可接受数字身份证件。 如需接受 Google 钱包中的凭据，您需要：

  1. 按照提供的说明，使用应用或网站进行集成
  2. 填写此表单，申请接受 Google 钱包中的凭据，并同意相关服务条款。

前提条件

如需测试身份证件展示功能，您必须先使用预期的测试账号注册公开 Beta 版计划。然后，向您的专属 Google 联系人提供后续详细信息。

  • 服务条款链接
  • 徽标
  • 网站
  • Play 商店软件包 ID（适用于 Android 应用集成）
  • 用于加入公开 Beta 版的 Gmail ID

支持的凭据格式

目前有几种拟议标准定义了数字身份证件的数据格式，其中两种标准在业界获得了广泛的关注：

  1. mdocs - 由 ISO 定义。
  2. W3C 可验证凭据 - 由 W3C 定义。

虽然 Android Credential Manager 支持这两种格式，但 Google 钱包目前仅支持基于 mdoc 的数字身份证件。

用户体验

当应用请求身份属性时，会发生以下流程：

  1. 凭据发现：应用会查询可用的钱包，以确定能满足请求的凭据。然后，Android 会显示系统界面选择器，显示要共享的信息。这样，用户就可以在了解情况的前提下决定使用哪种凭据。

  2. 用户选择和钱包互动：用户选择凭据，Android 会调用相应的钱包应用来完成交易。钱包应用可能会显示自己的意见征求界面，或要求进行生物识别确认。

输出：如果用户同意，系统会将所选身份凭据与发出请求的应用共享。如果用户拒绝，系统会返回错误。

应用内

如需从 Android 应用请求身份凭据，请按以下步骤操作：

更新依赖项

在项目的 build.gradle 中，更新您的依赖项以使用 Credential Manager（Beta 版）：

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-alpha05")
    // optional - needed for credentials support from play services, for devices running Android 13 and below.
    implementation("androidx.credentials:credentials-play-services-auth:1.5.0-alpha05")
}

配置 Credential Manager

如需配置和初始化 CredentialManager 对象，请添加类似于以下内容的逻辑：

// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = IdentityCredentialManager.Companion.getClient(context)

请求身份属性

// Retrieves the user's digital identites from wallet apps for your app.
val getIdentityCredentialOption = GetDigitalCredentialOption(
    requestJson = requestJson, // this is what partners needs to set, example JSON specified below
)
val result = credentialManager.getCredential(request = GetCredentialRequest(credentialOptions, ...)

应用调用方以 JSON 字符串的形式提供所有 IdentityRequest 参数。此处，它表示为 CredentialOption 的 requestMatcher 参数。Credential Manager 不关注该 json 的内容。此 JSON 请求会直接传递到电子钱包，然后电子钱包负责解析该请求，并确定哪些凭据可以满足该请求。完整的实现可在示例应用中找到。

我们预计 W3C 会将此 JSON 请求定义为 Web API 的组件。这种标准化将使浏览器能够直接将请求传输到 Android。

下面是一个 mdoc 请求示例，以便您大致了解该请求的样子：

{
  "selector": {
    "format": [
      "mdoc"
    ],
    "doctype": "org.iso.18013.5.1.mDL",
    "fields": [
      {
        "namespace": "org.iso.18013.5.1",
        "name": "family_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "given_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "age_over_21",
        "intentToRetain": false
      }
    ]
  },
  "nonce": "3cydsUF9xNFyBDAAWOct09hEeSqrFX2WB2r0G6f8Ol0=",
  "readerPublicKey": "BApmGdElal2-1dtafsdHVRa1EpAWZfhlQj_iof2I8L3V8_dCK1gVR0_12E4ZSQ2LcqXRd4zxVeKEqU1wUSgGWUU="
}

响应会返回 W3C 定义的 identityToken（JSON 字符串）。钱包应用负责构建此响应。

示例：

{
    "token": "<base64 encoded response>"
}

发送令牌并在服务器上进行处理

收到 identityToken 后，您的应用应将其传输到应用服务器进行验证。第一步是将令牌从 base64 格式解码。生成的字节数组表示 CBOR 数据，该数据遵循以下 CDDL。

CredentialDocument = {
  "version": tstr,       // Set to "ANDROID-HPKE-v1"
  "pkEm": bstr,          // Public key, in uncompressed form
  "cipherText": bstr     // The encrypted data
}

下一步是使用适用于 Android 的接力结构计算 ISO/IEC 18013-5:2021 中的 SessionTranscript：

SessionTranscript = [
  null,                // DeviceEngagementBytes not available
  null,                // EReaderKeyBytes not available
  AndroidHandover      // Defined below
]

AndroidHandover = [
  "AndroidHandoverv1", // Version number
  nonce,               // nonce that comes from request
  appId,               // RP package name
  pkRHash,             // The SHA256 hash of the recipient public key
]

cipherText 使用 HPKE 加密。如需对其进行解密，请使用 SessionTranscript 作为额外的身份验证数据，以及之前生成的 EC 私钥和以下设置：

  • KEM：DHKEM(P-256, HKDF-SHA256)
  • KDF：HKDF-SHA256
  • AEAD：AES-128-GCM

生成的明文是 ISO/IEC 18013-5:2021 中定义的 DeviceResponse CBOR 字节。DeviceResponse 必须根据 ISO/IEC 18013-5:2021 第 9 条进行验证。这包括几个步骤，例如验证 mdoc 是否来自可信发行者，以及响应是否由预期设备签名。OpenWallet Foundation Identity Credential 项目中的 DeviceResponseParser 类可用于此验证流程的一部分。

Web

如需在 Chrome 上使用 Digital Credentials API 请求身份凭据，您需要注册 Digital Credentials API 源试用。

现场互动

若要接受 Google 钱包中的身份证件，请按以下步骤操作：

  • 构建或获取读取器，以接受 ISO 18013-5 定义的 ID
  • 将 IACA 证书加载到读卡器中，以确保接受的身份证件真实无误
  • 测试您的解决方案
  • 在 Google 电子钱包中注册您的应用

构建或获取读取器，以接受 ISO 18013-5 定义的 ID

Google 钱包中的身份证件是根据移动驾照的 ISO 18013-5 标准实现的。它们使用基于 NFC 或二维码的互动以及 BLE 作为数据传输机制，因此任何能够实现该标准的各个方面的设备都可以充当读卡器，甚至包括移动应用。由于该标准是开放的，因此市场上有多个第三方实现。此外，您还可以根据需要直接实现该功能。

如需有关如何自行实现此功能的指导，请参阅我们的开源参考读取器 Android 应用，该应用实现了 ISO 标准，可以接受来自 Google 钱包的 mDL。

您可以先构建并运行参考阅读器应用：

  • 克隆参考应用代码库
  • 在 Android Studio 中打开项目
  • 在 Android 设备或模拟器上构建并运行 appverifier 目标。

将 IACA 证书加载到读卡器中，以确保接受的身份证件真实无误

如需验证真实凭据，您需要在钱包中拥有由受支持的发卡机构签发的身份证件。下面列出了 Google 钱包支持的发卡机构，以及用于验证的证书链接。

测试您的解决方案

如需测试您的解决方案，请构建并运行我们的开源引用持有器 Android 应用。 以下是构建和运行参考持有者应用的步骤：

  • 克隆参考应用代码库
  • 在 Android Studio 中打开项目
  • 在 Android 设备或模拟器上构建并运行 appholder 目标。

（可选）在 Google 钱包中注册您的应用

请填写此表单，在 Google 钱包中注册您的应用。