Partilhar via

Azure Key Vault Certificate client library for .NET - version 4.5.1 (Biblioteca de cliente de certificados do Azure Key Vault para .NET – versão 4.5.1)

  • Artigo

O Azure Key Vault é um serviço cloud que fornece armazenamento seguro e gestão automatizada de certificados utilizados numa aplicação na cloud. Vários certificados e várias versões do mesmo certificado podem ser mantidos no Azure Key Vault. Cada certificado no cofre tem uma política associada que controla a emissão e a duração do certificado, juntamente com as ações a serem tomadas como certificados perto da expiração.

A biblioteca de cliente de certificados do Azure Key Vault permite a gestão programática de certificados, oferecendo métodos para criar, atualizar, listar e eliminar certificados, políticas, emissores e contactos. A biblioteca também suporta a gestão de operações de certificado pendentes e a gestão de certificados eliminados.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.Security.KeyVault.Certificates

Pré-requisitos

Se utilizar a CLI do Azure, substitua <your-resource-group-name> e <your-key-vault-name> pelos 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 Key Vault do Azure, terá de criar uma instância da classe CertificateClient. Precisa de um URL do cofre, que poderá ver como "Nome DNS" no portal e credenciais para instanciar um objeto de cliente.

Os exemplos mostrados abaixo utilizam um DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Além disso, recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção. Pode encontrar mais informações sobre as diferentes formas de autenticação e os tipos de credenciais correspondentes na documentação da Identidade do Azure .

Para utilizar o DefaultAzureCredential fornecedor mostrado abaixo ou outros fornecedores de credenciais fornecidos com o SDK do Azure, primeiro tem de instalar o pacote Azure.Identity:

dotnet add package Azure.Identity

Criar CertificateClient

Instanciar um DefaultAzureCredential para passar para o cliente. A mesma instância de uma credencial de token pode ser utilizada com vários clientes se estiverem a autenticar 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());

Conceitos-chave

KeyVaultCertificate

A KeyVaultCertificate é o recurso fundamental no Azure Key Vault. Irá utilizar certificados para encriptar e verificar dados encriptados ou assinados.

CertificateClient

Com um CertificateClient , pode obter certificados do cofre, criar novos certificados e novas versões de certificados existentes, atualizar metadados de certificado e eliminar certificados. Também pode gerir emissores de certificados, contactos e políticas de gestão de certificados. Isto é ilustrado nos exemplos abaixo.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Opções de | cliente Aceder à resposta | Operações de execução prolongada | Lidar com falhas | Diagnósticos | A gozar | Duração do cliente

Exemplos

O pacote Azure.Security.KeyVault.Certificates suporta APIs síncronas e assíncronas.

A secção seguinte fornece vários fragmentos de código com o clientcriado acima, abrangendo algumas das tarefas mais comuns relacionadas com o serviço de certificados 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 já existir um certificado com o mesmo nome, será criada uma nova versão do certificado. Ao criar o certificado, o utilizador pode especificar a política que controla a duração do certificado. Se não for especificada nenhuma política, será utilizada a política predefinida. A StartCreateCertificate operação devolve um CertificateOperation. O exemplo seguinte cria um certificado autoassinado com a política predefinida.

// 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;

NOTA: consoante o emissor do certificado e os métodos de validação, a criação e assinatura de certificados podem demorar um período indeterminado de tempo. Os utilizadores só devem aguardar pelas operações de certificado quando a operação puder ser razoavelmente concluída no âmbito da aplicação, como com certificados autoassinados ou emissores com tempos de resposta bem conhecidos.

Obter um certificado

GetCertificateobtém a versão mais recente de um certificado armazenado no Azure Key Vault juntamente com o respetivo CertificatePolicy.

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

GetCertificateVersion obtém 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, devolvendo as propriedades selecionadas do certificado. Os campos confidenciais do certificado não serão devolvidos. Esta operação requer a permissão de certificados/lista.

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

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

Eliminar um certificado

DeleteCertificateelimina todas as versões de um certificado armazenado no Key Vault do Azure. Quando a eliminação recuperável não está ativada para a Key Vault do Azure, esta operação elimina permanentemente o certificado. Se a eliminação recuperável estiver ativada, o certificado será marcado para eliminação e poderá ser opcionalmente removido ou recuperado até à data de remoção 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 congéneres síncronas, mas devolvem com o sufixo "Assíncrono" típico para métodos assíncronos e devolvem um Task.

Este exemplo cria um certificado no Azure Key Vault 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 de aguardar o GetPropertiesOfCertificatesAsync método, mas devolve uma AsyncPageable<CertificateProperties> que pode utilizar com a await foreach instrução :

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

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

Eliminar um certificado de forma assíncrona

Ao eliminar um certificado de forma assíncrona antes de o remover, pode aguardar o WaitForCompletionAsync método na operação. Por predefinição, este ciclo é ciclo indefinidamente, mas pode cancelá-lo ao transmitir 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);

Resolução de problemas

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

Geral

Quando interage com a biblioteca de cliente de certificados do Azure Key Vault com o SDK .NET, os erros devolvidos pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos de API REST.

Por exemplo, se tentar obter uma Chave que não existe no seu Key Vault do Azure, é devolvido um 404 erro que indica Not Found.

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

Irá reparar que são registadas informações adicionais, como o ID do Pedido de 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

Passos seguintes

Estão disponíveis vários exemplos de biblioteca de cliente de certificados do Azure Key Vault neste repositório do GitHub. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente encontrados ao trabalhar com o Azure Key Vault:

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

    • Criar um certificado
    • Obter um certificado existente
    • Atualizar um certificado existente
    • Eliminar um certificado

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

    • Criar certificados
    • Listar todos os certificados no Key Vault
    • Listar versões de um certificado especificado
    • Eliminar certificados do Key Vault
    • Listar certificados eliminados no Key Vault

Documentação Adicional

Contribuir

Veja o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para estas bibliotecas.

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões