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

Artigo
12/07/2023

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

Pedido HTTP

A solicitação de emissã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 emissão da API REST do Serviço de Solicitação requer 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 do Serviço de Solicitação.

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

A seguinte solicitação HTTP demonstra uma solicitação para a API REST do 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 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 de solicitação de emissão

A carga útil 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 de usuário, como nome e sobrenome. O resultado desta 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/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

O payload contém as seguintes propriedades:

Parâmetro	Tipo	Descrição
`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 o digitalizar. A leitura 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`. Ao definir o valor como `false`, use a propriedade return `url` para renderizar um link direto.
`callback`	Retorno de chamada	Obrigatório. Permite que o desenvolvedor obtenha informações assíncronas sobre o fluxo durante o processo de emissão de credenciais verificáveis. Por exemplo, o desenvolvedor pode querer uma chamada quando o usuário escaneou o código QR ou se a solicitação de emissão for bem-sucedida ou falhar.
`authority`	string	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`	PedidoRegisto	Fornece informações sobre o emissor que podem ser exibidas no aplicativo autenticador.
`type`	string	O tipo de credencial verificável. Deve corresponder ao tipo definido no manifesto de credenciais verificável. Por exemplo: `VerifiedCredentialExpert`. Para obter mais informações, consulte Criar o cartão de especialista em credenciais verificadas no Azure.
`manifest`	string	A URL do documento de manifesto de credenciais 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 afirmaçõ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 de 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. A expirationDate só pode ser usada 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á o validityInterval na definição de regras de credenciais para esta solicitação de emissão. Use essa configuração para controlar explicitamente quando uma credencial expira, como fim de dia, fim de mês ou fim de ano, independentemente de quando ela é emitida. Por favor, note que a data é expressa em formato UTC. Se você especificar o fim do ano, com o tempo definido como `23:59:59`, isso é de 1 segundo à meia-noite no horário UTC. Qualquer usuário em um fuso horário diferente obterá a data de expiração apresentada no fuso horário local no Microsoft Authenticator. Isso significa que, se você estiver no fuso horário CET, ele será apresentado como 1 de janeiro 1h. O contrato de credencial precisa ter o sinalizador allowOverrideValidityOnIssuance definido como true.

Atualmente, existem quatro tipos de atestado de sinistros que você pode enviar na carga útil. O Microsoft Entra Verified ID 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 identificação
Sugestão de token de ID
Credenciais verificáveis através de uma apresentação verificável
Alegações auto-atestadas

Você pode encontrar informações detalhadas sobre os tipos de entrada em Personalizando sua credencial verificável.

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

Nota

No momento, as RequestRegistration informações não são apresentadas durante a emissão no aplicativo Microsoft Authenticator. Esta informação pode, no entanto, ser utilizada na carga útil.

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á erro de URL de retorno de chamada ilegível. Formatos aceitos IPv4, IPv6 ou DNS resolvível nome de host
`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 pino

O pin tipo define um código PIN que pode ser exibido como parte da emissão. pin é opcional e, se utilizado, deve ser sempre enviado para fora da banda. Ao usar um código PIN HASH, você deve definir as saltpropriedades , alge iterations . pin Contém as seguintes propriedades:

Propriedade	Type	Description
`value`	string	Contém o valor PIN em texto sem formatação. Quando você estiver usando um PIN com hash, a propriedade value contém o hash salgado, codificado em base64.
`type`	string	O tipo do código PIN. Valor possível: `numeric` (padrão).
`length`	integer	O comprimento do código PIN. O comprimento padrão é 6, o mínimo é 4 e o máximo é 16.
`salt`	string	O sal do código PIN com hash. O sal é pré-fixado durante o cálculo de hash. Codificação: UTF-8.
`alg`	string	O algoritmo de hash para o PIN com hash. Algoritmo suportado: `sha256`.
`iterations`	integer	O número de iterações de hash. Valor possível: `1`.

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/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	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 emissão e seus retornos de chamada.
`url`	string	Um URL que inicia o aplicativo autenticador e inicia o processo de emissã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 escanear para iniciar o fluxo de emissã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 emissão.

Resposta de erro

Se houver um erro com a solicitação, uma resposta de erro será retornada e deve 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 deep link do aplicativo autenticador ou conclui o processo de emissã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 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 mais detalhes, consulte a `error` propriedade.
`state`	string	Retorna o valor de estado que você passou na carga original.
`error`	error	Quando o valor da `code` propriedade é `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 uma carga de 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 depois que o usuário conclui 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 de retorno de chamada pode ser chamado com uma mensagem de erro. A tabela a seguir lista os códigos de erro:

Mensagem	Definição
`fetch_contract_error`	Não é possível obter o contrato de credencial verificável. Esse erro geralmente acontece quando a API não pode buscar o manifesto especificado no objeto RequestIssuance de carga útil da solicitação.
`issuance_service_error`	O serviço de Credenciais Verificáveis não é capaz de validar requisitos ou algo deu errado em Credenciais Verificáveis.
`unspecified_error`	Este erro é incomum, mas vale a pena investigar.

O exemplo a seguir demonstra uma carga de 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óximos passos

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