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

A ID Verificada do Microsoft Entra inclui a API REST do Serviço de Solicitação. Essa API permite que você emita e verifique uma credencial. Este artigo especifica a API REST do Serviço de Solicitação para uma solicitação de apresentação. A solicitação de apresentação solicita que o usuário apresente uma credencial verificável e, em seguida, verifique a credencial. Outro artigo descreve como chamar a API REST do Serviço de Solicitação.

Pedido HTTP

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

Método Notas
POST Com carga JSON conforme especificado neste artigo.

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

Método Value
Authorization Anexe o token de acesso como um token de portador ao cabeçalho de autorização em uma solicitação HTTP. Por exemplo, Authorization: Bearer <token>.
Content-Type Application/json

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

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

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

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": "11111111-2222-2222-2222-333333333333",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

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

Tipo de permissão Permissão
Aplicação 3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Carga útil do pedido de apresentação

A carga útil 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 deste pedido devolve um código QR com um link para iniciar o processo de apresentação.

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

A carga útil contém as seguintes propriedades.

Parâmetro Tipo Descrição
includeQRCode Booleano Opcional. Determina se um código QR está incluído na resposta a este pedido. Apresente o código QR e peça ao utilizador para o digitalizar. A digitalização do código QR inicia o aplicativo autenticador com esta solicitação de apresentação. Os valores possíveis são true (padrão) ou false. Ao definir o valor como false, use a propriedade return url para renderizar um link direto.
includeReceipt Boolean Opcional. Determina se um recibo deve ser incluído na resposta a esta solicitação. Os valores possíveis são true ou false (padrão). O recibo contém a carga original enviada do autenticador para o serviço de Credenciais Verificáveis. O recibo é útil para a solução de problemas ou se você tiver a necessidade de verificar todos os detalhes da carga útil. Caso contrário, não há necessidade de definir esse valor como true padrão. OpenId Connect SIOP Na solicitação, o recibo contém o token de ID da solicitação original.
authority string O seu identificador descentralizado (DID) do seu inquilino verificador Microsoft Entra. Para obter mais informações, consulte Reunir detalhes do locatário para configurar seu aplicativo de exemplo.
registration PedidoRegisto Fornece informações sobre o verificador.
callback Retorno de chamada Obrigatório. Permite que o desenvolvedor atualize a interface do usuário durante o processo de apresentação de credenciais verificáveis. Quando o usuário concluir o processo, continue o processo depois que os resultados forem retornados ao aplicativo.
requestedCredentials Coleção Uma coleção de objetos RequestCredential .

Tipo de RequestRegistration

O RequestRegistration tipo fornece informações de registro para o emitente. O RequestRegistration tipo contém as seguintes propriedades:

Propriedade Type Description
clientName string Um nome para exibição do verificador da credencial verificável. Esse nome será apresentado ao usuário no aplicativo autenticador.
purpose string Opcional. Uma cadeia de caracteres que é exibida para informar o usuário por que as credenciais verificáveis estão sendo solicitadas.
logoUrl URL Opcional. Um URL para um logotipo do verificador. Isso não é usado pelo aplicativo Authenticator.
termsOfServiceUrl URL Opcional. Um URL para os termos de serviço do verificador. Isso não é usado pelo aplicativo Authenticator.

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

Screenshot that shows how to approve the presentation request.

Tipo de retorno de chamada

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

Propriedade Type Description
url string URI para o ponto de extremidade de retorno de chamada do seu aplicativo. O URI deve apontar para um ponto de extremidade acessível na Internet, caso contrário, o serviço lançará um erro de URL de retorno de chamada ilegível. Entradas aceites IPv4, IPv6 ou nome de anfitrião resolúvel DNS.
state string Correlaciona o evento de retorno de chamada com o estado passado na carga útil original.
headers string Opcional. Você pode incluir uma coleção de cabeçalhos HTTP exigidos pela extremidade recetora da mensagem POST. Os valores de cabeçalho suportados atuais são os cabeçalhos ou os api-keyAuthorization cabeçalhos. Qualquer outro cabeçalho lançará um erro de cabeçalho de retorno de chamada inválido.

Tipo de RequestCredential

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

Propriedade Type Description
type string O tipo de credencial verificável. O type deve corresponder ao tipo conforme definido no manifesto de issuer credenciais verificável (por exemplo, VerifiedCredentialExpert). Para obter o manifesto do emissor, consulte Reunir credenciais e detalhes do ambiente para configurar seu aplicativo de exemplo. Copie o URL da credencial de problema, abra-o em um navegador da Web e verifique a propriedade id.
purpose string Opcional. Forneça informações sobre a finalidade de solicitar essa credencial verificável. Isso não é usado pelo aplicativo Authenticator.
acceptedIssuers Coleção String Opcional. Uma coleção de DIDs dos emitentes que poderiam emitir o tipo de credencial verificável que os sujeitos podem apresentar. Para obter o DID do emissor, consulte Reunir credenciais e detalhes do ambiente para configurar seu aplicativo de exemplo e copie o valor do identificador descentralizado (DID). Se a coleção estiver vazia ou não estiver presente, a acceptedIssuers solicitação de apresentação aceitará um tipo de credencial emitido por qualquer emissor.
configuration.validation Configuração.Validação Configurações opcionais para validação de apresentação.
constraints Restrições Opcional. Cobrança de restrições de sinistros.

Tipo Configuration.Validation

O Configuration.Validation fornece informações sobre como as credenciais apresentadas devem ser validadas. Contém as seguintes propriedades:

Propriedade Type Descrição
allowRevoked Booleano Opcional. Determina se uma credencial revogada deve ser aceita. O padrão é false (não deve ser aceito).
validateLinkedDomain Boolean Opcional. Determina se o domínio vinculado deve ser validado. A predefinição é false. Definir esse sinalizador significa false que você, como um aplicativo de terceira parte confiável, aceita credenciais de um domínio vinculado não verificado. Definir esse sinalizador significa true que o domínio vinculado será validado e apenas domínios verificados serão aceitos.
faceCheck FaceCheck Opcional. Permite solicitar uma verificação de vivacidade durante a apresentação.

Tipo de restrições

O constraints tipo 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 devem 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.

Propriedade Type Description
claimName string Obrigatório. Nome da reivindicação para a restrição. Este é o nome da declaração na credencial verificável. Consulte outputClaim no tipo claimMapping.
values Coleção String Conjunto de valores que devem corresponder ao valor da declaração. Se você especificar vários valores, como ["vermelho", "verde", "azul"], será uma correspondência se o valor da declaração na credencial tiver qualquer um dos valores na coleção.
contains string A restrição é avaliada como true se o valor da declaração contiver o valor especificado.
startsWith string A restrição é avaliada como true se o valor da declaração começar com o valor especificado.

tipo faceCheck

O tipo faceCheck contém informações para realizar a verificação de vivacidade 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 será bem-sucedida se a verificação de vivacidade atingir um nível de confiança igual ou superior ao especificado na propriedade matchConfidenceThreshold. Se o limite não for atingido, toda a apresentação falhará.

Propriedade Type Description
sourcePhotoClaimName string Obrigatório. O nome da declaração na credencial que contém a foto. Consulte outputClaim no tipo claimMapping.
matchConfidenceThreshold integer Opcional. O limite confidencial para uma verificação bem-sucedida entre a foto e os dados de vivacidade. Deve ser um número inteiro entre 50 e 100. O padrão é 70.

Resposta com êxito

Se bem-sucedido, esse método retorna 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/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

A resposta contém as seguintes propriedades:

Propriedade Type Description
requestId string Um ID de solicitação gerado automaticamente. O retorno de chamada usa a mesma solicitação, permitindo que você acompanhe a solicitação de apresentação e seus retornos de chamada .
url string Um URL que inicia o aplicativo autenticador e inicia o processo de apresentação. Pode apresentar este URL ao utilizador se este não conseguir digitalizar o código QR.
expiry integer Indica quando a resposta expirará.
qrCode string Um código QR que o usuário pode digitalizar para iniciar o fluxo de apresentação.

Quando seu aplicativo recebe a resposta, o aplicativo precisa apresentar o código QR ao usuário. O usuário escaneia o código QR, que abre o aplicativo autenticador e 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 de retorno de chamada é chamado quando um usuário escaneia o código QR, usa o link profundo do aplicativo autenticador ou conclui o processo de apresentação.

Propriedade Type Description
requestId string Mapeado para a solicitação original quando a carga foi postada no serviço de Credenciais Verificáveis.
requestStatus string O status retornou quando a solicitação foi recuperada pelo aplicativo autenticador. Valores possíveis:
  • request_retrieved: O usuário escaneou o código QR ou selecionou o link que inicia o fluxo de apresentação.
  • presentation_verified: A validação de credencial verificável foi concluída com êxito.
  • li>presentation_error: Houve um erro na apresentação.
state string Retorna o valor de estado que você passou na carga original.
subject string O usuário de credencial verificável FEZ.
verifiedCredentialsData matriz Retorna uma matriz de credenciais verificáveis solicitadas. Para cada credencial verificável, ele fornece:
  • O(s) tipo(s) de credencial verificável(is).
  • O DID do emitente
  • Os créditos recuperados.
  • O domínio do emissor de credenciais verificável.
  • O status de validação de domínio do emissor de credenciais verificável.
  • receipt string Opcional. O recibo contém a carga original enviada da carteira para o serviço de Credenciais Verificáveis. O recibo deve ser usado apenas para solução de problemas/depuração. O formato no recibo não é fixo e pode mudar com base na carteira e versão usada.

    O exemplo a seguir demonstra uma carga de 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 uma carga de retorno de chamada após a apresentação de credenciais verificáveis ter sido concluída com êxito:

    {
      "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óximos passos

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