请求服务 REST API 发布规范

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 请求。

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

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

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

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

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

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

发布请求有效负载

发布请求有效负载包含有关可验证凭据发布请求的信息。 以下示例通过将 PIN 代码流和用户声明（如名字和姓氏）配合使用，演示了一个颁发请求。 此请求的结果返回一个 QR 码，其中包含用于启动发布过程的链接。

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

有效负载包含以下属性：

参数	类型	说明
includeQRCode	Boolean	可选。 确定此请求的响应中是否包含 QR 码。 显示 QR 码并要求用户扫描它。 扫描该 QR 码后，系统便会通过发布请求启动验证器应用。 可能的值为 true 或 false（默认）。 将该值设置为 false 时，请使用 url 返回属性来呈现深层链接。
callback	Callback	必需。 允许开发人员在可验证凭据发布过程中异步获取有关流的信息。 例如，如果用户已扫描 QR 码，或者发布请求成功（或失败），则开发人员可能需要一个调用。
authority	字符串	颁发者的分散式标识符 (DID)。 有关详细信息，请参阅收集凭据和环境详细信息来设置示例应用程序。
registration	RequestRegistration	提供可以在验证器应用程序中显示的发布者的相关信息。
type	字符串	可验证凭据类型。 应当匹配可验证凭据清单中定义的类型。 例如：VerifiedCredentialExpert。 有关详细信息，请参阅在 Azure 中创建已验证凭据专家卡。
manifest	字符串	可验证凭据清单文档的 URL。 有关详细信息，请参阅收集凭据和环境详细信息来设置示例应用程序。
claims	字符串	可选。 只能用于 ID 令牌提示证明流，以在可验证凭据中包含关于主题的断言集合。
pin	PIN	可选。 PIN 代码只能与 ID 令牌提示证明流一起使用。 用于在颁发期间增强安全性的 PIN 号。 你可以生成 PIN 代码，并将其提供给应用中的用户。 用户必须提供你生成的 PIN 代码。
expirationDate	string	可选。 expirationDate 只能与 ID 令牌提示证明流一起使用。 如果指定，该值必须是以 ISO8601 格式表示的日期。 该日期将覆盖此颁发请求的凭据规则定义中的 validityInterval。 使用此设置可显式控制凭据何时过期（例如日末、月末或年末），而不考虑它是如何颁发的。 请注意，日期以 UTC 格式表示。 如果指定年末，时间设置为 23:59:59，则表示按 UTC 时间格式差 1 秒到午夜。 不同时区中的任何用户都将获得 Microsoft Authenticator 中本地时区显示的到期日期。 这意味着，如果你在 CET 时区，它将显示为 1 月 1 日凌晨 1 点。 凭据协定需要将标志 allowOverrideValidityOnIssuance 设置为 true。

当前，可在有效负载中发送四种声明证明类型。 Microsoft Entra 验证的 ID 使用四种方法将声明插入到可验证凭据中，并使用颁发者的 DID 证明该信息。 以下是这四种类型：

• ID 令牌
• ID 令牌提示
• 通过可验证的提交提供的可验证凭据
• 自证的声明

可在自定义可验证凭据中找到有关输入类型的详细信息。

RequestRegistration 类型

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

属性	类型​​	说明
clientName	string	可验证凭据发布者的显示名称。
logoUrl	字符串	可选。 颁发者徽标的 URL。
termsOfServiceUrl	字符串	可选。 你要颁发的可验证凭据的使用条款的 URL。

注意

目前，Microsoft Authenticator 应用在颁发期间不会提供 RequestRegistration 信息。 但是，此信息可在有效负载中使用。

回调类型

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

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

PIN 类型

pin 类型定义可在颁发过程中显示的 PIN 代码。 pin 是可选的，如果使用，应始终带外发送。 使用哈希 PIN 代码时，必须定义 salt、alg 和 iterations 属性。 pin 包含以下属性：

属性	类型​​	说明
value	string	包含纯文本形式的 PIN 值。 使用经过哈希处理的 PIN 时，value 属性包含 base64 编码的加盐哈希。
type	字符串	PIN 代码的类型。 可能的值：numeric（默认值）。
length	integer	PIN 代码的长度。 默认长度为 6，最小长度为 4，最大长度为 16。
salt	字符串	经过哈希处理的 PIN 代码的盐。 盐在哈希计算期间附加。 编码格式：UTF-8。
alg	string	用于生成经过哈希处理的 PIN 的哈希算法。 支持的算法：sha256。
iterations	integer	哈希迭代数。 可能的值：1。

成功的响应

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

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"  
} 

该响应包含以下属性：

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

应用收到响应时，需要向用户提供 QR 码。 如果用户扫描 QR 码，验证器应用即会打开，颁发过程亦会启动。

错误响应

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

回调事件

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

属性	类型​​	说明
requestId	字符串	在有效负载发布到可验证凭据服务后会映射到原始请求。
requestStatus	string	针对请求返回的状态。 可能的值： request_retrieved：用户扫描了 QR 码，或选择了用于启动颁发流的链接。 issuance_successful：已成功颁发可验证凭据。 issuance_error：在颁发期间出错。 有关详细信息，请参见 error 属性。
state	字符串	返回在原始有效负载中传递的状态值。
error	error	如果 code 属性值为 issuance_error，则此属性包含有关错误的信息。
error.code	string	返回错误代码。
error.message	字符串	错误消息。

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

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

以下示例演示了在用户成功完成颁发过程后的回调有效负载：

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

回调错误

可能会在调用回调终结点时出现错误消息。 下表列出了错误代码：

消息	定义
fetch_contract_error	无法提取可验证凭据协定。 当 API 无法提取在请求有效负载 RequestIssuance 对象中指定的清单时，通常会发生此错误。
issuance_service_error	可验证凭据服务无法验证要求，或者可验证凭据中出现问题。
unspecified_error	此错误很少见，但值得调查。

以下示例演示发生错误时的回调有效负载：

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
} 

后续步骤

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