Compartilhar via


Especificação de emissã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 emissão. Outro artigo descreve como chamar a API REST do Serviço de Solicitação.

Solicitação HTTP

A solicitação de emissã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 JSON, conforme especificado neste artigo.

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

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

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

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

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

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "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

Carga de solicitação de emissão

O conteúdo da solicitação de emissão contém informações sobre sua solicitação de emissão de credenciais verificáveis. O exemplo a seguir demonstra uma solicitação de emissão usando um fluxo de código PIN com declarações do usuário, como nome e sobrenome. O resultado dessa solicitação retorna um código QR com um link para iniciar o processo de emissão.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

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 emissão. Os valores possíveis são true ou false (padrão). Quando você tiver definido o valor para false, use a propriedade url return para apresentar um link profundo.
callback Retorno de chamada Mandatory. Permite que o desenvolvedor obtenha informações sobre o fluxo de forma assíncrona durante o processo de emissão de credenciais verificáveis. Por exemplo, o desenvolvedor pode querer solicitar uma chamada quando o usuário tiver examinado o código QR ou se a solicitação de emissão for bem-sucedida ou falhar.
authority Cadeia de caracteres O identificador descentralizado do emissor (DID). Para obter mais informações, consulte Reunir credenciais e detalhes do ambiente para configurar seu aplicativo de exemplo.
registration RequestRegistration Fornece informações sobre o emissor que pode ser exibido no aplicativo autenticador.
type string Tipo da credencial verificável. Deve corresponder ao tipo conforme definido no manifesto da credencial verificável do emissor. Por exemplo: VerifiedCredentialExpert. Para mais informações, confira Criar o cartão de especialista em credenciais verificáveis no Azure.
manifest string A URL do documento de manifesto de credencial verificável. Para obter mais informações, consulte Reunir credenciais e detalhes do ambiente para configurar seu aplicativo de exemplo.
claims string Opcional. Só pode ser usado para o fluxo de atestado de dica de token de ID para incluir uma coleção de declarações feitas sobre o assunto na credencial verificável.
pin PIN Opcional. O código PIN só pode ser usado com o fluxo de atestado Dica de token de ID. Um número PIN para fornecer segurança extra durante a emissão. Você gera um código PIN e o apresenta ao usuário em seu aplicativo. O usuário deve fornecer o código PIN que você gerou.
expirationDate string Opcional. O expirationDate só pode ser usado com o fluxo de atestado de dica de token de ID. Se especificado, o valor precisa ser uma data expressa no formato ISO8601. A data substituirá validityInterval na definição de regras de credenciais para esta solicitação de emissão. Use esta configuração para controlar explicitamente quando uma credencial expira, como fim do dia, fim do mês ou fim do ano, independentemente de quando for emitida. Observe que a data é expressa no formato UTC. Se você especificar o fim do ano, com o tempo definido como 23:59:59, isso é de 1 segundo antes da meia-noite no horário UTC. Qualquer usuário em um fuso horário diferente obterá a data de validade apresentada no fuso horário local no Microsoft Authenticator. Isso significa que, se você estiver no fuso horário CET, ela será apresentada como 1º de janeiro, 1h.

O contrato de credencial precisa ter o sinalizador allowOverrideValidityOnIssuance definido como true.

Atualmente, há quatro tipos de atestado de declarações que você pode enviar na payload. A ID Verificada do Microsoft Entra usa quatro maneiras de inserir declarações em uma credencial verificável e atestar essas informações com o DID do emissor. A seguir, estão os quatro tipos:

  • token de ID
  • Dica de token de ID
  • Credenciais verificáveis por meio de uma apresentação verificável
  • Declarações autoatestadas

Você pode encontrar informações detalhadas sobre os tipos de entrada em Personalizando suas credenciais verificáveis.

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 emissor da credencial verificável.
logoUrl string Opcional. A URL do logotipo do emissor.
termsOfServiceUrl string Opcional. A URL para os termos de uso da credencial verificável que você está emitindo.

Observação

Neste momento, as informações de RequestRegistration não são apresentadas durante a emissão no aplicativo Microsoft Authenticator. No entanto, essas informações podem ser usadas no payload.

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 URL de retorno de chamada ilegível. Formatos aceitos IPv4, IPv6 ou DNS resolvível nome de host. Para fortalecer sua rede, consulte Perguntas frequentes.
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 de pin

O tipo pin define um código PIN que pode ser exibido como parte da emissão. O pin é opcional e, se usado, deve sempre ser enviado fora de banda. Quando você estiver usando um PIN de código HASH, deverá definir as propriedades salt, alg e iterations. O pin contém as propriedades a seguir:

Propriedade Type Descrição
value string Contém o valor do PIN em texto sem formatação. Ao usar um PIN com hash, a propriedade value contém o hash de sal, codificado em base64.
type string O tipo do código PIN. Valor possível: numeric (padrão).
length inteiro O comprimento do código PIN. O comprimento padrão é 6, o mínimo é 4 e o máximo é 16.
salt Cadeia de caracteres O sal do código PIN com hash. O sal é anexado durante a computação de hash. Codificação = UTF-8.
alg string O algoritmo de hash para o PIN com hash. Algoritmo com suporte: sha256.
iterations inteiro O número de iterações de hash. Valor possível: 1.

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 emissão e seus retornos de chamada.
url string Uma URL que inicializa o aplicativo autenticador e inicia o processo de emissã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 string Um código QR que o usuário pode verificar para iniciar o fluxo de emissã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 e inicia o processo de emissã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 emissã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 para a solicitação. Valores possíveis:
  • request_retrieved: o usuário escaneou o código QR ou selecionou o link que inicia o fluxo de emissão.
  • issuance_successful: a emissão das credenciais verificáveis foi bem-sucedida.
  • issuance_error: houve um erro durante a emissão. Para obter detalhes, consulte a propriedade error.
state Cadeia de caracteres Retorna o valor de estado que você passou no conteúdo original.
error erro Quando o valor da propriedade code é issuance_error, essa propriedade contém informações sobre o erro.
error.code string O código de erro de retorno.
error.message string A mensagem de erro.

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

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

O exemplo a seguir demonstra uma carga de retorno de chamada após o usuário concluir com êxito o processo de emissão:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

Erros de retorno de chamada

O ponto de extremidade do retorno de chamada pode ser chamado com uma mensagem de erro. A tabela a seguir lista os códigos de erro:

Message Definição
fetch_contract_error Não é possível buscar o contrato de credencial verificável. Esse erro geralmente ocorre quando a API não pode buscar o manifesto especificado no objeto RequestIssuance do conteúdo da solicitação.
issuance_service_error O serviço de credenciais verificáveis não é capaz de validar os requisitos ou algo deu errado em credenciais verificáveis.
unspecified_error Esse erro não é comum, mas vale a pena investigar.

O exemplo a seguir demonstra o conteúdo de um retorno de chamada quando ocorreu um erro:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
} 

Próximas etapas

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