Спецификация выдачи REST API службы запросов

Статья
10/28/2023

Проверенные учетные данные Microsoft Entra включают REST API службы запросов. Этот API позволяет выдавать и проверять учетные данные. В данной статье описывается, как указать REST API службы запросов для запроса на выдачу. В другой статье описывается, как вызвать REST API службы запросов.

HTTP-запрос

Запрос на выдачу REST API службы запросов поддерживает следующий метод HTTP:

Способ	Примечания.
POST	С полезными данными JSON, как указано в этой статье.

Запрос на выдачу REST API службы запросов поддерживает следующие заголовки HTTP:

Имя.	Значение
`Authorization`	Вложите маркер доступа в качестве маркера носителя в заголовок авторизации в HTTP-запросе. Например, `Authorization: Bearer <token>`.
`Content-Type`	`application/json`

Создайте HTTP-запрос POST к REST API службы запросов.

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

Приведенный ниже HTTP-запрос демонстрирует запрос к REST API службы запросов:

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

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

Для вызова REST API службы запросов требуется приведенное разрешение. Дополнительные сведения см. в статье Настройка арендатора для использования службы проверяемых удостоверений Azure AD (предварительная версия).

Тип разрешения	Разрешение
Приложение	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Полезные данные запроса на выдачу

Полезные данные запроса на выдачу содержат сведения о запросе на выдачу проверяемого удостоверения. В следующем примере демонстрируется запрос на выдачу с использованием потока PIN-кода с пользовательскими утверждениями, такими как имя и фамилия. Результатом этого запроса является QR-код со ссылкой для запуска процесса выдачи.

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

Полезная нагрузка содержит следующие свойства:

Параметр	Тип	Описание
`includeQRCode`	Boolean	Определяет, включается ли QR-код в ответ на этот запрос. Представьте QR-код и попросите пользователя просканировать его. После сканирования QR-кода запускается приложение проверки подлинности с данным запросом на выдачу. Возможные значения: `true` (по умолчанию) или `false`. Если задано значение `false`, используйте возвращаемое свойство `url` для отображения прямой ссылки.
`callback`	Callback	Обязательно. Позволяет разработчику асинхронно получать информацию о потоке во время процесса выдачи проверяемого удостоверения. Например, разработчику может потребоваться выполнять вызов после того, как пользователь просканировал QR-код, или в случае успешного выполнения или сбоя запроса на выдачу.
`authority`	строка	Децентрализованный идентификатор издателя (DID). Дополнительные сведения см. в разделе Получение сведений об удостоверении и среде для настройки приложения.
`registration`	RequestRegistration	Предоставляет сведения об издателе, которые могут быть отображены в приложении проверки подлинности.
`type`	строка	тип проверяемого удостоверения; Должен соответствовать типу, определенному в манифесте проверяемого удостоверения. Например: `VerifiedCredentialExpert`. Дополнительные сведения см. в разделе Создание карточки эксперта с проверенным удостоверением в Azure.
`manifest`	строка	URL-адрес документа манифеста проверяемого удостоверения. Дополнительные сведения см. в разделе Получение сведений об удостоверении и среде для настройки приложения.
`claims`	строка	Необязательно. Можно использовать только для потока аттестации маркеров идентификатора, чтобы включить коллекцию утверждений, сделанных о субъекте в проверяемые учетные данные.
`pin`	КОНТАКТНЫЙ	Необязательно. Пин-код можно использовать только с потоком аттестации маркеров идентификатора. PIN-код для обеспечения дополнительной защиты во время выдачи. Вы создаете PIN-код и предоставляете его пользователю в своем приложении. Пользователь должен предоставить созданный вами PIN-код.
`expirationDate`	строка	Необязательно. Срок действия срока действия можно использовать только с потоком аттестации маркеров идентификатора. Если задано, значение должно быть датой, выраженной в формате ISO8601 . Дата переопределит допустимостьInterval в определении правил учетных данных для этого запроса на выдачу. Используйте этот параметр для явного управления сроком действия учетных данных, например окончания дня, окончания или конца года, независимо от того, когда он будет выдан. Обратите внимание, что дата выражена в формате UTC. Если указать конец года, если задано `23:59:59`значение времени , то есть 1 секунда до полуночи в формате UTC. Любой пользователь в другом часовом поясе получит дату окончания срока действия, представленную в локальном часовом поясе в Microsoft Authenticator. Это означает, что если вы находитесь в часовом поясе CET, оно будет представлено как 1 января 1 утра. Контракт учетных данных должен иметь флаг allowOverrideValidityOnIssuance , равный true.

В настоящее время существует четыре типа аттестации утверждений, которые можно отправить в полезных данных. Проверенный идентификатор Microsoft Entra использует четыре способа вставки утверждений в проверяемые удостоверения и подтверждения этой информации с помощью DID издателя. Ниже перечислены эти четыре типа:

Маркер идентификации
Указание для маркера идентификации
Проверяемые удостоверения посредством проверяемой презентации.
Самопроверяемые утверждения

Подробные сведения о типах входных данных см. в статье Настройка проверяемых учетных данных.

Тип RequestRegistration

Тип RequestRegistration обеспечивает регистрацию сведений для издателя. Тип RequestRegistration содержит перечисленные ниже свойства.

Свойство	Type	Описание:
`clientName`	строка	Отображаемое имя издателя проверяемого удостоверения.
`logoUrl`	строка	Необязательно. URL-адрес логотипа издателя.
`termsOfServiceUrl`	строка	Необязательно. URL-адрес условий использования проверяемого удостоверения, которое вы выдаете.

Примечание.

В настоящее время сведения RequestRegistration не отображаются во время выдачи в приложении Microsoft Authenticator. Однако эти сведения можно использовать в полезных данных.

Тип обратного вызова

REST API службы запросов создает несколько событий для конечной точки обратного вызова. Эти события позволяют обновить пользовательский интерфейс и продолжить процесс после возврата результатов в приложение. Тип Callback содержит перечисленные ниже свойства.

Свойство	Type	Описание:
`url`	строка	Универсальный код ресурса (URI) конечной точки обратного вызова приложения. Универсальный код ресурса (URI) должен указывать на достижимую конечную точку в Интернете. В противном случае служба выдаст ошибку о невозможности прочитать URL-адрес обратного вызова. Допустимые форматы: IPv4, IPv6 или разрешаемое DNS-имя узла.
`state`	строка	Сопоставляет событие обратного вызова со статусом, переданным в исходных полезных данных.
`headers`	строка	Необязательно. Можно включить коллекцию заголовков HTTP, требуемых стороной, принимающей сообщение POST. Текущие поддерживаемые значения заголовка — заголовки `api-key` или `Authorization`. Любой другой заголовок приведет к ошибке недопустимого заголовка обратного вызова

Тип pin

Тип pin определяет PIN-код, который может отображаться при выдаче. pin является необязательным и, если используется, всегда должен отправляться по внешнему каналу. При использовании PIN-кода на основе хэша необходимо определить свойства salt, alg и iterations. pin содержит следующие свойства:

Свойство	Type	Описание:
`value`	строка	Содержит значение PIN-кода в виде обычного текста. Если вы используете хэшированный PIN-код, то свойство value содержит случайный хэш в формате Base64.
`type`	строка	Тип PIN-кода. Возможное значение: `numeric` (по умолчанию).
`length`	integer	Длина PIN-кода. Длина по умолчанию равна 6, минимальная длина — 4, а максимальная — 16.
`salt`	строка	Соль хэшированного PIN-кода. Соль добавляется в начало кода при вычислении хэша. Кодировка: UTF-8.
`alg`	строка	Алгоритм хэширования для хэшированного PIN-кода. Поддерживаемый алгоритм: `sha256`.
`iterations`	integer	Число итераций хэширования. Возможное значение: `1`.

Успешный ответ

В случае успешного выполнения этот метод возвращает код ответа (HTTP 201 Created) и коллекцию объектов event в тексте ответа. В следующем примере JSON показан успешный ответ:

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

Результат содержит следующие свойства.

Свойство	Type	Описание:
`requestId`	строка	Автоматически сформированный идентификатор запроса. Обратный вызов использует тот же запрос, что позволяет отслеживать запрос на выдачу и его обратные вызовы.
`url`	строка	URL-адрес, который запускает приложение проверки подлинности и запускает процесс выдачи. Вы можете предоставить этот URL-адрес пользователю, если он не может просканировать QR-код.
`expiry`	integer	Указывает, когда истечет срок действия ответа.
`qrCode`	строка	QR-код, который пользователь может просканировать для запуска потока выдачи.

Когда ваше приложение получает ответ, оно должно предоставить пользователю QR-код. Пользователь сканирует QR-код, который открывает приложение проверки подлинности и запускает процесс выдачи.

Отклик в случае ошибки

При возникновении ошибки с запросом возвращается ответ на ошибку и должен обрабатываться соответствующим образом приложением.

События обратного вызова

Конечная точка обратного вызова вызывается, когда пользователь сканирует QR-код, использует прямую ссылку на приложение проверки подлинности или завершает процесс выдачи.

Свойство	Type	Описание:
`requestId`	строка	Сопоставляется с исходным запросом при отправке полезных данных в службу проверяемых удостоверений.
`requestStatus`	строка	Состояние, возвращенное для запроса. Возможные значения: `request_retrieved`: пользователь просканировал QR-код или выбрал ссылку, которая запускает поток выдачи. `issuance_successful`: выдача проверяемого удостоверения выполнена успешно. `issuance_error`: при выдаче произошла ошибка. Дополнительные сведения см. в свойстве `error` .
`state`	строка	Возвращает значение состояния, переданное в исходные полезные данные.
`error`	error	Если свойство `code` имеет значение `issuance_error`, то это свойство содержит сведения об ошибке.
`error.code`	строка	Возвращаемый код ошибки.
`error.message`	строка	Сообщение об ошибке.

В следующем примере показаны полезные данные обратного вызова, когда приложение проверки подлинности запускает запрос на выдачу:

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

В следующем примере показаны полезные данные обратного вызова после того, как пользователь успешно завершает процесс выдачи:

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

Ошибки обратного вызова

При вызове конечной точки обратного вызова может быть получено сообщение об ошибке. В следующей таблице перечислены коды ошибок.

Сообщение	Определение
`fetch_contract_error`	Не удалось получить контракт проверяемого удостоверения. Эта ошибка обычно возникает, когда API не может получить манифест, указанный в объекте RequestIssuance полезных данных запроса.
`issuance_service_error`	Служба проверяемых удостоверений не может проверить требования или обнаружена ошибка в проверяемом удостоверении.
`unspecified_error`	Эта ошибка встречается редко, но ее стоит изучить.

В следующем примере демонстрируется полезная нагрузка обратного вызова при возникновении ошибки:

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

Следующие шаги

Узнайте, как вызывать REST API службы запросов.

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