Guia de início rápido: biblioteca de cliente de certificado do Azure Key Vault para .NET

Introdução à biblioteca de cliente de certificado do Azure Key Vault para .NET. O Azure Key Vault é um serviço em nuvem que fornece um armazenamento seguro para certificados. Pode armazenar chaves, palavras-passe, certificados e outros segredos em segurança. Os cofres de chaves do Azure podem ser criados e geridos através do portal do Azure. Neste início rápido, você aprenderá a criar, recuperar e excluir certificados de um cofre de chaves do Azure usando a biblioteca de cliente .NET.

Recursos da biblioteca do cliente 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 certificados, consulte:

Pré-requisitos

Uma subscrição do Azure - crie uma gratuitamente
SDK do .NET 6 ou posterior
CLI do Azure
Um Cofre de Chaves - pode criar um utilizando o portal do Azure, a CLI do Azure ou o Azure PowerShell.

Esta introdução está usando dotnet e o Azure CLI.

Configuração

Este início rápido usa a biblioteca de Identidade do Azure com a CLI do Azure para autenticar utilizadores nos serviços da Azure. Os desenvolvedores também podem usar o Visual Studio ou o Visual Studio Code para autenticar as suas chamadas; para mais informações, veja Autenticar o cliente com a biblioteca Azure Identity para clientes.

Execute o comando login.
```
az login
```
Se a CLI puder abrir seu navegador padrão, ela fará isso e carregará uma página de entrada do Azure.

Caso contrário, abra uma página do navegador e https://aka.ms/devicelogin insira o código de autorização exibido no seu terminal.
Inicie sessão com as credenciais da sua conta no browser.

Conceder acesso ao seu cofre de chaves

Para obter permissões para o seu cofre de chaves por meio do controlo de acesso baseado em funções (RBAC), atribua uma função ao "Nome Principal do Utilizador" (UPN) usando o comando az role assignment create da CLI do Azure.

az role assignment create --role "Key Vault Certificates Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Substitua <upn>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos seus valores reais. Seu UPN normalmente estará no formato de um endereço de e-mail (por exemplo, username@domain.com).

Criar novo aplicativo de console .NET

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
```
Mude para o recém-criado diretório key-vault-console-app e execute o seguinte comando para compilar o projeto.
```
dotnet build
```
A saída da compilação não deve conter avisos ou erros.
```
Build succeeded.
 0 Warning(s)
 0 Error(s)
```

Instalar os pacotes

A partir do shell de comando, instale a biblioteca de cliente de certificado do Azure Key Vault para .NET:

dotnet add package Azure.Security.KeyVault.Certificates

Para este início rápido, você também precisará instalar a biblioteca de cliente do Azure Identity:

dotnet add package Azure.Identity

Definir variáveis de ambiente

A aplicação obtém o nome do cofre de chaves a partir de 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

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

Exemplos de código

Adicionar diretivas

Adicione as seguintes diretivas no início de Program.cs:

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

Autenticar e criar um cliente

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar a classe DefaultAzureCredential fornecida pela biblioteca cliente Azure Identity é a abordagem recomendada para implementar conexões sem senha nos serviços Azure no seu código. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Neste início rápido, DefaultAzureCredential autentica-se no cofre de chaves usando as credenciais do usuário de desenvolvimento local conectado à CLI do Azure. Quando a aplicação é implantada no Azure, o mesmo código pode descobrir e usar automaticamente uma identidade gerida atribuída a um Serviço de Aplicações, Máquina Virtual ou outros serviços. Para obter mais informações, consulte Visão geral da Identidade Gerida.


Neste exemplo, o nome do seu cofre de chaves é expandido para o URI do cofre de chaves, no formato https://<your-key-vault-name>.vault.azure.net. Para obter mais informações sobre como autenticar no cofre de chaves, consulte o 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());

Guardar um certificado
Neste exemplo, para simplificar, você pode usar o certificado autoassinado com a política de emissão padrão. Para esta tarefa, use o método StartCreateCertificateAsync . Os parâmetros do método aceitam um nome de certificado e a política de certificado.
var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();


Nota
Se o nome do certificado existir, o código acima criará uma nova 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 eliminar e remover definitivamente 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 para interagir com o Cofre da Chave concluindo as seguintes etapas:

Substitua o código em Program.cs pelo seguinte código:
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 seguinte comando para criar o projeto
dotnet build

É apresentada uma variação da seguinte saída:
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óximos passos
Neste início rápido, você criou um cofre de chaves, armazenou um certificado e recuperou esse certificado.
Para saber mais sobre o Key Vault e como integrá-lo aos seus aplicativos, consulte os seguintes artigos:

Leia uma visão geral do Azure Key Vault
Leia uma visão geral dos certificados
Veja um Tutorial do Aplicativo do Cofre da Chave de Acesso do Serviço de Aplicativo
Veja um tutorial do Cofre da Chave de Acesso da Máquina Virtual
Consulte o guia de desenvolvimento do Azure Key Vault
Revise a visão geral de segurança do Cofre de Chaves

Feedback

Esta página foi útil?

Last updated on 2025-04-21

Partilhar via

Guia de início rápido: biblioteca de cliente de certificado do Azure Key Vault para .NET

Pré-requisitos

Configuração

Iniciar sessão no Azure

Conceder acesso ao seu cofre de chaves

Criar novo aplicativo de console .NET

Instalar os pacotes

Definir variáveis de ambiente

Modelo de objeto

Exemplos de código

Adicionar diretivas

Autenticar e criar um cliente

Guardar um certificado

Recuperar um certificado

Excluir um certificado

Código de exemplo

Testar e verificar

Próximos passos

Feedback

Recursos adicionais