数字凭据 API：在网络上安全且私密地验证身份

Natalia Markoborodova

José Luis Zapata

发布时间：2025 年 10 月 3 日

我们很高兴地宣布，从 Chrome 141 开始，Digital Credentials API 现已默认启用。此外，iOS 26 还为 Chrome 和其他浏览器添加了对 Digital Credentials API 的支持。此 API 可为网络上的身份验证带来新的安全性和隐私保护水平，让网站能够以标准化方式向用户请求和接收可验证的信息。

在成功完成源试用后，数字凭据 API 现在支持在 Android 上进行同一设备凭据展示，以及在桌面版 Chrome 上进行跨设备展示。

背景

到目前为止，在线验证身份一直是一个复杂的过程，通常需要用户上传身份证件的扫描件。这种做法通常意味着共享的数据量超过了必要范围，这会给用户带来严重隐私问题。对于开发者而言，这也带来了风险，因为他们必须确保自己的解决方案能够以安全且保护隐私的方式处理和存储通常不一致的敏感数据。

与此同时，eIDAS 2.0 等法规要求政府向公众提供数字身份识别方式。这些数字身份钱包必须能够存储各种凭据，包括身份和年龄证明。 在线服务提供商可以请求这些凭据来验证用户身份。

W3C 的 Web 标准社区认识到数字凭据在满足用户对隐私保护的需求和开发者对验证用户数据的需求方面的潜力，因此开发了一种解决方案：Digital Credentials API。数字凭据 API 旨在通过引入用于验证用户信息的内置接口来解决此问题，与替代方案相比，该接口可提高安全性、隐私保护能力和用户体验。借助此 API，用户不再需要将身份证扫描件等敏感文档上传到多个网站。网站可以仅从可信的签发机构请求所需的特定加密签名数据，从而与用户建立信任关系。

核心功能

数字凭据 API 基于三项核心原则构建：隐私保护、跨平台支持和标准化。

隐私权

数字凭据 API 可增强在线隐私保护和安全性。它允许用户向网站出示移动钱包中的数字身份证件，以验证特定事实，而无需披露基础敏感数据。例如，该 API 可以在不透露用户完整出生日期的情况下，验证用户是否年满 18 周岁。这种“选择性披露”原则可确保网站仅接收必要的最少信息。

数字凭据 API 还与零知识证明 (ZKP) 协议（例如 Google 的 Longfellow ZK）兼容，该协议通过返回加密证明来确保用户隐私，证明某个身份断言为真，而不会泄露任何其他信息。

跨平台支持

数字凭据 API 旨在支持不同的平台，以便用户可以在不同设备上方便地出示经过验证的信息。

在 Android 上：提供内置的用户界面，允许用户从已安装的钱包应用中选择凭据。

在桌面设备上：用户可以向桌面浏览器中的网站出示移动钱包中的凭证。通过扫描二维码，系统会在桌面设备和移动设备之间建立安全、端到端加密且防钓鱼的连接。此连接使用 CTAP 协议通过 BLE 验证用户是否在附近，确保用户在场并能控制两部设备。

标准化

互操作性至关重要。在 Chrome 中，数字凭据 API 是独立于协议平台的，并且与各种展示协议兼容，例如 OpenID4VP 和 ISO 18013-7 的附录 C。Apple 还从 Safari 26.0 开始支持数字凭据 API。

此外，数字凭据 API 基于 Android 中内置的凭据管理支持和不断壮大的兼容钱包生态系统。Google 钱包是早期采用者，Samsung 钱包和 1Password 也即将提供支持。

自源试用以来，有哪些新变化？

对于之前参与过源试用的开发者，您会发现数字凭据 API 已从 navigator.identity.get() 移至 navigator.credentials.get()，这与凭据管理 API 的更广泛的身份统一工作保持一致。 此外，providers 参数已重命名为 requests，request 已重命名为 data。

实现

集成 Digital Credentials API 涉及两个主要步骤：功能检测和请求凭据。开发者还应实现自定义逻辑，以确定其应用是否可以使用凭据。

功能检测

在显示“使用数字凭据进行验证”按钮之前，请检查用户的浏览器中是否提供 Digital Credentials API。

if (typeof DigitalCredential !== "undefined") {
  // Digital Credentials API is supported
} else {
  // Digital Credentials API is not supported
}

申请凭据

请求凭据需要调用 navigator.credentials.get() 并提供 digital 参数。在数字凭证类型中，添加一个 requests 数组，其中包含具有以下基本参数的 DigitalCredentialGetRequest：

• protocol：使用字符串指定交换协议。例如，"openid4vp" 或 "org-iso-mdoc"。检测浏览器是否支持相应协议，如下所示：

  if (DigitalCredential.userAgentAllowsProtocol("example-protocol")) {
      // Create a request with this protocol
    } else {
      // Protocol is not supported
  }
  

• data：一个对象，其中包含数字钱包应用针对指定协议接受的参数。对于 "openid4vp"，参数在 W3C 数字凭据 API 规范的 OpenID 可验证演示 (OID4VP) 中定义。

  try {
    const digitalCredential = await navigator.credentials.get({
      digital: {
        requests: [{
          protocol: "openid4vp-v1-unsigned",
          data: {
            response_type: "vp_token",
        nonce: "[some-nonce]",
            client_metadata: {...},
        dcql_query: {...}
          }
      }]
      }
    });
  
    // Decrypt payload respons and verify credentials on the backend
    const response = await fetch("/verify", {
      method: "POST",
        body: JSON.stringify(digitalCredential.data),
        headers: {
            'Content-Type': 'application/json'
        }
    });
  } catch (e) {
    // Handle errors, such as the user canceling the request
    console.error(e);
  }
  

例如，如需请求用户的姓氏、名字以及一个布尔值（用于指明用户是否年满 21 周岁），您可以指定以下载荷：

{
  protocol: 'openid4vp-v1-unsigned',
  data: {
    response_type: 'vp_token',
    nonce: '[some-nonce]',
    // Contains the Verifier metadata values, including supported credential formats and response encryption public key
    client_metadata: {
  // Supported credential formats. Refer to the documentation for specific values
        vp_formats_supported: {...},
   // Public key(s). Refer to the documentation for more detail.
        jwks: {...}
    },
    dcql_query: {
      // A wallet will try to find credentials it holds that match these definitions.
      credentials: [
        {
          // A locally unique identifier for this credential definition within the query.
          id: "cred_vc",
          format: "dc+sd-jwt",
          meta: {
            // 'vct_values' specifies the Verifiable Credential allowed type.
            // In this case, it's a European Digital Identity (EUDI) Personal Identification Data (PID) credential.
            vct_values: [
              "urn:eudi:pid:1"
            ]
          },
          // 'claims' is an array of specific data that's being requested.
          claims: [
            {
              // The path ["age_equal_or_over", "18"] corresponds to accessing `credential.age_equal_or_over['18']`.
              path: [
                "age_equal_or_over",
                "18"
              ]
            }
          ]
        }
      ]
    }
  }
}

在此示例中，client_metadata 必须指定支持的格式列表。请参阅规范，了解可以使用哪些值。在 client_metadata 中设置的可选 jwks 值必须包含用于加密响应的公钥。您还可以查看演示代码，了解更多示例。

以下是加密的 DigitalCredential 对象响应载荷的示例：

{
    // This is an example for a response using an OpenID4VP protocol.
    // The format of the 'data' object will differ for other protocols.
    "protocol": "openid4vp-v1-unsigned",
    "data": {
        // To decrypt this JWE payload, use the private key.
   // The decrypted payload will be a JSON object containing the
       // Verifiable Presentation in the 'vp_token' claim.
        "response": "[jwe-token]"
    }
}

在此示例中，系统请求使用 openid4vp-v1-unsigned 协议获取凭据，并且响应的 data 属性中包含 response。

解析响应的具体方式取决于协议。您通常需要：

1. 解密响应载荷。解密方法取决于所使用的协议。请参阅如何解密 openid4vp（使用 JWE）和 org-iso-mdoc（使用混合公钥加密）的载荷。
2. 验证签名和签发者。如需了解详情，请参阅在线接受数字凭据文档。

如需查看不同协议的代码示例，请查看演示代码或实时托管版本。

验证对颁发者的信任

数字凭证的加密签名可证明凭证的真实性。不过，开发者必须验证签发者是否适合其特定使用情形且值得信赖。例如，为了提供大学学生折扣，电子商务网站会要求用户提供经认可的大学颁发的凭据，并拒绝任何其他实体签发的凭据。验证对签发者的信任的常见方法是维护一个已批准的签发者列表，并拒绝任何不匹配的签发者。

开始使用

准备好开始构建项目了吗？以下是您需要了解的情况。

• 可用性：Chrome 141 或更高版本默认在不同平台上启用 Digital Credentials API。
• 前提条件：用户需要使用兼容的设备，例如搭载 Google Play 服务 24.0 或更高版本的 Android 设备，或者搭载 26 或更高版本的 iOS 设备。设备必须安装支持 Digital Credentials API 的数字钱包应用，例如 Google 钱包或演示钱包。
• 试用演示：了解用户体验并测试实现情况的最佳方式是使用 Chrome 141 或更高版本试用实时演示，网址为 https://verifier.multipaz.org。

资源

如需了解详情，请参阅以下资源：

• 开发者指南： Digital Credentials API
• 规范： W3C 数字凭证
• Android 支持： Android 对数字凭证的支持

分享您的反馈

现在，数字凭据 API 已发布，我们希望了解您使用该 API 构建应用的体验。您可以提交问题来分享您的反馈或报告任何 bug。