Pedido de serviço REST API especificação de apresentação

Nota

Azure Ative Directory Verifiable Credentials é agora ID Verificada do Microsoft Entra e faz parte da família Microsoft Entra de produtos. Saiba mais sobre a Microsoft Entra família de soluções identitárias e iniciou-se no centro de administração Microsoft Entra unificado.

ID Verificada do Microsoft Entra inclui o Serviço de Pedido REST API. Esta API permite-lhe emitir e verificar uma credencial. Este artigo especifica o Serviço de Pedido REST API para um pedido de apresentação. O pedido de apresentação solicita ao utilizador que apresente uma credencial verificável e, em seguida, verifique a credencial. Outro artigo descreve como chamar a API do Serviço de Pedidos REST.

Pedido HTTP

O pedido de apresentação da API do Serviço de Pedidos de Apoio suporta o seguinte método HTTP:

Método Notas
POST Com a carga útil JSON, conforme especificado neste artigo.

O pedido de apresentação da API do Serviço de Pedidos DE ASSISTÊNCIA requer os seguintes cabeçalhos HTTP:

Método Valor
Authorization Anexe o token de acesso como símbolo portador do cabeçalho de autorização num pedido HTTP. Por exemplo, Authorization: Bearer <token>.
Content-Type Application/json

Construa um pedido HTTP POST para o Serviço de Pedido REST API. O tenantId não é mais necessário na URL, uma vez que está presente como uma reivindicação no access_token.

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

O seguinte pedido HTTP demonstra um pedido de apresentação à API do Serviço de Pedidos:

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "includeQRCode": true,
    "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallbac",
    "state": "11111111-2222-2222-2222-333333333333",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

É necessária a seguinte permissão para ligar para a API do Serviço de Pedidos. Para mais informações, consulte as permissões do Grant para obter fichas 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 do pedido de apresentação contém informações sobre o seu pedido de apresentação de credenciais verificáveis. O exemplo a seguir demonstra um pedido de apresentação de um emitente 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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://www.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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

A carga útil contém as seguintes propriedades.

Parâmetro Tipo Description
includeQRCode Booleano 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 digitalizá-lo. A digitalização do código QR lança a aplicação autenticadora com este pedido de apresentação. Os valores possíveis são true (padrão) ou false. . Quando definir o valor para false, use a propriedade de retorno url para tornar um elo profundo.
includeReceipt Booleano Determina se um recibo deve ser incluído na resposta a este pedido. 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 Desídutos Verificáveis. O recibo é útil para a resolução de problemas ou se tiver a necessidade de obter todos os detalhes da carga útil. Caso contrário, não há necessidade de definir este valor true por defeito. OpenId Connect SIOP No pedido, o recibo contém o sinal de identificação do pedido original.
authority string O seu identificador descentralizado (DID) do seu verificador Azure AD inquilino. Para mais informações, consulte os detalhes do inquilino para configurar o seu pedido de amostra.
registration Registo de Pedidos Fornece informações sobre o verificador.
callback Chamada Obrigatório. Permite ao desenvolvedor atualizar a UI durante o processo de apresentação de credenciais verificáveis. Quando o utilizador concluir o processo, continue o processo após o retorno dos resultados à aplicação.
requestedCredentials coleção Uma coleção de objetos RequestCredential .

Tipo de Registo de Pedidos

O RequestRegistration tipo fornece registo de informação para o emitente. O RequestRegistration tipo contém as seguintes propriedades:

Propriedade Tipo Description
clientName cadeia (de carateres) Um nome de exibição do emitente da credencial verificável. Este nome será apresentado ao utilizador na aplicação autenticadora.

A imagem que se segue mostra a clientName propriedade e o nome de exibição do authority (verificador) no pedido de apresentação.

Screenshot que mostra como aprovar o pedido de apresentação.

Tipo de chamada

A API do Serviço de Pedidos gera vários eventos para o ponto final de retorno de chamada. Estes eventos permitem-lhe atualizar a UI e continuar o processo após o retorno dos resultados à aplicação. O Callback tipo contém as seguintes propriedades:

Propriedade Tipo Description
url cadeia (de carateres) URI para o ponto final de retorno da sua aplicação. O URI deve apontar para um ponto final acessível na internet, caso contrário o serviço irá lançar um erro ilegível de URL de retorno. Entradas aceites IPv4, IPv6 ou DNS resolvem o nome de anfitrião.
state string Correlaciona o evento de retorno com o estado aprovado na carga original.
headers string Opcional. Pode incluir uma coleção de cabeçalhos HTTP exigidos pela extremidade recetora da mensagem POST. Os valores atuais do cabeçalho suportado são os api-key ou os Authorization cabeçalhos. Qualquer outro cabeçalho irá lançar um erro inválido do cabeçalho de chamada.

Pedido Tipo de identificação

O RequestCredential fornece informações sobre as credenciais solicitadas que o utilizador precisa fornecer. RequestCredential contém as seguintes propriedades:

Propriedade Tipo Description
type cadeia (de carateres) O tipo de credencial verificável. O type deve coincidir com o tipo definido no issuer manifesto credencial verificável (por exemplo, VerifiedCredentialExpert). Para obter o manifesto do emitente, consulte as credenciais de recolha e detalhes do ambiente para configurar a sua aplicação de amostra. Copie o URL credencial de emissão, abra-o num navegador web e verifique a propriedade de id .
purpose string Fornecer informações sobre o propósito de solicitar esta credencial verificável.
acceptedIssuers coleção de cordas Uma coleção de DI dos emitentes que poderia emitir o tipo de credencial verificável que os sujeitos podem apresentar. Para obter o seu emitente DID, consulte recolher credenciais e detalhes ambientais para configurar a sua aplicação de amostra, e copiar o valor do identificador Descentralizado (DID). Se a acceptedIssuers coleção estiver vazia, o pedido de apresentação aceitará um tipo de credencial emitido por qualquer emitente.
configuration.validation Configuração.Validação Configurações opcionais para validação de apresentação.

Configuração.Tipo de validação

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

Propriedade Tipo Description
allowRevoked Booleano Determina se deve ser aceite uma credencial revogada. O padrão é false (não deve ser aceite).
validateLinkedDomain Booleano Determina se o domínio ligado deve ser validado. A predefinição é false. Definir esta bandeira significa false que você como uma aplicação Do Partido De Relying aceita credenciais de um domínio não verificado ligado. Definir esta bandeira significa true que o domínio ligado será validado e apenas serão aceites domínios verificados.

Resposta bem sucedida

Se for bem sucedido, este método devolve um código de resposta (HTTP 201 Criado) e uma coleção de objetos de evento no corpo de resposta. O seguinte JSON 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 Tipo Description
requestId cadeia (de carateres) Uma identificação de pedido autogerido. O retorno utiliza o mesmo pedido, permitindo-lhe acompanhar o pedido de apresentação e as suas chamadas.
url string Um URL que lança a aplicação autenticadora e inicia o processo de apresentação. Pode apresentar este URL ao utilizador se não puderem digitalizar o código QR.
expiry número inteiro Indica quando a resposta expirará.
qrCode string Um código QR que o utilizador pode digitalizar para iniciar o fluxo de apresentação.

Quando a sua aplicação recebe a resposta, a aplicação precisa de apresentar o código QR ao utilizador. O utilizador digitaliza o código QR, que abre a aplicação autenticadora e inicia o processo de apresentação.

Resposta de erro

Se houver um erro com o pedido, uma resposta de erro é devolvida e deve ser tratada adequadamente pela app.

Eventos de callback

O ponto final de retorno é chamado quando um utilizador digitaliza o código QR, utiliza o link profundo da aplicação autenticador ou termina o processo de apresentação.

Propriedade Tipo Description
requestId cadeia (de carateres) Mapeado para o pedido original quando a carga foi postada no serviço de Credenciais Verificáveis.
requestStatus string O estado de retorno quando o pedido foi recuperado pela aplicação autenticadora. Valores possíveis:
  • request_retrieved: O utilizador digitalizou o código QR ou selecionou o link que inicia o fluxo de apresentação.
  • presentation_verified: A validação credencial verificável foi concluída com sucesso.
state string Devolve o valor estatal que passou na carga original.
subject string O utilizador credencial verificável DID.
issuers matriz Devolve uma série de credenciais verificáveis solicitadas. Para cada credencial verificável, fornece:
  • O tipo de credencial verificável.
  • O emitente did
  • As reivindicações foram recuperadas.
  • O domínio do emitente de credencial verificável.
  • O estado de validação do domínio do emitente de credencial 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 utilizado apenas para a resolução/depuração de problemas. O formato no recibo não é corrigido e pode ser alterado com base na carteira e versão utilizadas.

    O exemplo a seguir demonstra uma carga de retorno quando a aplicação autenticadora inicia o pedido 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 após a apresentação de credencial verificável ter concluído com sucesso:

    {
      "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
      "requestStatus": "presentation_verified",
      "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "verifiedCredentialsData": [
        {
          "issuer": "did:ion:issuer",
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "credentialState": {
            "revocationStatus": "VALID"
          },
          "domainValidation": {
            "url": "https://contoso.com/"
          }
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
        "vp_token": "...",
        "state": "..."
      }
    }
    

    Passos seguintes

    Saiba como ligar para a API do Serviço de Pedidos.