API администратора для проверяемых удостоверений

Статья
02/26/2024

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. Маркер доступа должен быть для пользователя с ролью глобального администратора или ролью администратора политики проверки подлинности . Пользователь с глобальной функцией чтения ролей может выполнять вызовы API только для чтения.

Маркеры носителя приложений

Служба 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 должен быть повторно зарегистрирован для отражения обновления. По завершении синхронизацияWithDidDocument сообщает системе начать использование нового ключа для подписывания.

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
}

Создание ключа подписи

Ключ подписывания создает новый закрытый ключ в уже существующем 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 изменено на outOfSyncpublished успешный вызов.

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, если пользователи будут получать уведомление о готовности к выдаче этого проверяемого удостоверения
`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, mail, 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 );
  }

В следующем запросе показано, как добавить вычисляемое значение в параметр фильтра в запросе. На данный момент поддерживается только формат eq filter=indexclaimhash eq.

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, возвращается сообщение об ошибке, но отказ успешно фиксируется

Поделиться через

API администратора для проверяемых удостоверений

Базовый URL-адрес

Проверка подлинности

Маркеры носителя пользователей

Маркеры носителя приложений

Переход

HTTP-запрос

Заголовки запросов

Текст запроса

Возвращаемое сообщение

Полномочия

Методы

Получение центра авторизации

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Тип центра авторизации

Тип didModel

Интернет

Тип keyVaultMetadata

Список центров авторизации

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Создание центра авторизации

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Замечания

Обновление центра авторизации

HTTP-запрос

Заголовки запросов

Текст запроса

Удаление центра

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Хорошо известная конфигурация DID

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Замечания

Создание документа DID

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Комментарий

Проверка хорошо известной конфигурации DID

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Смена ключа подписывания

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Создание ключа подписи

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Синхронизация с документом DID

HTTP-запрос

Заголовки запросов

Текст запроса

Сообщение ответа

Контракты

Методы

Get contract

HTTP-запрос

Заголовки запросов

Текст запроса