Compartilhar via

Biblioteca de clientes do Certificado Key Vault do Azure para .NET – versão 4.5.1

  • Artigo

O Azure Key Vault é um serviço de nuvem que fornece armazenamento seguro e gerenciamento automatizado de certificados usados em um aplicativo de nuvem. Vários certificados e várias versões do mesmo certificado podem ser mantidos no Key Vault do Azure. Cada certificado no cofre tem uma política associada a ele que controla a emissão e o tempo de vida do certificado, juntamente com as ações a serem executadas como certificados próximos à expiração.

A biblioteca de clientes de certificados Key Vault do Azure permite gerenciar programaticamente certificados, oferecendo métodos para criar, atualizar, listar e excluir certificados, políticas, emissores e contatos. A biblioteca também dá suporte ao gerenciamento de operações de certificado pendentes e ao gerenciamento de certificados excluídos.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto | Amostras | Guia de migração

Introdução

Instalar o pacote

Instale a biblioteca de clientes de certificados do Azure Key Vault para .NET com o NuGet:

dotnet add package Azure.Security.KeyVault.Certificates

Pré-requisitos

  • Uma assinatura do Azure.
  • Um Key Vault existente do Azure. Se precisar criar um Key Vault do Azure, você poderá usar o Portal do Azure ou a CLI do Azure.
  • Autorização para um Key Vault existente do Azure usando o RBAC (recomendado) ou o controle de acesso.

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-key-vault-name> por seus próprios nomes exclusivos:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Autenticar o cliente

Para interagir com o serviço de Key Vault do Azure, você precisará criar uma instância da classe CertificateClient. Você precisa de uma URL do cofre, que você pode ver como "Nome DNS" no portal e credenciais para instanciar um objeto cliente.

Os exemplos mostrados abaixo usam um DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, é recomendável usar uma identidade gerenciada para autenticação em ambientes de produção. Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credenciais correspondentes na documentação da Identidade do Azure .

Para usar o DefaultAzureCredential provedor mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, primeiro você deve instalar o pacote Azure.Identity:

dotnet add package Azure.Identity

Criar CertificateClient

Instancie um DefaultAzureCredential para passar para o cliente. A mesma instância de uma credencial de token poderá ser usada com vários clientes se eles estiverem se autenticando com a mesma identidade.

// Create a new certificate client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

Principais conceitos

KeyVaultCertificate

Um KeyVaultCertificate é o recurso fundamental no Azure Key Vault. Você usará certificados para criptografar e verificar dados criptografados ou assinados.

CertificateClient

Com um CertificateClient , você pode obter certificados do cofre, criar novos certificados e novas versões de certificados existentes, atualizar metadados de certificado e excluir certificados. Você também pode gerenciar emissores de certificado, contatos e políticas de gerenciamento de certificados. Isso é ilustrado nos exemplos abaixo.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | cliente Acessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

O pacote Azure.Security.KeyVault.Certificates dá suporte a APIs síncronas e assíncronas.

A seção a seguir fornece vários snippets de código usando o clientcriado acima, abrangendo algumas das tarefas mais comuns relacionadas ao serviço de certificado do Azure Key Vault:

Exemplos de sincronização

Exemplos assíncronos

Criar um certificado

StartCreateCertificatecria um certificado a ser armazenado no Key Vault do Azure. Se um certificado com o mesmo nome já existir, uma nova versão do certificado será criada. Ao criar o certificado, o usuário pode especificar a política que controla o tempo de vida do certificado. Se nenhuma política for especificada, a política padrão será usada. A StartCreateCertificate operação retorna um CertificateOperation. O exemplo a seguir cria um certificado autoassinado com a política padrão.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

OBSERVAÇÃO: dependendo do emissor do certificado e dos métodos de validação, a criação e a assinatura do certificado podem levar um tempo indeterminado. Os usuários só devem aguardar as operações de certificado quando a operação puder ser razoavelmente concluída no escopo do aplicativo, como com certificados autoassinados ou emissores com tempos de resposta conhecidos.

Recuperar um certificado

GetCertificaterecupera a versão mais recente de um certificado armazenado no Key Vault do Azure junto com seu CertificatePolicy.

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion recupera uma versão específica de um certificado no cofre.

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

Atualizar um certificado existente

UpdateCertificateatualiza um certificado armazenado no Key Vault do Azure.

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Listar certificados

GetCertificates enumera os certificados no cofre, retornando as propriedades selecionadas do certificado. Campos confidenciais do certificado não serão retornados. Essa operação requer a permissão de certificados/lista.

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

Excluir um certificado

DeleteCertificateexclui todas as versões de um certificado armazenado no Key Vault do Azure. Quando a exclusão reversível não está habilitada para a Key Vault do Azure, essa operação exclui permanentemente o certificado. Se a exclusão temporária estiver habilitada, o certificado será marcado para exclusão e poderá, opcionalmente, ser limpo ou recuperado até a data de limpeza agendada.

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

Criar um certificado de forma assíncrona

As APIs assíncronas são idênticas às suas contrapartes síncronas, mas retornam com o sufixo "Assíncrono" típico para métodos assíncronos e retornam um Task.

Este exemplo cria um certificado no Key Vault do Azure com os argumentos opcionais especificados.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

Listar certificados de forma assíncrona

A listagem do certificado não depende da espera do GetPropertiesOfCertificatesAsync método , mas retorna um AsyncPageable<CertificateProperties> que você pode usar com a instrução await foreach :

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

Excluir um certificado de forma assíncrona

Ao excluir um certificado de forma assíncrona antes de purgá-lo, você pode aguardar o WaitForCompletionAsync método na operação. Por padrão, isso executa um loop indefinidamente, mas você pode cancelá-lo passando um CancellationToken.

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

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

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.Name);

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Quando você interage com a biblioteca de clientes de certificados do Azure Key Vault usando o SDK do .NET, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações da API REST.

Por exemplo, se você tentar recuperar uma Chave que não existe no Key Vault do Azure, um 404 erro será retornado, indicando Not Found.

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Você observará que informações adicionais são registradas, como a ID de Solicitação do Cliente da operação.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"CertificateNotFound","message":"Certificate not found: MyCertificate"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

Próximas etapas

Vários exemplos de biblioteca de clientes de certificados do Azure Key Vault estão disponíveis neste repositório GitHub. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com o Azure Key Vault:

  • Sample1_HelloWorld.md – para trabalhar com certificados de Key Vault do Azure, incluindo:

    • Criar um certificado
    • Obter um certificado existente
    • Atualizar um certificado existente
    • Excluir um certificado

  • Sample2_GetCertificates.md – código de exemplo para trabalhar com certificados de Key Vault do Azure, incluindo:

    • Criar certificados
    • Listar todos os certificados no Key Vault
    • Listar versões de um certificado especificado
    • Excluir certificados do Key Vault
    • Listar certificados excluídos no Key Vault

Documentação Adicional

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essas bibliotecas.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões