可验证凭据管理 API
通过 Microsoft Entra 验证 ID 管理 API 可以管理可验证凭据服务的各个方面。 它提供了一种方法来设置全新的服务、管理和创建可验证凭据协定、撤销可验证凭据以及完全选择退出服务。
该 API 适用于熟悉 RESTful API 且在 Microsoft Entra 租户上具有足够权限来启用服务的开发人员
基 URL
管理 API 是 HTTPS 上的服务器。 文档中引用的所有 URL 都具有以下基 URL：https://verifiedid.did.msidentity.com。
身份验证
可通过 Microsoft Entra ID 对该 API 进行保护，该 API 使用 OAuth2 持有者令牌。 访问令牌可以用于用户或应用程序。
用户持有者令牌
应用注册需要具有 Verifiable Credentials Service Admin 的 API 权限，随后在获取访问令牌时，应用应使用范围 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access。 访问令牌必须适用于具有全局管理员或身份验证策略管理员角色的用户。 角色为全局读取者的用户可以执行只读 API 调用。
应用程序持有者令牌
Verifiable Credentials Service Admin 服务支持以下应用程序权限。
| 权限 | 说明 |
|---|---|
| VerifiableCredential.Authority.ReadWrite | 读取/写入颁发机构对象的权限 |
| VerifiableCredential.Contract.ReadWrite | 读取/写入协定对象的权限 |
| VerifiableCredential.Credential.Search | 搜索要撤销的凭据的权限 |
| VerifiableCredential.Credential.Revoke | 撤销以前颁发的凭据的权限 |
| VerifiableCredential.Network.Read | 从已验证 ID 网络读取条目的权限 |
应用注册需要具有 Verifiable Credentials Service Admin 的 API 权限和上表中所需的权限。 通过客户端凭据流获取访问令牌时，应用应使用范围 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default。
如果应用打算创建新的颁发机构，需要满足两个条件。 首先，应用注册需要 VerifiableCredential.Authority.ReadWrite 权限。 其次，应用需要在 Key Vault 访问策略中具有 Create Key 权限。 如果应用仅读取/写入现有颁发机构，则不需要 Key Vault 权限。
登记
此 API 可帮助创建新环境，以便可以设置新颁发机构。 也可以通过在 Azure 门户中导航到“可验证凭据”页来手动触发此操作。 只需调用此 API 一次，并且仅当要使用此 API 设置全新环境时才调用。
HTTP 请求
POST /v1.0/verifiableCredentials/onboard
使用此终结点在租户中完成可验证凭据服务的预配。 系统会创建其余服务主体（如果尚未预配这些主体）。
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
返回消息
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
"verifiableCredentialServicePrincipalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
"verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
"status": "Enabled"
}
重复调用此 API 会产生完全相同的返回消息。
颁发机构
此终结点可用于创建或更新可验证凭据服务实例。
方法
| 方法 | 返回类型 | 说明 |
|---|---|---|
| 获取颁发机构 | 颁发机构 | 读取颁发机构的属性 |
| 列出颁发机构 | 颁发机构数组 | 获取所有已配置颁发机构/可验证凭据服务的列表 |
| 创建颁发机构 | 颁发机构 | 创建新颁发机构 |
| 更新颁发机构 | 颁发机构 | 更新颁发机构 |
| 删除颁发机构 | 颁发机构 | 删除颁发机构 |
| 生成知名 DID 配置 | ||
| 生成 DID 文档 | ||
| 验证知名 DID 配置 | ||
| 轮换签名密钥 | 颁发机构 | 轮换签名密钥 |
| 与 DID 文档同步 | 颁发机构 | 将 DID 文档与新的签名密钥同步 |
获取颁发机构
检索已配置颁发机构或可验证凭据服务实例的属性。
HTTP 请求
GET /v1.0/verifiableCredentials/authorities/:authorityId
将 :authorityId 替换为已配置颁发机构之一的值。
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文
响应消息
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
响应包含以下属性。
颁发机构类型
| 属性 | 类型 | 说明 |
|---|---|---|
Id |
字符串 | 自动生成的唯一 ID，可用于检索或更新可验证凭据服务的特定实例 |
name |
字符串 | 此可验证凭据服务实例的易记名称 |
status |
字符串 | 服务的状态，此值始终为 enabled |
| didModel | didModel | 有关 DID 和密钥的信息 |
| keyVaultMetadata | keyVaultMeta 数据 | 有关所使用的密钥保管库的信息 |
didModel 类型
Web
| 属性 | 类型 | 说明 |
|---|---|---|
did |
字符串 | 此可验证凭据服务实例的 DID |
signingKeys |
字符串数组 | 签名密钥的 URL |
linkedDomainUrls |
字符串数组 | 链接到此 DID 的域，需要单个条目 |
| didModel | didModel | 有关 DID 和密钥的信息 |
didDocumentStatus |
字符串 | DID 的状态，对于此方法，值始终为 published |
keyVaultMetadata 类型
| 属性 | 类型 | 说明 |
|---|---|---|
subscriptionId |
字符串 | 此密钥保管库所在的 Azure 订阅 |
resourceGroup |
字符串 | 此密钥保管库中的资源组的名称 |
resourceName |
字符串 | 密钥保管库名称 |
resourceUrl |
字符串 | 此密钥保管库的 URL |
列出颁发机构
获取此租户的所有已配置颁发机构或可验证凭据服务
HTTP 请求
GET /v1.0/verifiableCredentials/authorities
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
响应消息是一个由颁发机构组成的数组
示例：
HTTP/1.1 200 OK
Content-type: application/json
{
value:
[
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName2",
"keyVaultUrl": "https://vccontosokv.vault.azure.net/",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid2.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid2.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
]
}
创建颁发机构
此调用会创建新的私钥、恢复密钥和更新密钥，将这些密钥存储在指定 Azure 密钥保管库中，为可验证凭据服务设置对此密钥保管库的权限，使用对应 DID 文档创建新的 DID。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
在请求正文中，提供以下内容的 JSON 表示形式
| 属性 | 类型 | 说明 |
|---|---|---|
name |
字符串 | 此服务实例的显示名称 |
linkedDomainUrl |
字符串 | 链接到此 DID 的域 |
didMethod |
string | 必须是 web |
keyVaultMetadata |
keyVaultMetadata | 特定密钥保管库的元数据 |
示例消息：
{
"name":"ExampleName",
"linkedDomainUrl":"https://verifiedid.contoso.com/",
"didMethod": "web",
"keyVaultMetadata":
{
"subscriptionId":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup":"verifiablecredentials",
"resourceName":"vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
响应消息
成功后，响应消息包含颁发机构的名称
did:web 的示例消息：
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
did:ion 的示例消息：
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
注解
可以创建多个具有其自己的 DID 和私钥的颁发机构，这些颁发机构在 Azure 门户的 UI 中不可见。 目前，我们仅支持具有 1 个颁发机构。 我们没有对创建了多个颁发机构的所有方案进行完整测试。 如果尝试此方案，请向我们告知你的体验。
更新颁发机构
此方法可用于更新可验证凭据服务的此特定实例的显示名称。
HTTP 请求
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
将 :authorityId 的值替换为要更新的颁发机构 ID 的值。
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
在请求正文中，提供以下内容的 JSON 表示形式。
| 属性 | 类型 | 说明 |
|---|---|---|
name |
字符串 | 此服务实例的显示名称 |
示例消息
{
"name":"ExampleIssuerName"
}
删除颁发机构
可以使用此方法删除颁发机构。 目前只能删除 did:ion 颁发机构。 删除颁发机构时，任何已颁发的已验证 ID 凭据会变为无效且无法再进行验证，因为颁发机构已不存在。
HTTP 请求
DELETE /beta/verifiableCredentials/authorities/:authorityId
将 :authorityId 的值替换为要删除的颁发机构 ID 的值。
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
无请求正文
响应消息
示例响应消息：
成功删除颁发机构响应。
HTTP/1.1 200 OK
如果成功删除颁发机构，但清理 Azure Key Vault 密钥失败，则会获得如下响应。
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": {
"code": "deleteIssuerSuccessfulButKeyDeletionFailed",
"message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
}
}
知名 DID 配置
generateWellknownDidConfiguration 方法会生成已签名的 did-configuration.json 文件。 该文件必须上传到此可验证凭据实例的链接域中为该域托管的网站根目录中的 .well-known 文件夹。 可在此处找到说明。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
需要在指定颁发机构的 linkedDomains 中指定其中一个域。
{
"domainUrl":"https://atest/"
}
响应消息
示例响应消息：
HTTP/1.1 200 OK
Content-type: application/json
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbGciOiJFUzI1NksiL...<SNIP>..."
]
}
使用文件名 did-configuration.json 保存此结果，并将此文件上传到正确的文件夹和网站。 如果指定未链接到此 DID/DID 文档的域，则会收到错误：
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"079192a95fbf56a661c1b2dd0e012af5",
"date":"Mon, 07 Feb 2022 18:55:53 GMT",
"mscv":"AVQh55YiU3FxMipB.0",
"error":
{
"code":"wellKnownConfigDomainDoesNotExistInIssuer",
"message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
}
}
备注
可以将多个 DID 指向同一个域。 如果选择此配置，则需要合并生成的令牌并将它们置于相同的 did-configuration.json 文件中。 该文件包含这些令牌的数组。
例如：
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
生成 DID 文档
此调用生成用于 DID:WEB 标识符的 DID 文档。 生成此 DID 文档后，管理员必须将文件放置在 https://domain/.well-known/did.json 位置。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "did:web:verifiedid.contoso.com",
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:web:verifiedid.contoso.com"
}
],
"service": [
{
"id": "#linkeddomains",
"type": "LinkedDomains",
"serviceEndpoint": {
"origins": [
"https://verifiedid.contoso.com/"
]
}
},
{
"id": "#hub",
"type": "IdentityHub",
"serviceEndpoint": {
"instances": [
"https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
]
}
}
],
"verificationMethod": [
{
"id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
"controller": "did:web:verifiedid.contoso.com",
"type": "EcdsaSecp256k1VerificationKey2019",
"publicKeyJwk": {
"crv": "secp256k1",
"kty": "EC",
"x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
"y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
}
}
],
"authentication": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
],
"assertionMethod": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
]
}
备注
要求调用方对目标密钥保管库具有密钥列表权限。
验证知名 DID 配置
此调用检查 DID 设置。 它会下载知名 DID 配置，验证是否使用了正确 DID 并且签名正确。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
HTTP/1.1 204 No Content
Content-type: application/json
轮换签名密钥
轮换签名密钥会为 did:web 颁发机构创建新的私钥。 应重新注册 DID 文档以反映更新。 完成此操作后，synchronizeWithDidDocument 会告知系统开始使用新密钥进行签名。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
didDocumentStatus 将更改为 outOfSync。
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
与 DID 文档同步
轮换签名密钥后，应重新注册 DID 文档以反映更新。 完成此操作后，synchronizeWithDidDocument 会告知系统开始使用新密钥进行签名。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
调用成功后，didDocumentStatus 将从 outOfSync 更改为 published。
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
协定
此终结点允许创建新协定并更新现有协定。 协定由两个 JSON 定义表示的两个部分组成。 可在此处找到有关如何手动设计和创建协定的信息。
- 显示定义由管理员用于控制可验证凭据的外观，例如可验证凭据的背景色、徽标和标题。 此文件还包含需要存储在可验证凭据中的声明。
- 规则定义包含有关如何收集证明的信息，例如自证明声明、作为输入的其他可验证凭据或者可能是用户登录 OIDC 兼容标识提供者后收到的 ID 令牌。
方法
| 方法 | 返回类型 | 说明 |
|---|---|---|
| 获取协定 | 合约 | 读取协定的属性 |
| 列出协定 | 协定集合 | 获取所有已配置协定的列表 |
| 创建协定 | 合约 | 创建新合同 |
| 更新协定 | 合约 | 更新协定 |
获取协定
HTTP 请求
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
将 :authorityId 和 :contractId 替换为颁发机构和协定的正确值。
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
示例消息：
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "...",
"issueNotificationAllowedToGroupOids" : null,
"rules": <rulesModel>,
"displays": <displayModel[]>,
"allowOverrideValidityIntervalOnIssuance": false
}
响应包含以下属性
协定类型
| 属性 | 类型 | 说明 |
|---|---|---|
Id |
字符串 | 协定 ID |
name |
字符串 | 此协定的易记名称 |
status |
字符串 | 始终是 Enabled |
manifestUrl |
字符串 | 颁发请求中使用的协定的 URL |
issueNotificationEnabled |
boolean | 如果会通知用户此 VC 已准备好进行颁发，则设置为 true |
issueNotificationAllowedToGroupOids |
groupId 字符串数组 | 会向其提供此凭据的组 ID 的数组 |
availableInVcDirectory |
boolean | 此协定是否在可验证凭据网络中发布 |
| rules | rulesModel | 规则定义 |
| displays | displayModel 数组 | 显示定义 |
allowOverrideValidityIntervalOnIssuance |
boolean | 如果允许 createIssuanceRequest API 调用替换凭据的到期时间。 这仅适用于 idTokenHint 流。 |
rulesModel 类型
| 属性 | 类型 | 说明 |
|---|---|---|
attestations |
attestations | 描述规则支持的输入 |
validityInterval |
数字 | 此值显示凭据的有效期 |
vc |
vcType 数组 | 此协定的类型 |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint-type)（可选） | 要包含在此协定的可验证凭据中的状态终结点 |
如果未指定属性 customStatusEndpoint，则使用 anonymous 状态终结点。
证明类型
| 属性 | 类型 | 说明 |
|---|---|---|
idTokens |
idTokenAttestation（数组）（可选） | 描述 ID 令牌输入 |
idTokenHints |
idTokenHintAttestation（数组）（可选） | 描述 ID 令牌提示输入 |
presentations |
verifiablePresentationAttestation（数组）（可选） | 描述可验证演示文稿输入 |
selfIssued |
selfIssuedAttestation（数组）（可选） | 描述自行颁发的输入 |
accessTokens |
accessTokenAttestation（数组）（可选） | 描述访问令牌输入 |
idTokenAttestation 类型
| 属性 | 类型 | 说明 |
|---|---|---|
mapping |
claimMapping（可选） | 将输入声明映射到可验证凭据中的输出声明的规则 |
configuration |
字符串 (url) | 标识提供者的配置文档位置 |
clientId |
string | 获取 ID 令牌时要使用的客户端 ID |
redirectUri |
string | 获取 ID 令牌时要使用的重定向 URI 必须是 vcclient://openid/ |
scope |
string | 获取 ID 令牌时要使用的范围的空格分隔列表 |
required |
布尔值（默认为 false） | 指示是否需要此证明 |
idTokenHintAttestation 类型
| 属性 | 类型 | 说明 |
|---|---|---|
mapping |
claimMapping（可选） | 将输入声明映射到可验证凭据中的输出声明的规则 |
required |
布尔值（默认为 false） | 指示是否需要此证明 |
trustedIssuers |
字符串（数组） | 允许颁发此协定的可验证凭据的 DID 列表 |
verifiablePresentationAttestation 类型
| 属性 | 类型 | 说明 |
|---|---|---|
mapping |
claimMapping（可选） | 将输入声明映射到可验证凭据中的输出声明的规则 |
credentialType |
字符串（可选） | 所需的输入凭据类型 |
required |
布尔值（默认为 false） | 指示是否需要此证明 |
trustedIssuers |
字符串（数组） | 允许颁发此协定的可验证凭据的 DID 列表 |
selfIssuedAttestation 类型
| 属性 | 类型 | 说明 |
|---|---|---|
mapping |
claimMapping（可选） | 将输入声明映射到可验证凭据中的输出声明的规则 |
required |
布尔值（默认为 false） | 指示是否需要此证明 |
accessTokenAttestation 类型
| 属性 | 类型 | 说明 |
|---|---|---|
mapping |
claimMapping（可选） | 将输入声明映射到可验证凭据中的输出声明的规则 |
required |
布尔值（默认为 false） | 指示是否需要此证明 |
mappings属性支持的inputClaim值包括：givenName、displayName、preferredLanguage、userPrincipalName、surname、jobTitle、photo。
claimMapping 类型
| 属性 | 类型 | 说明 |
|---|---|---|
inputClaim |
string | 输入中要使用的声明名称 |
outputClaim |
string | 可验证凭据中声明的名称 |
indexed |
布尔值（默认为 false） | 指示此声明的值是否用于搜索；对于给定协定，只允许为一个 clientMapping 对象编制索引 |
required |
布尔值（默认为 false） | 指示是否需要此映射 |
type |
字符串（可选） | 声明类型 |
customStatusEndpoint 类型
| properties | 类型 | 说明 |
|---|---|---|
url |
字符串 (url) | 自定义状态终结点的 URL |
type |
string | 终结点的类型 |
示例：
"rules": {
"attestations": {
"idTokens": [
{
"clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
"redirectUri": "vcclient://openid/",
"scope": "openid",
"mapping": [
{
"outputClaim": "givenName",
"required": false,
"inputClaim": "given_name",
"indexed": false
},
{
"outputClaim": "familyName",
"required": false,
"inputClaim": "family_name",
"indexed": true
}
],
"required": false
}
]
},
"validityInterval": 2592000,
"vc": {
"type": [
"BankofWoodgroveIdentity"
]
}
}
displayModel 类型
| 属性 | 类型 | 说明 |
|---|---|---|
locale |
string | 此显示的区域设置 |
credential |
displayCredential | 可验证凭据的显示属性 |
consent |
displayConsent | 颁发可验证凭据时的补充数据 |
claims |
displayClaims 数组 | 可验证凭据中包含的声明的标签 |
displayCredential 类型
| 属性 | 类型 | 说明 |
|---|---|---|
title |
string | 凭据的标题 |
issuedBy |
string | 凭据颁发者的名称 |
backgroundColor |
数字（十六进制） | 十六进制凭据的背景色，例如 #FFAABB |
textColor |
数字（十六进制） | 十六进制凭据的文本颜色，例如 #FFAABB |
description |
string | 要随每张凭据一起显示的补充文本 |
logo |
displayCredentialLogo | 用于凭据的徽标 |
displayCredentialLogo 类型
| 属性 | 类型 | 描述 |
|---|---|---|
uri |
字符串 (uri) | 徽标的 uri。 如果这是 URL，则必须通过公共 Internet 匿名访问它。 |
description |
string | 徽标的说明 |
displayConsent 类型
| 属性 | 类型 | 说明 |
|---|---|---|
title |
string | 同意的标题 |
instructions |
string | 显示同意时要使用的补充文本 |
displayClaims 类型
| 属性 | 类型 | 说明 |
|---|---|---|
label |
string | 显示中声明的标签 |
claim |
string | 标签应用到的声明的名称 |
type |
string | 声明的类型 |
description |
字符串（可选） | 声明的说明 |
示例：
{
"displays": [
{
"locale": "en-US",
"card": {
"backgroundColor": "#FFA500",
"description": "ThisisyourBankofWoodgroveIdentity",
"issuedBy": "BankofWoodgrove",
"textColor": "#FFFF00",
"title": "BankofWoodgroveIdentity",
"logo": {
"description": "Defaultbankofwoodgrovelogo",
"uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please login with your bankofWoodgrove account to receive this credential.",
"title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
},
"claims": [
{
"claim": "vc.credentialSubject.givenName",
"label": "Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.familyName",
"label": "Surname",
"type": "String"
}
]
}
]
}
列出协定
此 API 列出当前租户中为指定颁发机构配置的所有协定。
HTTP 请求
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
示例消息：
{
"value":
[
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "test1",
"authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
"name": "test2",
"authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
}
]
}
创建合同
创建协定时，名称在租户中必须唯一。 如果创建了多个颁发机构，则协定名称必须在所有颁发机构中唯一。 协定的名称是颁发请求中使用的协定 URL 的一部分。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
示例请求
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
响应消息
示例消息：
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "GUID",
"name": "ExampleContractName1",
"issuerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"rules": "<rules JSON>",
"displays": [{<display JSON}],
"manifestUrl": "https://..."
}
更新协定
此 API 允许更新协定。
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
示例请求：
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
响应消息
示例消息：
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": true,
"manifestUrl": "https://...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[],
"allowOverrideValidityIntervalOnIssuance": true
}
凭据
此终结点允许搜索已颁发的可验证凭据、检查撤销状态以及撤销凭据。
方法
| 方法 | 返回类型 | 说明 |
|---|---|---|
| 获取凭据 | 凭据 | 读取凭据的属性 |
| 搜索凭据 | 凭据集合 | 搜索具有特定声明值的凭据的列表 |
| 撤销凭据 | 撤销特定凭据 |
获取凭据
此 API 允许检索特定凭据并检查状态，以查看该凭据是否已撤销。
HTTP 请求
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
响应消息
示例消息
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
搜索凭据
能够搜索具有特定索引声明的可验证凭据。 由于只存储哈希，因此需要搜索特定计算值。 需要使用的算法是：Base64Encode(SHA256(contractid + claim value)) C# 中的示例如下所示：
string claimvalue = "Bowen";
string contractid = "<...your-contract-id-value...>";
string output;
using (var sha256 = SHA256.Create())
{
var input = contractid + claimvalue;
byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
}
以下请求演示如何将计算值添加到请求的筛选器参数。 目前仅支持 filter=indexclaimhash eq 格式。
HTTP 请求
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
示例消息
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"status": "valid",
"issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
}
]
}
撤销凭据
此 API 允许在使用搜索 API 搜索凭据后撤销特定凭据，可以通过指定特定凭据 ID 来撤销凭据。
HTTP 请求
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文。
响应消息
HTTP/1.1 204 No Content
Content-type: application/json
选择退出
此方法会完全移除此租户中可验证凭据服务的所有实例。 它会移除所有已配置协定。 无法检查每个已颁发的可验证凭据是否撤销。 此操作不能撤消。
警告
此操作不能撤消，会使所有已颁发的可验证凭据和已创建的协定失效。
HTTP 请求
POST /v1.0/verifiableCredentials/optout
请求标头
| 标头 | 值 |
|---|---|
| 授权 | 持有者（令牌）。 必需 |
| Content-Type | application/json |
请求正文
请勿为此方法提供请求正文
响应消息
示例响应消息
HTTP/1.1 200 OK
Content-type: application/json
OK
备注
备注
如果你对密钥保管库没有删除权限，我们会返回错误消息，但仍选择退出
后续步骤
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈