请求服务 REST API 出示规范

项目
10/24/2024

Microsoft Entra Verified ID 包括请求服务 REST API。使用此 API 可以颁发和验证凭据。本文详细说明了用于出示请求的请求服务 REST API。出示请求要求用户出示可验证凭据，然后验证该凭据。另一篇文章介绍了如何调用请求服务 REST API。

HTTP 请求

请求服务 REST API 出示请求支持以下 HTTP 方法：

方法	说明
POST	带有本文中指明的 JSON 有效负载。

请求服务 REST API 出示请求需要以下 HTTP 头：

方法	值
`Authorization`	将访问令牌作为持有者令牌附加到 HTTP 请求中的授权标头。例如 `Authorization: Bearer <token>`。
`Content-Type`	`Application/json`

构建对请求服务 REST API 的 HTTP POST 请求。 URL 中不再需要 tenantId，因为它在 access_token 中显示为声明。

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

以下 HTTP 请求演示了对请求服务 REST API 的出示请求：

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

需要拥有以下权限才能调用请求服务 REST API。有关详细信息，请参阅授予权限以获取访问令牌。

权限类型	权限
应用程序	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

出示请求有效负载

出示请求有效负载包含有关可验证凭据出示请求的信息。以下示例演示了来自特定颁发者的出示请求。此请求的结果返回一个 QR 码，其中包含用于启动出示过程的链接。

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

有效负载包含以下属性。

参数	类型	说明
`includeQRCode`	Boolean	可选。确定此请求的响应中是否包含 QR 码。显示 QR 码并要求用户扫描它。扫描该 QR 码会通过此出示请求启动验证器应用。可能的值为 `true` 或 `false`（默认）。将该值设置为 `false` 时，请使用 `url` 返回属性来呈现深层链接。
`includeReceipt`	Boolean	可选。确定是否应在此请求的响应中包含回执。可能的值为 `true` 或 `false`（默认）。回执包含从验证器发送到可验证凭据服务的原始有效负载。收据对于故障排除或需要了解有效负载的完整详细信息非常有用。否则，默认情况下无需将此值设置为 `true` 。在 `OpenId Connect SIOP` 请求中，回执包含原始请求中的 ID 令牌。
`authority`	string	验证者 Microsoft Entra 租户的分散式标识符 (DID)。有关详细信息，请参阅收集租户详细信息以设置示例应用程序。
`registration`	RequestRegistration	提供有关验证者的信息。
`callback`	Callback	必需。允许开发人员在可验证凭据出示期间更新 UI。当用户完成该过程时，在结果返回到应用程序之后继续执行该过程。
`requestedCredentials`	collection	RequestCredential 对象的集合。

RequestRegistration 类型

RequestRegistration 类型可为颁发者提供信息注册。 RequestRegistration 类型包含以下属性：

属性	类型	说明
`clientName`	字符串	可验证凭据的验证程序的显示名称。此名称将向验证器应用中的用户显示。
`purpose`	字符串	可选。显示的字符串，用于通知用户请求可验证凭据的原因。
`logoUrl`	URL	可选。验证程序标识的 URL。它未由 Authenticator 应用使用。
`termsOfServiceUrl`	URL	可选。验证程序服务条款的 URL。它未由 Authenticator 应用使用。

以下屏幕截图显示了 clientName 属性，以及出示请求中 authority（验证者）的显示名称。

显示如何批准出示请求的屏幕截图。

回调类型

请求服务 REST API 会生成发往回调终结点的多个事件。这些事件使你可以更新 UI，并在结果返回到应用程序后继续执行过程。 Callback 类型包含以下属性：

属性	类型	说明
`url`	string	应用程序的回调终结点的 URI。 URI 必须指向 Internet 上可访问的终结点，否则服务将引发回叫 URL 不可读错误。接受的输入 IPv4、IPv6 或 DNS 可解析主机名。若要强化网络，请参阅常见问题解答。
`state`	string	将回调事件与原始有效负载中传递的状态相关联。
`headers`	字符串	可选。可以包含 POST 消息接收端所需的 HTTP 标头的集合。当前支持的标头值为 `api-key` 或 `Authorization` 标头。任何其他标头都将引发无效的回调标头错误。

RequestCredential 类型

RequestCredential 提供有关用户需要提供的所请求的凭据的信息。 RequestCredential 包含以下属性：

属性	类型	说明
`type`	字符串	可验证凭据类型。 `type` 必须匹配 `issuer` 可验证凭据清单（例如 `VerifiedCredentialExpert`）中定义的类型。若要获取颁发者清单，请参阅收集凭据和环境详细信息以设置示例应用程序。复制“颁发凭据 URL”并在 Web 浏览器中将其打开，然后检查 id 属性。
`purpose`	字符串	可选。提供有关请求此可验证凭据的目的的信息。它未由 Authenticator 应用使用。
`acceptedIssuers`	字符串集合	可选。颁发者 DID 的集合，这些颁发者 DID 可以颁发使用者可出示的可验证凭据类型。若要获取颁发者 DID，请参阅收集凭据和环境详细信息以设置示例应用程序，并复制“分散式标识符(DID)”的值。如果 `acceptedIssuers` 集合为空或不存在，则出示请求将接受由任何颁发者颁发的凭据类型。
`configuration.validation`	Configuration.Validation	演示验证的可选设置。
`constraints`	约束	可选。声明约束的集合。

Configuration.Validation 类型

Configuration.Validation 提供有关如何验证所演示凭据的信息。其中包含以下属性：

属性	类型	说明
`allowRevoked`	Boolean	可选。确定是否应接受已撤销的凭据。默认值为 `false`（不应接受）。
`validateLinkedDomain`	布尔	可选。确定是否应验证链接域。默认值为 `false`。将此标志设置为 `false` 意味着你作为信赖方应用接受来自未验证链接域的凭据。将此标志设置为 `true` 表示将验证链接域，并且仅接受已验证的域。
`faceCheck`	faceCheck	可选。允许在演示期间请求运行状况检查。

约束类型

constraints 类型包含当钱包选择候选凭据时必须满足的声明约束集合。这样便可以请求具有特定声明值的凭据。指定的约束将使用 AND 逻辑，即，如果指定三个约束，则必须满足所有这些约束。对于集合中的每个约束，必须选择一个值操作数：contains 或 startsWith。值不能是正则表达式。所有比较不区分大小写。

properties	类型	说明
`claimName`	string	必需。约束声明的名称。这是可验证凭据中的声明名称。请参阅 claimMapping 类型中的 outputClaim。
`values`	字符串集合	应与声明值匹配的值集。如果指定多个值（如 ["red", "green", "blue"]），则在凭据中的声明值具有集合中任何值的情况下，比较结果是匹配的。
`contains`	string	如果声明值包含指定的值，约束的计算结果为 true。
`startsWith`	string	如果声明值以指定的值开头，约束的计算结果为 true。

faceCheck 类型

faceCheck 类型包含用于在演示凭据期间执行运行状况检查的信息。请求的凭据必须在由 sourcePhotoClaimName 命名的声明中包含持有者的照片。如果运行状况检查的置信度级别等于或大于属性 matchConfidenceThreshold 中指定的值，演示文稿将成功。如果未达到阈值，则整个演示文稿将失败。

properties	类型	说明
`sourcePhotoClaimName`	string	必需。包含照片的凭据中的声明名称。请参阅 claimMapping 类型中的 outputClaim。
`matchConfidenceThreshold`	integer	可选。成功检查照片与运行状况数据的机密阈值。必须是介于 50 到 100 之间的整数。默认值为 70。

成功的响应

如果成功，则此方法将在响应正文中返回响应代码（HTTP 201“已创建”）和事件对象集合。以下 JSON 演示了成功响应：

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

该响应包含以下属性：

属性	类型	说明
`requestId`	字符串	自动生成的请求 ID。回调使用相同的请求，使你可以跟踪出示请求及其回调。
`url`	string	用于启动验证器应用并启动出示过程的 URL。如果用户无法扫描 QR 码，你可以向他们显示此 URL。
`expiry`	integer	指示响应的过期时间。
`qrCode`	字符串	可供用户扫描以启动出示流的 QR 码。

应用收到响应时，需要向用户提供 QR 码。用户扫描 QR 码，这会打开验证器应用并启动出示过程。

错误响应

如果请求出现错误，将返回错误响应，并应由应用进行适当处理。

回调事件

当用户扫描 QR 码、在其验证器应用中使用深层链接或完成出示过程时，将调用回调终结点。

属性	类型	说明
`requestId`	字符串	在有效负载发布到可验证凭据服务后会映射到原始请求。
`requestStatus`	string	在验证器应用检索到请求时返回的状态。可能的值： `request_retrieved`：用户扫描了 QR 码，或选择了用于启动出示流的链接。 `presentation_verified`：可验证凭据验证已成功完成。 li>`presentation_error`：演示文稿中有错误。
`state`	string	返回在原始有效负载中传递的状态值。
`subject`	string	可验证凭据用户 DID。
`verifiedCredentialsData`	array	返回所请求的可验证凭据的数组。对于每个可验证凭据，它提供：可验证的凭据类型。颁发者的 DID 检索到的声明。可验证凭据颁发者的域。可验证凭据颁发者的域验证状态。
`receipt`	字符串	可选。收据包含从钱包发送到可验证凭据服务的原始有效负载。收据应仅用于故障排除/调试。收据中的格式不是固定的，可以根据使用的钱包和版本进行更改。

以下示例演示了当验证器应用启动出示请求时的回调有效负载：

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

以下示例演示了成功完成可验证凭据出示后的回调有效负载：

{
  "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
  "requestStatus": "presentation_verified",
  "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
  "subject": "did:web:verifiedid.contoso.com",
  "verifiedCredentialsData": [
    {
      "issuer": "did:web:issuer...",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      },
      "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
      "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

后续步骤

了解如何调用请求服务 REST API。

通过