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

Artigo
10/24/2024

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>

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

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

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` ou `false` (padrão). 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.

Captura de tela que mostra como aprovar a solicitação de apresentação.

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. Para proteger a sua rede, consulte as Perguntas frequentes.
`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 `api-key` cabeçalhos ou os `Authorization` 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 `acceptedIssuers` coleção estiver vazia ou não estiver presente, a 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/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:

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.

Partilhar via