Chamar a API REST do Serviço de Solicitação

A ID Verificada do Microsoft Entra inclui a API REST do Serviço de Solicitação. Essa API permite que você emita e verifique credenciais. Este artigo mostra como começar a usar a API REST do Serviço de Solicitação.

Token de acesso à API

Seu aplicativo precisa incluir um token de acesso válido com as permissões necessárias para que possa acessar a API REST do Serviço de Solicitação. Os tokens de acesso emitidos pela plataforma de identidade da Microsoft contêm informações (escopos) que a API REST do Serviço de Solicitação usa para validar o chamador. Um token de acesso garante que o chamador tenha as permissões adequadas para executar a operação que está solicitando.

Para obter um token de acesso, seu aplicativo deve ser registrado na plataforma de identidade da Microsoft e ser autorizado por um administrador para acessar a API REST do Serviço de Solicitação. Se você não registrou o aplicativo verificable-credentials-app, veja como registrar o aplicativo e, em seguida, gerar um segredo do aplicativo.

Obter um token de acesso

Use o fluxo de concessão de credenciais do cliente OAuth 2.0 para adquirir o token de acesso usando a plataforma de identidade da Microsoft. Use uma biblioteca confiável para essa finalidade. Neste tutorial, usamos a Biblioteca de Autenticação da Microsoft (MSAL). O MSAL simplifica a adição de autenticação e autorização a um aplicativo que pode chamar uma API da Web segura.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

No código anterior, forneça os seguintes parâmetros:

Parâmetro Condição Description
Autoridade Necessário O locatário do diretório contra o qual o aplicativo planeja operar. Por exemplo: https://login.microsoftonline.com/{your-tenant}. (Substitua your-tenant pelo ID ou nome do locatário.)
ID de Cliente Necessário A ID do aplicativo atribuída ao seu aplicativo. Você pode encontrar essas informações no portal do Azure, onde registrou seu aplicativo.
Segredo do cliente Necessário O segredo do cliente que você gerou para seu aplicativo.
Âmbitos Necessário Deve ser definido como 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Essa configuração produz um token de acesso com uma declaração de funções de VerifiableCredential.Create.All.

Para obter mais informações sobre como obter um token de acesso usando a identidade de um aplicativo de console, consulte um dos seguintes artigos:

Você também pode acessar uma solicitação de token com um certificado em vez de um segredo do cliente.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1   //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=12345678-0000-0000-00000000000000000
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Chamar a API

Para emitir ou verificar uma credencial verificável:

  1. Construa uma solicitação HTTP POST para a API REST do Serviço de Solicitação. O ID do locatário não é mais necessário na URL porque está presente como uma declaração no token de acesso.

    Problema

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

    Verificar

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Anexe o token de acesso como um token de portador ao cabeçalho de autorização em uma solicitação HTTP.

    Authorization: Bearer <token>
    
  3. Defina o Content-Type cabeçalho como Application/json.

  4. Prepare e anexe a carga útil da solicitação de emissão ou apresentação ao corpo da solicitação.

  5. Envie a solicitação para a API REST do Serviço de Solicitação.

A API do Serviço de Solicitação retorna um Código 201 Created de Status HTTP em uma chamada bem-sucedida. Se a chamada de API retornar um erro, verifique a documentação de referência de erro.

Exemplo de solicitação de emissão

O exemplo a seguir demonstra uma solicitação de emissão de credenciais verificável. Para obter informações sobre a carga útil, consulte Especificação de emissão da 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>

{...JSON payload...}

Solicitação de emissão utilizando o fluxo de idTokenHint atestado:

{
    "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",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

Para obter o código completo, consulte um dos seguintes exemplos de código:

Exemplo de pedido de apresentação

O exemplo a seguir demonstra uma solicitação de apresentação de credenciais verificáveis. Para obter informações sobre a carga útil, consulte Especificação de apresentação da API REST do serviço de solicitação.

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

{...JSON payload...}

Pedido de apresentação de uma credencial com um determinado tipo e emissor:

{
  "includeQRCode": true,
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "includeReceipt": true,
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": true,
          "validateLinkedDomain": true
        }
      }
    }
  ]
}

Para obter o código completo, consulte um dos seguintes exemplos de código:

Eventos de retorno de chamada

A carga útil da solicitação contém o ponto de extremidade de retorno de chamada de emissão e apresentação . O ponto de extremidade faz parte da sua aplicação Web e deve estar disponível publicamente através do protocolo HTTPS. A API do Serviço de Solicitação chama seu ponto de extremidade para informar seu aplicativo sobre determinados eventos. Por exemplo, esses eventos podem ser quando um usuário escaneia o código QR, usa o link direto para o aplicativo autenticador ou conclui o processo de apresentação.

O diagrama a seguir descreve a chamada que seu aplicativo faz para a API REST do Serviço de Solicitação e os retornos de chamada para seu aplicativo.

Diagram that shows the call to the API and the callback events.

Configure seu ponto de extremidade para ouvir solicitações HTTP POST recebidas. O trecho de código a seguir demonstra como lidar com a solicitação HTTP de retorno de chamada de emissão e como atualizar a interface do usuário de acordo:

Não aplicável. Escolha uma das outras linguagens de programação.

Próximos passos

Saiba mais sobre estas especificações: