Início rápido: Biblioteca de clientes de certificados do Azure Key Vault para .NET (SDK v4)

Introdução à biblioteca de clientes de certificados do Azure Key Vault para .NET. O Azure Key Vault é um serviço de nuvem que funciona como um repositório seguro de certificados. Você pode armazenar chaves, senhas, certificados e outros segredos com segurança. Os cofres de chaves do Azure podem ser criados e gerenciados por meio do portal do Azure. Neste guia de início rápido, você aprenderá a criar, recuperar e excluir certificados de um cofre de chaves do Azure usando a biblioteca de clientes do .NET

Recursos da biblioteca de clientes do Key Vault:

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet)

Para obter mais informações sobre o Key Vault e os certificados, confira:

Pré-requisitos

Este guia de início rápido usa o dotnet e a CLI do Azure

Instalação

Este guia de início rápido usa a biblioteca de identidades do Azure com a CLI do Azure para autenticar o usuário nos serviços do Azure. Os desenvolvedores também podem usar o Visual Studio ou o Visual Studio Code para autenticar as chamadas. Para saber mais, confira Autenticar o cliente na biblioteca de clientes do Azure Idendity.

Entrar no Azure

  1. Execute o comando login.

    az login
    

    Se a CLI puder abrir o navegador padrão, ela o fará e carregará uma página de entrada do Azure.

    Caso contrário, abra uma página de navegador em https://aka.ms/devicelogin e insira o código de autorização exibido no terminal.

  2. Entre com suas credenciais de conta no navegador.

Permitir acesso ao cofre de chaves

Crie uma política de acesso para o cofre de chaves que conceda permissões de certificado à sua conta de usuário

az keyvault set-policy --name <your-key-vault-name> --upn user@domain.com --certificate-permissions delete get list create purge

Criar um novo aplicativo de console do .NET

  1. Em um shell de comando, execute o seguinte comando para criar um projeto chamado key-vault-console-app:

    dotnet new console --name key-vault-console-app
    
  2. Altere para o diretório key-vault-console-app recém-criado e execute o seguinte comando para compilar o projeto:

    dotnet build
    

    A saída de compilação não deve conter nenhum aviso ou erro.

    Build succeeded.
     0 Warning(s)
     0 Error(s)
    

Instalar os pacotes

No shell de comando, instale a biblioteca de clientes de certificados do Azure Key Vault para .NET:

dotnet add package Azure.Security.KeyVault.Certificates

Para este guia de início rápido, você também precisará instalar a biblioteca de clientes do SDK do Azure para a identidade do Azure:

dotnet add package Azure.Identity

Definir variáveis de ambiente

Este aplicativo usa o nome do cofre de chaves como uma variável de ambiente chamada KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS ou Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Modelo de objeto

Com a biblioteca de clientes de certificados do Azure Key Vault para .NET, você pode gerenciar certificados. A seção Exemplos de código mostra como criar um cliente, definir, recuperar e excluir um certificado.

Exemplos de código

Adicionar diretivas

Adicione as seguintes diretivas à parte superior de Program.cs:

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

Autenticar e criar um cliente

Neste guia de início rápido, o usuário conectado é usado para se autenticar no cofre de chaves, que é o método preferencial para o desenvolvimento local. Para os aplicativos implantados no Azure, a identidade gerenciada deve ser atribuída ao Serviço de Aplicativo ou à Máquina Virtual. Para obter mais informações, confira Visão geral da identidade gerenciada.

No exemplo abaixo, o nome do cofre de chaves é expandido para o URI do cofre de chaves, no formato "https://<your-key-vault-name>.vault.azure.net". Este exemplo usa a classe 'DefaultAzureCredential()' da Biblioteca de Identidades do Azure, que permite usar o mesmo código em diferentes ambientes com outras opções para fornecer a identidade. Para obter mais informações sobre como se autenticar no cofre de chaves, confira Guia do Desenvolvedor.

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

Salvar um certificado

Neste exemplo, para simplificar, você pode usar o certificado autoassinado com a política de emissão padrão. Para essa tarefa, use o método StartCreateCertificateAsync. Os parâmetros do método aceitam um nome de certificado e a política de certificação.

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

Observação

Se o nome do certificado existir, o código acima criará uma versão desse certificado.

Recuperar um certificado

Agora você pode recuperar o certificado criado anteriormente com o método GetCertificateAsync.

var certificate = await client.GetCertificateAsync("myCertificate");

Excluir um certificado

Por fim, vamos excluir e limpar o certificado do cofre de chaves com os métodos StartDeleteCertificateAsync e PurgeDeletedCertificateAsync.

var operation = await client.StartDeleteCertificateAsync("myCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
await operation.WaitForCompletionAsync();

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

Código de exemplo

Modifique o aplicativo de console .NET Core para interagir com o Key Vault concluindo as seguintes etapas:

  • Substitua o código em Program.cs pelo código a seguir:

    using System;
    using System.Threading.Tasks;
    using Azure.Identity;
    using Azure.Security.KeyVault.Certificates;
    
    namespace key_vault_console_app
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                const string certificateName = "myCertificate";
                var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
                var kvUri = $"https://{keyVaultName}.vault.azure.net";
    
                var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());
    
                Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
                CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
                await operation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
                var certificate = await client.GetCertificateAsync(certificateName);
                Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");
    
                Console.Write($"Deleting your certificate from {keyVaultName} ...");
                DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
                // You only need to wait for completion if you want to purge or recover the certificate.
                await deleteOperation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.Write($"Purging your certificate from {keyVaultName} ...");
                await client.PurgeDeletedCertificateAsync(certificateName);
                Console.WriteLine(" done.");
            }
        }
    }
    

Testar e verificar

Execute o comando a seguir para compilar o projeto

dotnet build

Uma variação do seguinte resultado é exibida:

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

Próximas etapas

Neste guia de início rápido, você criou um cofre de chaves e armazenou e recuperou um certificado.

Para saber mais sobre o Key Vault e como integrá-lo aos seus aplicativos, confira os seguintes artigos: