Emitir credenciais de ID Verificada do Microsoft Entra a partir de um aplicativo

  • Artigo

Neste tutorial, você executa um aplicativo de exemplo do computador local que se conecta ao locatário do Microsoft Entra. Usando o aplicativo, você emitirá e verificará um cartão de especialista em credenciais verificado.

Neste artigo, vai aprender a:

  • Crie o cartão de especialista de credenciais verificadas no Azure.
  • Reúna credenciais e detalhes do ambiente para configurar o aplicativo de exemplo.
  • Transfira o código da aplicação de exemplo para o computador local.
  • Atualize o aplicativo de exemplo com seu cartão de especialista de credenciais verificado e detalhes do ambiente.
  • Execute o aplicativo de exemplo e emita seu primeiro cartão de especialista em credenciais verificadas.
  • Verifique seu cartão de especialista em credenciais verificado.

O diagrama a seguir ilustra a arquitetura do Microsoft Entra Verified ID e o componente que você configura.

Diagram that illustrates the Microsoft Entra Verified ID architecture.

Pré-requisitos

Criar o cartão de especialista de credenciais verificadas no Azure

Gorjeta

As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.

Nesta etapa, você cria o cartão de especialista de credenciais verificadas usando a ID verificada do Microsoft Entra. Depois de criar a credencial, o locatário do Microsoft Entra pode emiti-la para os usuários que iniciam o processo.

  1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador Global.

  2. Selecione Credenciais verificáveis.

  3. Depois de configurar seu locatário, a credencial Criar deve aparecer. Como alternativa, você pode selecionar Credenciais no menu à esquerda e selecionar + Adicionar uma credencial.

  4. Em Criar credencial, selecione Credencial personalizada e clique em Avançar:

    1. Em Nome da credencial, insira VerifiedCredentialExpert. Esse nome é usado no portal para identificar suas credenciais verificáveis. Ele está incluído como parte do contrato de credenciais verificáveis.

    2. Copie o JSON a seguir e cole-o na caixa de texto Definição de vídeo

      {
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png",
        "description": "Verified Credential Expert Logo"
      },
      "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials."
    },
    "consent": {
      "title": "Do you want to get your Verified Credential?",
      "instructions": "Sign in with your account to get your card."
    },
    "claims": [
      {
        "claim": "vc.credentialSubject.firstName",
        "label": "First name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.lastName",
        "label": "Last name",
        "type": "String"
      }
    ]
}

    3. Copie o JSON a seguir e cole-o na caixa de texto Definição de regras

      {
  "attestations": {
    "idTokenHints": [
      {
        "mapping": [
          {
            "outputClaim": "firstName",
            "required": true,
            "inputClaim": "$.given_name",
            "indexed": false
          },
          {
            "outputClaim": "lastName",
            "required": true,
            "inputClaim": "$.family_name",
            "indexed": true
          }
        ],
        "required": false
      }
    ]
  },
  "validityInterval": 2592000,
  "vc": {
    "type": [
      "VerifiedCredentialExpert"
    ]
  }
}

    4. Selecione Criar.

A captura de tela a seguir demonstra como criar uma nova credencial:

Screenshot that shows how to create a new credential.

Reúna credenciais e detalhes do ambiente

Agora que você tem uma nova credencial, vai reunir algumas informações sobre seu ambiente e a credencial que você criou. Você usa essas informações ao configurar seu aplicativo de exemplo.

  1. Em Credenciais verificáveis, selecione Emitir credencial.

    Screenshot that shows how to select the newly created verified credential.

  2. Copie a autoridade, que é o Identificador Descentralizado, e registre-a para mais tarde.

  3. Copie o URL do manifesto. É a URL que o Autenticador avalia antes de exibir ao usuário os requisitos de emissão de credenciais verificáveis. Grave-o para uso posterior.

  4. Copie o ID do locatário e registre-o para mais tarde. O ID do Locatário é o guid no URL do manifesto destacado em vermelho acima.

Faça o download do código de exemplo

O aplicativo de exemplo está disponível no .NET e o código é mantido em um repositório GitHub. Baixe o código de exemplo do GitHub ou clone o repositório para sua máquina local:

git clone https://github.com/Azure-Samples/active-directory-verifiable-credentials-dotnet.git

Configurar o aplicativo de credenciais verificáveis

Crie um segredo de cliente para o aplicativo registrado que você criou. O aplicativo de exemplo usa o segredo do cliente para provar sua identidade quando solicita tokens.

  1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador Global.

  2. Selecione Microsoft Entra ID.

  3. Aceda à página de registos da aplicação Aplicações>.

  4. Selecione o aplicativo verifiable-credentials-app que você criou anteriormente.

  5. Selecione o nome para entrar nos detalhes de registro.

  6. Copie o ID do aplicativo (cliente) e armazene-o para mais tarde.

    Screenshot that shows how to copy the app registration ID.

  7. No menu principal, em Gerenciar, selecione Certificados & segredos.

  8. Selecione Novo segredo do cliente e faça o seguinte:

    1. Em Descrição, insira uma descrição para o segredo do cliente (por exemplo, vc-sample-secret).

    2. Em Expira, selecione uma duração para a qual o segredo é válido (por exemplo, seis meses). Em seguida, selecione Adicionar.

    3. Registre o valor do segredo. Você usará esse valor para configuração em uma etapa posterior. O valor do segredo não será exibido novamente e não poderá ser recuperado por nenhum outro meio. Grave-o assim que estiver visível.

Neste ponto, você deve ter todas as informações necessárias para configurar seu aplicativo de exemplo.

Atualizar o aplicativo de exemplo

Agora você fará modificações no código do emissor do aplicativo de exemplo para atualizá-lo com sua URL de credencial verificável. Esta etapa permite que você emita credenciais verificáveis usando seu próprio locatário.

  1. Na pasta active-directory-verifiable-credentials-dotnet-main, abra o Visual Studio Code e selecione o projeto dentro da pasta 1-asp-net-core-api-idtokenhint.

  2. Na pasta raiz do projeto, abra o arquivo appsettings.json . Este arquivo contém informações sobre seu ambiente de ID Verificada do Microsoft Entra. Atualize as seguintes propriedades com as informações que você registrou nas etapas anteriores:

    1. ID do inquilino: o seu ID de inquilino
    2. ID do cliente: o seu ID de cliente
    3. Segredo do cliente: o segredo do seu cliente
    4. DidAuthority: Seu identificador descentralizado
    5. Manifesto de credencial: URL do manifesto

    CredentialType só é necessário para apresentação, portanto, se tudo o que você deseja fazer é emissão, ele estritamente não é necessário.

  3. Salve o arquivo appsettings.json .

O JSON a seguir demonstra um arquivo appsettings.json completo:

{
  "VerifiedID": {
    "Endpoint": "https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/",
    "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default",
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "12345678-0000-0000-0000-000000000000",
    "ClientId": "33333333-0000-0000-0000-000000000000",
    "ClientSecret": "123456789012345678901234567890",
    "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]",
    "DidAuthority": "did:web:...your-decentralized-identifier...",
    "CredentialType": "VerifiedCredentialExpert",
    "CredentialManifest":  "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert"
  }
}

Emita seu primeiro cartão de especialista em credenciais verificadas

Agora você está pronto para emitir seu primeiro cartão de especialista de credenciais verificadas executando o aplicativo de exemplo.

  1. No Visual Studio Code, execute o projeto Verifiable_credentials_DotNet . Ou, na linha de comando do sistema operacional, execute:

    cd active-directory-verifiable-credentials-dotnet\1-asp-net-core-api-idtokenhint
dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\bin\Debug\net6.
dotnet run

  2. Em outra janela de prompt de comando, execute o seguinte comando. Este comando executa ngrok para configurar um URL no 5000 e torná-lo disponível publicamente na Internet.

    ngrok http 5000

    Nota

    Em alguns computadores, talvez seja necessário executar o comando neste formato: ./ngrok http 5000.

  3. Abra o URL HTTPS gerado pelo ngrok.

    Screenshot that shows how to get the ngrok public URL.

  4. Em um navegador da Web, selecione Obter credencial.

    Screenshot that shows how to choose to get the credential from the sample app.

  5. Usando seu dispositivo móvel, digitalize o código QR com o aplicativo Authenticator. Você também pode digitalizar o código QR diretamente da sua câmera, o que abrirá o aplicativo Authenticator para você.

    Screenshot that shows how to scan the QR code.

  6. Neste momento, você verá uma mensagem avisando que esse aplicativo ou site pode ser arriscado. Selecione Avançadas.

    Screenshot that shows how to respond to the warning message.

  7. No aviso do site de risco, selecione Continuar mesmo assim (inseguro). Você está vendo esse aviso porque seu domínio não está vinculado ao seu identificador descentralizado (DID). Para verificar seu domínio, siga Vincular seu domínio ao seu identificador descentralizado (DID). Para este tutorial, você pode ignorar o registro de domínio e selecionar Continuar mesmo assim (não seguro).

    Screenshot that shows how to proceed with the risky warning.

  8. Ser-lhe-á pedido que introduza um código PIN que é apresentado no ecrã onde digitalizou o código QR. O PIN adiciona uma camada extra de proteção à emissão. O código PIN é gerado aleatoriamente sempre que um código QR de emissão é exibido.

    Screenshot that shows how to type the pin code.

  9. Depois de inserir o número PIN, a tela Adicionar uma credencial é exibida. Na parte superior da tela, você verá uma mensagem Não verificado (em vermelho). Este aviso está relacionado com o aviso de validação de domínio mencionado anteriormente.

  10. Selecione Adicionar para aceitar sua nova credencial verificável.

    Screenshot that shows how to add your new credential.

Parabéns! Agora você tem uma credencial verificada de especialista em credenciais, verificável.

Screenshot that shows a newly added verifiable credential.

Volte para o aplicativo de exemplo. Ele mostra que uma credencial foi emitida com êxito.

Screenshot that shows a successfully issued verifiable credential.

Nomes de credenciais verificáveis

Sua credencial verificável contém Megan Bowen para os valores de nome e sobrenome na credencial. Esses valores foram codificados no aplicativo de exemplo e adicionados à credencial verificável no momento da emissão na carga útil.

Em cenários reais, seu aplicativo extrai os detalhes do usuário de um provedor de identidade. O trecho de código a seguir mostra onde o nome está definido no aplicativo de exemplo.

//file: IssuerController.cs
[HttpGet("/api/issuer/issuance-request")]
public async Task<ActionResult> issuanceRequest()
  {
    ...
    // Here you could change the payload manifest and change the first name and last name.
    payload["claims"]["given_name"] = "Megan";
    payload["claims"]["family_name"] = "Bowen";
    ...
}

Próximos passos

Na próxima etapa, saiba como um aplicativo de terceiros, também conhecido como aplicativo de terceira parte confiável, pode verificar suas credenciais com seu próprio serviço de API de credenciais verificáveis de locatário do Microsoft Entra.