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

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

HTTP-запрос

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

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

Создайте 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>

{
    "includeQRCode": true,
    "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 (предварительная версия).

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

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

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:web:verifiedid.contoso.com",
  "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
        }
      }
    }
  ]
}

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

Тип RequestRegistration

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

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

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

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

Тип RequestCredential

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

Тип Configuration.Validation

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

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

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

Тип faceCheck

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

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

В случае успешного выполнения этот метод возвращает код ответа (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>"
}

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

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

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

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

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

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

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

{
    "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 службы запросов.