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

Artigo
02/06/2024

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:

Método	Observações
POST	Com o conteúdo do JSON, conforme especificado neste artigo.

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

Método	Valor
`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 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>

{
    "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 de 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
Aplicativo	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

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.

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

O conteúdo tem as propriedades a seguir.

Parâmetro	Tipo	Descrição
`includeQRCode`	Boolean	Opcional. Determina se um código QR está incluído na resposta dessa solicitação. Apresente o código QR e peça ao usuário para escaneá-lo. A verificação do código QR inicia o aplicativo autenticador com essa solicitação de apresentação. Os valores possíveis são `true` (padrão) ou `false`. Quando você tiver definido o valor para `false`, use a propriedade `url` return para apresentar um link profundo.
`includeReceipt`	Boolean	Opcional. Determina se um recibo deve ser incluído na resposta dessa solicitação. Os valores possíveis são `true` ou `false` (padrão). O recibo contém o conteúdo original enviado do autenticador para o serviço de Credencial Verificável. O recibo é útil para solução de problemas ou se você precisar obter os detalhes completos do conteúdo. Caso contrário, não é necessário definir esse valor como `true` por padrão. Na solicitação `OpenId Connect SIOP`, o recibo contém o token de ID da solicitação original.
`authority`	string	Seu identificador descentralizado (DID) do locatário do verificador do Microsoft Entra. Para obter mais informações, consulte Coletar detalhes do locatário para configurar seu aplicativo de exemplo.
`registration`	RequestRegistration	Fornece informações sobre o verificador.
`callback`	Retorno de chamada	Mandatory. Permite ao desenvolvedor atualizar a interface do usuário durante o processo de apresentação das credenciais verificáveis. Quando o usuário concluir o processo, continue depois que os resultados forem retornados ao aplicativo.
`requestedCredentials`	collection	Uma coleção de objetos RequestCredential.

Tipo RequestRegistration

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

Propriedade	Type	Descrição
`clientName`	string	Um nome de 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 ao usuário por que as credenciais verificáveis estão sendo solicitadas.
`logoUrl`	URL	Opcional. Uma URL para um logotipo do verificador. Isso não é usado pelo aplicativo Authenticator.
`termsOfServiceUrl`	URL	Opcional. Uma URL para os termos de serviço do verificador. Isso não é usado pelo aplicativo Authenticator.

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.

Captura de tela que mostra como aprovar a 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:

Propriedade	Type	Descrição
`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 emitirá um erro de uma URL de retorno de chamada ilegível. Os formatos de entrada aceitos são IPv4, IPv6 ou nome do host resolvível por DNS.
`state`	string	Correlaciona o evento de retorno de chamada com o estado passado no conteúdo original.
`headers`	string	Opcional. Você pode incluir uma coleção de cabeçalhos HTTP exigidos pela extremidade de recebimento da mensagem POST. Os valores de cabeçalho com suporte atuais são os cabeçalhos `api-key` ou `Authorization`. Qualquer outro cabeçalho resultará em erro de cabeçalho de retorno de chamada inválido.

Tipo RequestCredential

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

Propriedade	Type	Descrição
`type`	string	Tipo da credencial verificável. O `type` deve corresponder ao tipo conforme definido no `issuer`manifesto da credencial verificável (por exemplo, `VerifiedCredentialExpert`). Para obter o manifesto do emissor, consulte Coletar credenciais e detalhes do ambiente para configurar seu aplicativo de exemplo. Copie a URL de credencial da emissão, abra-a 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 da cadeia de caracteres	Opcional. Uma coleção de DIDs dos emissores que poderia emitir o tipo de credencial verificável que os assuntos podem apresentar. Para obter o DID do emissor, consulte Coletar credenciais e detalhes do ambiente para configurar seu aplicativo de exemplo e copie o valor do DID (identificador descentralizado) . Se a coleção `acceptedIssuers` estiver vazia ou ausente, a solicitação de apresentação aceitará um tipo de credencial emitido por qualquer emissor.
`configuration.validation`	Configuration.Validation	Configurações opcionais para validação de apresentação.
`constraints`	Restrições	Opcional. Coleção de restrições de declarações.

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:

Propriedade	Type	Descrição
`allowRevoked`	Boolean	Opcional. Ele determina se uma credencial revogada deve ser aceita. O padrão é `false` (não deve ser aceita).
`validateLinkedDomain`	Boolean	Opcional. Determina se o domínio vinculado deve ser validado. O padrão é `false`. Definir esse sinalizador como `false` significa que você, como um aplicativo de Terceira Parte Confiável, aceita credenciais de um domínio vinculado não verificado. Definir esse sinalizador como `true` significa que o domínio vinculado será validado e somente domínios verificados serão aceitos.
`faceCheck`	faceCheck	Opcional. Permite solicitar uma verificação de atividade durante a apresentação.

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.

Propriedade	Type	Descrição
`claimName`	string	Mandatory. Nome da declaração para a restrição. Esse é o nome da declaração na credencial verificável. Consulte outputClaim no tipo claimMapping.
`values`	coleção da cadeia de caracteres	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 será avaliada como true se o valor da declaração contiver o valor especificado.
`startsWith`	string	A restrição será avaliada como true se o valor da declaração começar com o valor especificado.

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á.

Propriedade	Type	Descrição
`sourcePhotoClaimName`	string	Mandatory. O nome da declaração na credencial que contém a foto. Consulte outputClaim no tipo claimMapping.
`matchConfidenceThreshold`	Número inteiro	Opcional. O limite confidencial para uma verificação bem-sucedida entre a foto e os dados de atividade. Deverá ser um número inteiro entre 50 e 100. O padrão é 70.

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/12345678-0000-0000-0000-000000000000/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

A resposta contém as seguintes propriedades:

Propriedade	Type	Descrição
`requestId`	Cadeia de caracteres	Uma ID da solicitação gerada automaticamente. O retorno de chamada usa a mesma solicitação, permitindo acompanhar a solicitação de apresentação e seus retornos de chamada.
`url`	string	Uma URL que inicializa o aplicativo autenticador e inicia o processo de apresentação. Você poderá apresentar essa URL ao usuário se ele não puder escanear o código QR.
`expiry`	inteiro	Indica quando a resposta terá expirado.
`qrCode`	Cadeia de caracteres	Um código QR que o usuário pode escanear para iniciar o fluxo de apresentação.

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.

Propriedade	Type	Descrição
`requestId`	Cadeia de caracteres	Mapeado para a solicitação original quando o conteúdo foi postado no serviço de credenciais verificáveis.
`requestStatus`	string	O status retornado 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 da 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 no conteúdo original.
`subject`	string	DID do usuário da credencial verificável.
`verifiedCredentialsData`	array	Retorna uma matriz de credenciais verificáveis solicitadas. Para cada credencial verificável, ela fornece: Os tipos de credencial verificável. O DID do emissor As declarações recuperadas. O domínio do emissor da credencial verificável. O status de validação do domínio do emissor da credencial verificável.
`receipt`	string	Opcional. O recibo contém o conteúdo original enviado da carteira para o serviço de Credencial Verificável. O recibo deve ser usado somente para solução de problemas/depuração. O formato do recibo não é fixo e pode mudar com base na carteira e na versão usada.

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.