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

Artigo
01/31/2025

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 uma chamada quando o usuário examinar 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`	Cadeia de caracteres	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`	Cadeia de caracteres	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`	Cadeia de caracteres	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`	Cadeia de caracteres	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 substitui o validityInterval na definição de regras de credenciais para essa solicitação de emissão. Use essa configuração para controlar explicitamente quando uma credencial expirar, como fim de dia, fim do mês ou fim do ano, independentemente do tempo de emissão. A data é expressa no formato UTC. Se você especificar o fim do ano, com o tempo definido como `23:59:59` (ou seja, de 1 segundo a 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	Tipo	Descrição
`clientName`	Cadeia de caracteres	Um nome de exibição do emissor da credencial verificável.
`logoUrl`	Cadeia de caracteres	Opcional. A URL do logotipo do emissor.
`termsOfServiceUrl`	Cadeia de caracteres	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	Tipo	Descrição
`url`	Cadeia de caracteres	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 gerará um erro ilegível de URL de retorno de chamada. Formatos aceitos IPv4, IPv6 ou nome de host resolvível de DNS. Para fortalecer sua rede, consulte Perguntas frequentes.
`state`	Cadeia de caracteres	Correlaciona o evento de retorno de chamada com o estado passado no conteúdo original.
`headers`	Cadeia de caracteres	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 lança um 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	Tipo	Descrição
`value`	Cadeia de caracteres	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`	Cadeia de caracteres	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`	Cadeia de caracteres	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	Tipo	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`	Cadeia de caracteres	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 expira.
`qrCode`	Cadeia de caracteres	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. O aplicativo deve lidar com a resposta adequadamente.

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	Tipo	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`	Cadeia de caracteres	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`	Cadeia de caracteres	O código de erro de retorno.
`error.message`	Cadeia de caracteres	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.

Compartilhar via