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

Artigo
03/04/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 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>

{
    "includeQRCode": true,
    "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.

{
  "includeQRCode": false,
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "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	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` (padrão) ou `false`. 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 nome do host resolvido 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 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.

Share via