Especificação de apresentação da API REST de Serviço de Solicitação

A ID Verificada do Microsoft Entra inclui a API REST do Serviço de Solicitação. Essa API permite emitir e verificar uma credencial. Este artigo especifica a API REST de Serviço de Solicitação para uma solicitação de apresentação. A solicitação de apresentação pede ao usuário para apresentar uma credencial verificável, e verificar a credencial. Outro artigo descreve como chamar a API REST do Serviço de Solicitação.

Solicitação HTTP

A solicitação de apresentação da API REST de Serviço de Solicitação dá suporte ao seguinte método HTTP:

A solicitação de apresentação da API REST de Serviço de Solicitação requer os seguintes cabeçalhos HTTP:

Construa uma solicitação HTTP POST para a API REST de Serviço de Solicitação. O tenantId não é mais necessário na URL, pois ele está presente como uma declaração no access_token.

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

A solicitação HTTP a seguir demonstra uma solicitação de apresentação para a API REST de Serviço de Solicitação:

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"
      }
    },
    ...
}

A permissão a seguir é necessária para chamar a API REST de Serviço de Solicitação. Para obter mais informações, consulte Conceder permissões para obter tokens de acesso.

Conteúdo da solicitação de apresentação

O conteúdo da solicitação de apresentação contém informações sobre sua solicitação de apresentação de credenciais verificáveis. O exemplo a seguir demonstra uma solicitação de apresentação de um emissor específico. O resultado dessa solicitação retorna um código QR com um link para iniciar o processo de apresentação.

{
  "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
        }
      }
    }
  ]
}

O conteúdo tem as propriedades a seguir.

Tipo RequestRegistration

O tipo RequestRegistration fornece o registro de informações para o emissor. O tipo RequestRegistration contém as propriedades a seguir:

A captura de tela a seguir mostra a propriedade clientName e o nome de exibição de authority (o verificador) na solicitação de apresentação.

Tipo de retorno de chamada

A API REST de Serviço de Solicitação gera vários eventos para o ponto de extremidade do retorno de chamada. Esses eventos permitem atualizar a interface do usuário e continuam o processo depois que os resultados são retornados para o aplicativo. O tipo Callback contém as propriedades a seguir:

Tipo RequestCredential

O RequestCredential fornece informações sobre as credenciais solicitadas que o usuário precisa fornecer. RequestCredential contém as propriedades a seguir:

Tipo de Configuration.Validation

O Configuration.Validation fornece informações sobre como as credenciais apresentadas devem ser validadas. Ele contém as propriedades a seguir:

Tipo de restrições

O tipo constraints contém uma coleção de restrições de declarações que devem ser atendidas quando uma carteira seleciona as credenciais do candidato. Isso permite solicitar uma credencial com valor de declaração específico. As restrições especificadas usarão a lógica AND, ou seja, se você especificar três restrições, todas elas precisarão ser atendidas. Para cada restrição na coleção, você deve selecionar um operando de valores, contém ou startsWith. Os valores não podem ser expressões regulares. Todas as comparações não diferenciam maiúsculas de minúsculas.

Tipo de faceCheck

O tipo faceCheck contém informações para executar a verificação de atividade durante a apresentação de uma credencial. A credencial solicitada deve conter uma foto do titular na declaração nomeada pelo sourcePhotoClaimName. A apresentação terá êxito se a verificação de atividade atingir um nível de confiança igual ou maior ao especificado na propriedade matchConfidenceThreshold. Se o limite não for atingido, toda a apresentação falhará.

Resposta bem-sucedida

Se for bem-sucedido, esse método retornará um código de resposta (HTTP 201 Criado) e uma coleção de objetos de evento no corpo da resposta. O JSON a seguir demonstra uma resposta bem-sucedida:

{
    "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>"
}

A resposta contém as seguintes propriedades:

Quando seu aplicativo recebe a resposta, ele precisa apresentar o código QR ao usuário. O usuário escaneia o código QR, que abre o aplicativo autenticador que inicia o processo de apresentação.

Resposta de erro

Se houver um erro com a solicitação, uma resposta de erro será retornada e deverá ser tratada adequadamente pelo aplicativo.

Eventos de retorno de chamada

O ponto de extremidade do retorno de chamada é chamado quando um usuário escaneia o código QR, usa o link profundo do aplicativo autenticador ou termina o processo de apresentação.

O exemplo a seguir demonstra o conteúdo do retorno de chamada quando o aplicativo autenticador inicia a solicitação de apresentação:

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

O exemplo a seguir demonstra o conteúdo do retorno de chamada após a apresentação de credencial verificável ter sido concluída com sucesso:

{
  "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": "..."
  }
}

Próximas etapas

Saiba como chamar a API REST de Serviço de Solicitação.