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

Статья
10/24/2024

Проверенные учетные данные 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 службы запросов. Теперь в URL-адресе не нужно указывать идентификатор tenantId, так как он присутствует в качестве утверждения в access_token.

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

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

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

{
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

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

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

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

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

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Полезные данные содержат перечисленные ниже свойства.

Параметр	Тип	Описание
`includeQRCode`	Boolean	Необязательно. Определяет, включается ли QR-код в ответ на этот запрос. Представьте QR-код и попросите пользователя просканировать его. После сканирования QR-кода запускается приложение проверки подлинности с данным запросом на представление. Возможные значения: `true` или `false` (по умолчанию). Если задано значение `false`, используйте возвращаемое свойство `url` для отображения прямой ссылки.
`includeReceipt`	Логический	Необязательно. Определяет, следует ли включать уведомление в ответ на этот запрос. Возможные значения: `true` или `false` (по умолчанию). Уведомление содержит исходные полезные данные, отправленные из приложения проверки подлинности в службу проверяемых удостоверений. Уведомление полезно для устранения неполадок и в тех случаях, когда нужно получить полные сведения о полезных данных. В остальных случаях не нужно по умолчанию присваивать этому параметру значение `true` . В запросе `OpenId Connect SIOP` уведомление содержит маркер идентификатора из исходного запроса.
`authority`	строка	Ваш децентрализованный идентификатор (DID) клиента Microsoft Entra проверяющего объекта. Дополнительные сведения см. в разделе Сбор сведений об арендаторе для настройки примера приложения.
`registration`	RequestRegistration	Предоставляет сведения о средстве проверки.
`callback`	Callback	Обязательно. Позволяет разработчику обновлять пользовательский интерфейс во время процесса представления проверяемого удостоверения. Когда пользователь завершает процесс, он продолжается после возвращения результатов в приложение.
`requestedCredentials`	коллекция	Представляет коллекцию объектов RequestCredential.

Тип RequestRegistration

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

Свойство	Type	Описание:
`clientName`	строка	Отображаемое имя проверяющего проверяющего учетных данных. Это имя будет представлено пользователю в приложении проверки подлинности.
`purpose`	строка	Необязательно. Строка, отображаемая для информирования пользователя о том, почему запрашиваются проверяемые учетные данные.
`logoUrl`	URL	Необязательно. URL-адрес для логотипа проверяющего элемента. Это не используется приложением Authenticator.
`termsOfServiceUrl`	URL	Необязательно. URL-адрес условий службы для проверяющего. Это не используется приложением Authenticator.

На следующем снимке экрана показано свойство clientName и отображаемое имя authority (средства проверки) в запросе на представление.

Снимок экрана, показывающий, как одобрить запрос на представление.

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

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

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

Тип RequestCredential

RequestCredential предоставляет сведения о запрашиваемых учетных данных, которые пользователь должен предоставить. RequestCredential содержит следующие свойства:

Свойство	Type	Описание:
`type`	строка	тип проверяемого удостоверения; `type` должен соответствовать типу, определенному в манифесте проверяемого удостоверения `issuer` (например, `VerifiedCredentialExpert`). Получение манифеста издателя описывается в разделе Получение сведений об удостоверении и среде для настройки приложения. Скопируйте URL-адрес выдачи учетных данных, откройте его в веб-браузере и проверьте свойство ID.
`purpose`	строка	Необязательно. Укажите сведения о цели запроса этого проверяемого удостоверения. Это не используется приложением Authenticator.
`acceptedIssuers`	Коллекция string	Необязательно. Коллекция идентификаторов DID издателей, которая может выдавать тип проверяемого удостоверения, представляемого субъектами. Чтобы получить DID издателя, ознакомьтесь со статьей Получение сведений об удостоверении и среде для настройки приложения и скопируйте значение децентрализованного идентификатора (DID). `acceptedIssuers` Если коллекция пуста или отсутствует, запрос презентации примет тип учетных данных, выданный любым издателем.
`configuration.validation`	Configuration.Validation	Необязательные параметры для проверки представления.
`constraints`	Ограничения	Необязательно. Коллекция ограничений утверждений.

Тип Configuration.Validation

Configuration.Validation предоставляет сведения о том, как должны проверяться учетные данные. Он содержит следующие свойства:

Свойство	Type	Описание
`allowRevoked`	Boolean	Необязательно. Определяет, следует ли принимать отозванные учетные данные. Значение по умолчанию — `false` (не принимать).
`validateLinkedDomain`	Логический	Необязательно. Определяет, следует ли проверять связанный домен. По умолчанию — `false`. Если для этого флага задано значение `false`, то вы в качестве приложения проверяющей стороны будете принимать учетные данные от непроверенного связанного домена. Если этот флаг имеет значение `true`, то связанный домен будет проверяться, и приниматься будут только проверенные домены.
`faceCheck`	faceCheck	Необязательно. Позволяет запрашивать проверку активности во время презентации.

Тип ограничений

Тип constraints содержит коллекцию ограничений утверждений, которые должны быть выполнены при выборе учетных данных кандидата. Это позволяет запрашивать учетные данные с определенным значением утверждения. Указанные ограничения будут использовать логику AND, т. е. если указать три ограничения, все из них должны быть выполнены. Для каждого ограничения в коллекции необходимо выбрать один операнды значений, содержать или запускатьwith. Значения не могут быть регулярными выражениями. Все сравнения не учитывает регистр.

Свойство	Type	Описание:
`claimName`	строка	Обязательно. Имя утверждения для ограничения. Это имя утверждения в проверяемых учетных данных. См. выходные данныеClaim в типе claimMapping.
`values`	Коллекция string	Набор значений, которые должны соответствовать значению утверждения. Если указать несколько значений, таких как ["красный", "зеленый", "синий"] это совпадение, если значение утверждения в учетных данных имеет любое из значений в коллекции.
`contains`	строка	Ограничение оценивается как true, если значение утверждения содержит указанное значение.
`startsWith`	строка	Ограничение оценивается как true, если значение утверждения начинается с указанного значения.

Тип faceCheck

Тип faceCheck содержит сведения о выполнении проверки активности во время представления учетных данных. Запрошенные учетные данные должны содержать фотографию владельца в утверждении с именем sourcePhotoClaimName. Презентация будет успешно выполнена, если проверка активности достигает уровня достоверности, равного или больше заданному в свойстве соответствияConfidenceThreshold. Если пороговое значение не выполнено, вся презентация завершится ошибкой.

Свойство	Type	Описание:
`sourcePhotoClaimName`	строка	Обязательно. Имя утверждения в учетных данных, содержащих фотографию. См. выходные данныеClaim в типе claimMapping.
`matchConfidenceThreshold`	integer	Необязательно. Конфиденциальное пороговое значение для успешной проверки между фотографией и данными о активности. Должно быть целым числом от 50 до 100. Значение по умолчанию — 70.

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

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

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "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-код или выбрал ссылку, которая запускает поток представления. `presentation_verified`: проверка проверяемого удостоверения успешно завершена. li>`presentation_error`: Произошла ошибка в презентации.
`state`	строка	Возвращает значение состояния, переданное в исходные полезные данные.
`subject`	строка	Идентификатор DID пользователя проверяемого удостоверения.
`verifiedCredentialsData`	array	Возвращает массив запрошенных проверяемых удостоверений. Для каждого проверяемого учетных данных он предоставляет: тип проверяемого удостоверения; DID издателя; полученные утверждения; домен издателя проверяемого удостоверения; состояние проверки домена издателя проверяемого удостоверения.
`receipt`	строка	Необязательно. Уведомление содержит исходные полезные данные, отправленные из кошелька в службу проверяемых удостоверений. Уведомление следует использовать только для устранения неполадок и отладки. Формат уведомления не фиксирован и может изменяться в зависимости от используемого кошелька и используемой версии.

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

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

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

{
  "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
  "requestStatus": "presentation_verified",
  "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
  "subject": "did:web:verifiedid.contoso.com",
  "verifiedCredentialsData": [
    {
      "issuer": "did:web:issuer...",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      },
      "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
      "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

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

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

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