API администратора для проверяемых удостоверений
API администратора Проверенных учетных данных Microsoft Entra позволяет управлять всеми аспектами службы проверяемых удостоверений. Он позволяет настроить новую службу, создать контракты удостоверений и управлять ими, отозвать проверяемые удостоверения и полностью отказаться от использования службы.
API предназначен для разработчиков, удобных для API RESTful и достаточно разрешений для клиента Microsoft Entra, чтобы включить службу.
Базовый URL-адрес
API администратора работает по протоколу HTTPS. Все URL-адреса, указанные в документации, имеют следующую базу: https://verifiedid.did.msidentity.com
.
Проверка подлинности
API защищен с помощью идентификатора Microsoft Entra и использует маркеры носителя OAuth2. Маркер доступа может быть для пользователя или приложения.
Маркеры носителя пользователей
Регистрация приложения должна иметь разрешение API для Verifiable Credentials Service Admin
, а при получении маркера доступа приложению нужно указать область 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access
. Маркер доступа должен быть для пользователя с ролью глобального администратора
Маркеры носителя приложений
Служба Verifiable Credentials Service Admin
поддерживает следующие разрешения приложения.
Разрешение | Description |
---|---|
VerifiableCredential.Authority.ReadWrite | Разрешение на чтение и запись объектов центра управления |
VerifiableCredential.Contract.ReadWrite | Разрешение на чтение и запись объектов контракта |
VerifiableCredential.Credential.Search | Разрешение на поиск учетных данных для отзыва |
VerifiableCredential.Credential.Revoke | Разрешение на отзыв ранее выданных учетных данных |
VerifiableCredential.Network.Read | Разрешение на чтение записей из проверенной сети идентификаторов |
Регистрация приложения должна иметь разрешение API для Verifiable Credentials Service Admin
и разрешений, необходимых для таблицы. Когда приложение получает маркер доступа, через поток учетных данных клиента , приложение должно использовать область 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
.
Если приложение намерено создать новый центр, ему потребуется две вещи. Во-первых, для регистрации приложения требуется VerifiableCredential.Authority.ReadWrite
разрешение. Во-вторых, приложению требуется Create Key
разрешение в политиках доступа Key Vaults. Если приложение доступно только для чтения и записи существующих центров, для него не требуется разрешение Key Vault.
Переход
Этот API поможет создать новую среду, чтобы настроить новые центры сертификации. Этот процесс можно активировать вручную, перейдя на страницу проверяемых учетных данных на портале Azure. Этот API придется вызвать только один раз и только в том случае, если вы хотите настроить новую среду без применения других средств, кроме этого API.
HTTP-запрос
POST /v1.0/verifiableCredentials/onboard
Используйте эту конечную точку, чтобы завершить подготовку службы проверяемых учетных данных в арендаторе. Система создает остальные субъекты-службы, если они еще не подготовлены.
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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 приводит к тому же возвращаемого сообщения.
Полномочия
Эту конечную точку можно использовать для создания или обновления экземпляра службы проверяемого удостоверения.
Методы
Методы | Тип возвращаемых данных | Description |
---|---|---|
Получение центра авторизации | Центр | Чтение свойств центра авторизации |
Список центров авторизации | Массив Authority | Получение списка всех настроенных центров авторизации или служб проверяемых удостоверений |
Создание центра авторизации | Центр | Создание нового центра авторизации |
Обновление центра авторизации | Центр | Обновление центра авторизации |
Удаление центра | Центр | Удаление центра |
Создание документа DID | ||
Смена ключа подписывания | Центр | Смена ключа подписывания |
создание ключа подписывания | Центр | Создание ключа подписи |
Синхронизация с документом DID | Центр | Синхронизация документа DID с новым ключом подписывания |
Создание хорошо известной конфигурации DID | ||
Проверка хорошо известной конфигурации DID |
Получение центра авторизации
Получение свойств настроенного центра авторизации или экземпляра службы проверяемого удостоверения.
HTTP-запрос
GET /v1.0/verifiableCredentials/authorities/:authorityId
Замените :authorityId
значением для одного из настроенных центров авторизации.
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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/"
}
}
Результат содержит следующие свойства.
Тип центра авторизации
Свойство | Type | Description |
---|---|---|
Id |
строка | Автоматически созданный уникальный идентификатор, который можно использовать для получения или обновления конкретного экземпляра службы проверяемого удостоверения. |
name |
строка | Понятное имя этого экземпляра службы проверяемого удостоверения |
status |
строка | состояние службы всегда enabled |
didModel | didModel | Сведения о DID и ключах |
keyVaultMetadata | Данные keyVaultMeta | Сведения об используемом Key Vault |
Тип didModel
Интернет
Свойство | Type | Description |
---|---|---|
did |
строка | DID для этого экземпляра службы проверяемого удостоверения |
signingKeys |
строка массив | URL-адрес ключа подписывания |
linkedDomainUrls |
строка массив | Домены, связанные с этим DID (обычно здесь ровно одна запись) |
didModel | didModel | Сведения о DID и ключах |
didDocumentStatus |
строка | состояние этого DID (для этого метода всегда имеет значение published ) |
Тип keyVaultMetadata
Свойство | Type | Description |
---|---|---|
subscriptionId |
строка | Подписка Azure, в которой находится это хранилище Key Vault |
resourceGroup |
строка | имя группы ресурсов для этого Key Vault |
resourceName |
строка | Имя хранилища ключей |
resourceUrl |
строка | URL-адрес этого Key Vault |
Список центров авторизации
Получение полного списка настроенных центров авторизации или служб проверяемого удостоверения для этого арендатора
HTTP-запрос
GET /v1.0/verifiableCredentials/authorities
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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 Key Vault и задает разрешения для этой службы ключей для проверяемой службы учетных данных и создает новые DID с соответствующим документом DID.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | application/json |
Текст запроса
В тексте запроса нужно передать представление следующих данных в формате JSON
Свойство | Type | Description |
---|---|---|
name |
строка | Отображаемое имя этого экземпляра службы |
linkedDomainUrl |
строка | Домен, связанный с этим DID |
didMethod |
строка | Должен содержать значение 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. В настоящее время мы поддерживаем только 1 центр авторизации. Мы не полностью протестировали сценарии использования нескольких центров авторизации. Если вы используете этот сценарий, просим вас сообщить нам о результатах.
Обновление центра авторизации
Этот метод можно использовать для обновления отображаемого имени конкретного экземпляра службы проверяемого удостоверения.
HTTP-запрос
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Замените значение :authorityId
реальным идентификатором центра авторизации, который вы хотите обновить.
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | application/json |
Текст запроса
В тексте запроса нужно передать представление следующих данных в формате JSON.
Свойство | Type | Description |
---|---|---|
name |
строка | Отображаемое имя этого экземпляра службы |
Пример сообщения
{
"name":"ExampleIssuerName"
}
Удаление центра
Этот метод можно использовать для удаления центра. В настоящее время можно удалить только did:ion
центры. При удалении центра все выданные учетные данные проверенного идентификатора становятся недействительными и больше не могут быть проверены по мере удаления центра выдачи.
HTTP-запрос
DELETE /beta/verifiableCredentials/authorities/:authorityId
Замените значение значения :authorityId
идентификатора центра, который требуется удалить.
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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, используемый для идентификаторов DID:WEB. После создания документа DID администратор должен поместить файл в расположение https://domain/.well-known/did.json.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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"
]
}
Комментарий
Требует, чтобы вызывающий объект имел разрешения KEY List ключей в целевом хранилище ключей.
Проверка хорошо известной конфигурации DID
Этот вызов проверяет настройку DID. Он скачивает хорошо известную конфигурацию DID и проверяет версию DID и подпись.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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
}
Создание ключа подписи
Ключ подписывания create создает новый закрытый ключ в уже существующем Key Vault для центра did:web. Документ DID должен быть повторно зарегистрирован, чтобы отразить обновление, так как didDocumentStatus
центра изменяется на outOfSync
. При повторной регистрации документа DID вызовите синхронизацииWithDidDocument сообщить системе начать использовать новый ключ для подписывания.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | application/json |
Текст запроса
{
"signingKeyCurve": "P-256"
}
Сообщение ответа
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"keyUrl": "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407",
"curve": "P-256"
}
Синхронизация с документом DID
После смены ключа подписи документ DID должен быть повторно зарегистрирован для отражения обновления. По завершении процесса синхронизацияWithDidDocument сообщает системе начать использование нового ключа для подписывания.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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 удостоверений.
Методы
Методы | Тип возвращаемых данных | Description |
---|---|---|
Get contract | Contract | Чтение свойств контракта |
List contracts | Коллекция контрактов | Получение списка всех настроенных контрактов |
Create contract | Contract | создать контейнер; |
Update contract | Contract | Обновление контракта |
Get contract
HTTP-запрос
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Замените значения :authorityId
и :contractId
реальными значениями для используемых центра авторизации и контракта.
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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
}
Результат содержит следующие свойства.
Тип контракта
Свойство | Type | Description |
---|---|---|
Id |
строка | ИД контракта |
name |
строка | Понятное имя этого контракта |
status |
строка | Всегда Enabled |
manifestUrl |
строка | URL-адрес контракта, используемого в запросе на выдачу |
issueNotificationEnabled |
boolean | Значение true для пользователей, которые будут получать уведомления об этом VC, готовы к их выпуску. |
issueNotificationAllowedToGroupOids |
Массив строковых значений groupId | Массив идентификаторов групп, доступных для этих учетных данных. |
availableInVcDirectory |
boolean | Обозначает, опубликован ли контракт в сети проверяемого удостоверения |
rules | rulesModel | Определение правил |
displays | Массив displayModel | Определения отображения |
allowOverrideValidityIntervalOnIssuance |
boolean | Если вызов API createIssuanceRequest разрешен переопределить срок действия учетных данных. Это допустимо только для потоков idTokenHint . |
Тип rulesModel
Свойство | Type | Description |
---|---|---|
attestations |
аттестации | Описание поддерживаемых входных данных для правил |
validityInterval |
number | Это значение показывает продолжительность существования удостоверения |
vc |
Массив vcType | типы для этого контракта |
customStatusEndpoint |
[customStatusEndpoint] (тип #customstatusendpoint) (необязательно) | Конечная точка состояния для включения в проверяемое удостоверение для этого контракта |
Если свойство свойства customStatusEndpoint
не указано, anonymous
используется конечная точка состояния.
Тип аттестаций
Свойство | Type | Description |
---|---|---|
idTokens |
idTokenAttestation (массив) (необязательно) | описание входных данных маркера идентификатора |
idTokenHints |
idTokenHintAttestation (массив) (необязательно) | описание входных данных указания маркера идентификатора |
presentations |
verifiablePresentationAttestation (массив) (необязательно) | описывает входные данные проверяемых презентаций |
selfIssued |
selfIssuedAttestation (массив) (необязательно) | описывает самостоятельно выданные входные данные |
accessTokens |
accessTokenAttestation (массив) (необязательно) | описывает входные данные маркера доступа |
Тип idTokenAttestation
Свойство | Type | Description |
---|---|---|
mapping |
claimMapping (необязательно) | правила сопоставления входных утверждений с выходными утверждениями в проверяемых удостоверений |
configuration |
Строка (URL-адрес) | расположение документа с конфигурацией поставщика удостоверений |
clientId |
строка | идентификатор клиента, используемый при получении маркера идентификатора |
redirectUri |
строка | URI перенаправления, используемый при получении маркера идентификатора, должен быть vcclient://openid/ |
scope |
строка | список областей, используемых при получении маркера идентификатора, с пробелами в качестве разделителей |
required |
логическое значение (по умолчанию false) | указывает, является ли эта аттестация обязательной или нет |
Тип idTokenHintAttestation
Свойство | Type | Description |
---|---|---|
mapping |
claimMapping (необязательно) | правила сопоставления входных утверждений с выходными утверждениями в проверяемых удостоверений |
required |
логическое значение (по умолчанию false) | указывает, является ли эта аттестация обязательной или нет |
trustedIssuers |
строка (массив) | список идентификаторов DID, которые могут выдавать проверяемые удостоверения для этого контракта. |
Тип verifiablePresentationAttestation
Свойство | Type | Description |
---|---|---|
mapping |
claimMapping (необязательно) | правила сопоставления входных утверждений с выходными утверждениями в проверяемых удостоверений |
credentialType |
строка (необязательно) | тип обязательных учетных данных внутри входных данных |
required |
логическое значение (по умолчанию false) | указывает, является ли эта аттестация обязательной или нет |
trustedIssuers |
строка (массив) | список идентификаторов DID, которые могут выдавать проверяемые удостоверения для этого контракта. |
Тип selfIssuedAttestation
Свойство | Type | Description |
---|---|---|
mapping |
claimMapping (необязательно) | правила сопоставления входных утверждений с выходными утверждениями в проверяемых удостоверений |
required |
логическое значение (по умолчанию false) | указывает, является ли эта аттестация обязательной или нет |
Тип accessTokenAttestation
Свойство | Type | Description |
---|---|---|
mapping |
claimMapping (необязательно) | правила сопоставления входных утверждений с выходными утверждениями в проверяемых удостоверений |
required |
логическое значение (по умолчанию false) | указывает, является ли эта аттестация обязательной или нет |
Для свойства
inputClaim
поддерживаются следующие значенияmappings
:givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
,photo
.
Тип claimMapping
Свойство | Type | Description |
---|---|---|
inputClaim |
строка | имя утверждения, используемого из входных данных |
outputClaim |
строка | имя утверждения в проверяемых удостоверений |
indexed |
логическое значение (по умолчанию false) | указывает, используется ли значение этого утверждения для поиска; Индексировать можно только один объект clientMapping для каждого заданного контракта. |
required |
логическое значение (по умолчанию false) | указывает, является ли это сопоставление обязательным или нет |
type |
строка (необязательно) | тип утверждения |
Тип customStatusEndpoint
Свойство | Type | Description |
---|---|---|
url |
Строка (URL-адрес) | URL-адрес пользовательской конечной точки состояния |
type |
строка | тип конечной точки |
Пример:
"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
Свойство | Type | Description |
---|---|---|
locale |
строка | языковая настройка данного отображения |
credential |
displayCredential | свойства отображения проверяемых удостоверений |
consent |
displayConsent | дополнительные данные при выдаче проверяемых удостоверений |
claims |
Массив displayClaims | метки для утверждений, включенных в проверяемые удостоверения |
Тип displayCredential
Свойство | Type | Description |
---|---|---|
title |
строка | название учетных данных |
issuedBy |
строка | имя издателя учетных данных |
backgroundColor |
число (шестнадцатеричное значение) | цвет фона учетных данных в шестнадцатеричном формате, например #FFAABB |
textColor |
число (шестнадцатеричное значение) | цвет текста учетных данных в шестнадцатеричном формате, например #FFAABB |
description |
строка | дополнительный текст, отображаемый рядом с каждыми учетными данными |
logo |
displayCredentialLogo | логотип, используемый для учетных данных |
Тип displayCredentialLogo
Свойство | Type | Description |
---|---|---|
uri |
string (URI) | URI логотипа. Если значение является URL-адресом, оно должно быть доступно через общедоступный Интернет анонимно. |
description |
строка | описание логотипа |
Тип displayConsent
Свойство | Type | Description |
---|---|---|
title |
строка | название согласия |
instructions |
строка | дополнительный текст, используемый при отображении согласия |
Тип displayClaims
Свойство | Type | Description |
---|---|---|
label |
строка | метка утверждения в отображении |
claim |
строка | имя утверждения, для которого применяется метка |
type |
строка | тип утверждения |
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"
}
]
}
]
}
List contracts
Этот API перечисляет все контракты, настроенные в текущем клиенте для указанного центра авторизации.
HTTP-запрос
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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}]
}
]
}
Create contract
При создании контракта имя, которое вы используете, должно быть уникальным в клиенте. Если вы создаете несколько центров, имя контракта должно быть уникальным для всех органов. Имя контракта является частью URL-адреса контракта, используемого в запросах на выдачу.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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
}
Подтверждение компетенции
Эта конечная точка позволяет выполнять поиск выданных проверяемых удостоверений, проверять состояние отзыва и отзывать удостоверения.
Методы
Методы | Тип возвращаемых данных | Description |
---|---|---|
Get credential | Подтверждение компетенции | Чтение свойств удостоверения |
Search credentials | Коллекция удостоверений | Поиск списка удостоверений с определенным значением утверждения |
Revoke credential | Отзыв определенного удостоверения |
Get credential
Этот API позволяет получить определенное удостоверение и проверить его состояние, то есть отозвано ли он или нет.
HTTP-запрос
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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"
}
Search credentials
Вы можете искать проверяемые удостоверения по определенным утверждениям индекса. Так как в индексе сохраняется только хэш, поиск можно выполнять только по конкретному вычисляемому значению. Используется алгоритм хэширования Base64Encode(SHA256(ИД контракта + значение утверждения)) Пример для 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 );
}
В следующем запросе показано, как добавить вычисляемое значение в параметр фильтра в запросе.
HTTP-запрос
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | 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"
}
]
}
Revoke credential
Этот API позволяет отозвать определенное удостоверение, найденное через API поиска. Чтобы отозвать удостоверение, нужно указать точный идентификатор этого удостоверения.
HTTP-запрос
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | application/json |
Текст запроса
Не указывайте текст запроса для этого метода.
Сообщение ответа
HTTP/1.1 204 No Content
Content-type: application/json
Отказ от согласия
Этот метод удаляет все экземпляры проверяемой службы учетных данных в этом клиенте. При этом удаляются и все настроенные контракты. Все выданные проверяемые удостоверения после этого не могут быть проверены отзыв. Это действие невозможно отменить.
Предупреждение
Это действие не может быть отменено и отменяет все выданные проверяемые учетные данные и созданные контракты.
HTTP-запрос
POST /v1.0/verifiableCredentials/optout
Заголовки запросов
Заголовок | Значение |
---|---|
Авторизация | Носитель (маркер). Обязательное поле |
Тип контента | application/json |
Текст запроса
Не предоставляйте для этого метода текст запроса.
Сообщение ответа
Пример ответного сообщения:
HTTP/1.1 200 OK
Content-type: application/json
OK
Комментарий
Примечание.
Если у вас нет разрешений на удаление в Key Vault, мы возвращаем сообщение об ошибке и по-прежнему отключаем