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

Artigo
12/07/2023

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.

Diagrama que ilustra a arquitetura de ID Verificada do Microsoft Entra.

Pré-requisitos

Configure um locatário para a ID Verificada do Microsoft Entra.
Para clonar o repositório que hospeda o aplicativo de exemplo, instale o GIT.
Visual Studio Code, Visual Studio ou editor de código semelhante.
.NET 7.0.
Faça o download do ngrok e inscreva-se para obter uma conta gratuita. Se não puder utilizar ngrok na sua organização, leia estas Perguntas frequentes.
Um dispositivo móvel com a versão mais recente do Microsoft Authenticator.

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.

Entre no centro de administração do Microsoft Entra como Administrador Global.
Selecione Credenciais verificáveis.
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.

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

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.

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.z13.web.core.windows.net/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"
      }
    ]
}

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"
    ]
  }
}

Selecione Criar.

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

Captura de tela que mostra como criar uma nova credencial.

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.

Em Credenciais verificáveis, selecione Emitir credencial.
Copie a autoridade, que é o Identificador Descentralizado, e registre-a para mais tarde.
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.
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.

Entre no centro de administração do Microsoft Entra como Administrador Global.
Selecione Microsoft Entra ID.
Aceda à página de registos da aplicação Aplicações>.
Selecione o aplicativo verifiable-credentials-app que você criou anteriormente.
Selecione o nome para entrar nos detalhes de registro.
Copie o ID do aplicativo (cliente) e armazene-o para mais tarde.
No menu principal, em Gerenciar, selecione Certificados & segredos.
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.

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.
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.
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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "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/00001111-aaaa-2222-bbbb-3333cccc4444/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.

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

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.
Abra o URL HTTPS gerado pelo ngrok.
Em um navegador da Web, selecione Obter credencial.
Usando seu dispositivo móvel, digitalize o código QR com o aplicativo Authenticator. Para mais informações sobre como digitalizar o código QR, consulte a secção FAQ.
Neste momento, você verá uma mensagem avisando que esse aplicativo ou site pode ser arriscado. Selecione Avançadas.
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).
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.
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.
Selecione Adicionar para aceitar sua nova credencial verificável.

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

Captura de tela que mostra uma credencial verificável recém-adicionada.

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

Captura de tela que mostra uma credencial verificável emitida com êxito.

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.

Partilhar via