可验证凭据管理 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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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、mail、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.z13.web.core.windows.net/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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
            "name": "test1",
            "authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        },
        {
            "id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w",
            "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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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

备注

备注

如果你对密钥保管库没有删除权限，我们会返回错误消息，但仍选择退出

后续步骤

• 指定请求服务 REST API 发布请求
• Microsoft Entra 验证 ID 网络 API