Início Rápido: Biblioteca de clientes do certificado do Azure Key Vault para Python
Comece a usar a biblioteca de clientes do certificado do Azure Key Vault para Python. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas. Usando o Key Vault para armazenar certificados, você evita armazenar certificados no código, o que aumenta a segurança do aplicativo.
Documentação de referência da API | Código-fonte da biblioteca | Pacote (Índice de Pacote do Python)
Pré-requisitos
- Uma assinatura do Azure – crie uma gratuitamente.
- Python 3.7 e superior
- CLI do Azure
Este início rápido assume que você está executando a CLI do Azure ou o Azure PowerShell em uma janela de terminal do Linux.
Configurar o ambiente local
Este início rápido usa a biblioteca de identidades do Azure com a CLI do Azure ou o Azure PowerShell 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 obter mais informações, confira Autenticar o cliente com a biblioteca de clientes da Identidade do Azure.
Entrar no Azure
Execute o comando
login.az loginSe 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.
Entre com suas credenciais de conta no navegador.
Instalar os pacotes
Em um terminal ou prompt de comando, crie uma pasta de projeto adequada e depois crie e ative um ambiente virtual do Python conforme descrito em Usar ambientes virtuais do Python
Instale a biblioteca de identidade do Microsoft Entra:
pip install azure.identityInstale a biblioteca de clientes do certificado do Key Vault:
pip install azure-keyvault-certificates
Criar um grupo de recursos e um cofre de chaves
Use o comando
az group createpara criar um grupo de recursos:az group create --name myResourceGroup --location eastusVocê poderá alterar "eastus" para um local mais próximo de você, se preferir.
Use
az keyvault createpara criar o cofre de chaves:az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroupSubstitua
<your-unique-keyvault-name>por um nome que seja exclusivo em todo o Azure. Normalmente, você usa o nome pessoal ou da empresa junto com outros números e identificadores.
Definir a variável de ambiente KEY_VAULT_NAME
Nosso script usará o valor atribuído à variável de ambiente KEY_VAULT_NAME como o nome do cofre de chaves. Portanto, você deve definir esse valor usando o seguinte comando:
export KEY_VAULT_NAME=<your-unique-keyvault-name>
Permitir acesso ao cofre de chaves
Para obter permissões para o cofre de chaves por meio do RBAC (controle de acesso baseado em função), atribua uma função ao seu UPN (nome principal do usuário) usando o comando da CLI do Azure az role assignment create.
az role assignment create --role "Key Vault Certificate 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 valores reais. Seu UPN normalmente estará no formato de um endereço de email (por exemplo, username@domain.com).
Criar o código de exemplo
A biblioteca de clientes do certificado do Azure Key Vault para Python permite gerenciar certificados. O exemplo de código a seguir demonstrará como criar um cliente, além de definir, recuperar e excluir um certificado.
Crie um arquivo chamado kv_certificates.py que contenha esse código.
import os
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
from azure.identity import DefaultAzureCredential
keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = "https://" + keyVaultName + ".vault.azure.net"
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)
certificateName = input("Input a name for your certificate > ")
print(f"Creating a certificate in {keyVaultName} called '{certificateName}' ...")
policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()
print(" done.")
print(f"Retrieving your certificate from {keyVaultName}.")
retrieved_certificate = client.get_certificate(certificateName)
print(f"Certificate with name '{retrieved_certificate.name}' was found'.")
print(f"Deleting your certificate from {keyVaultName} ...")
poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()
print(" done.")
Executar o código
Verifique se o código na seção anterior está em um arquivo chamado kv_certificates.py. Execute o código com o seguinte comando:
python kv_certificates.py
- Se você encontrar erros de permissões, verifique se executou o
az keyvault set-policyouSet-AzKeyVaultAccessPolicycomando. - Executar novamente o código com o mesmo nome de chave pode produzir este erro: “O Certificado <nome>(Conflito) está em um estado excluído, mas recuperável”. Use um nome de chave diferente.
Detalhes do código
Autenticar e criar um cliente
As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes da Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no código. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.
Neste guia de início rápido, DefaultAzureCredential se autenticará no cofre de chaves usando as credenciais do usuário de desenvolvimento local conectado à CLI do Azure. Quando o aplicativo é implantado no Azure, o mesmo código DefaultAzureCredential pode descobrir e usar automaticamente uma identidade gerenciada atribuída a um Serviço de Aplicativo, máquina virtual ou outros serviços. Para obter mais informações, confira Visão geral da Identidade Gerenciada.
No código de exemplo, o nome do cofre de chaves é expandido para a URI do cofre de chaves, no formato https://\<your-key-vault-name>.vault.azure.net.
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)
Salvar um certificado
Depois de obter o objeto de cliente para o cofre de chaves, você pode criar um certificado usando o método begin_create_certificate:
policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()
Aqui, o certificado requer uma política obtida com o método CertificatePolicy.get_default.
Chamar um método begin_create_certificate gera uma chamada assíncrona à API REST do Azure para o cofre de chaves. A chamada assíncrona retorna um objeto do instrumento de sondagem. Para aguardar o resultado da operação, chame o método result do instrumentos de sondagem.
Quando o Azure lida com a solicitação, ele autentica a identidade do chamador (a entidade de serviço) usando o objeto de credencial que você forneceu ao cliente.
Recuperar um certificado
Para ler um certificado do Key Vault, use o método get_certificate:
retrieved_certificate = client.get_certificate(certificateName)
Também é possível verificar se o certificado foi definido com o comando az keyvault certificate show da CLI do Azure ou com o cmdlet Get-AzKeyVaultCertificate do Azure PowerShell
Excluir um certificado
Para excluir um certificado, use o método begin_delete_certificate:
poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()
O método begin_delete_certificate é assíncrono e retorna um objeto do instrumento de sondagem. Chamar o método result do instrumento de sondagem aguarda sua conclusão.
É possível verificar se o certificado foi excluído com o comando az keyvault certificate show da CLI do Azure ou com o cmdlet Get-AzKeyVaultCertificate do Azure PowerShell.
Depois de excluído, um certificado permanece em um estado excluído, mas recuperável, por algum tempo. Se você executar o código novamente, use outro nome de certificado.
Limpar os recursos
Se você também quiser experimentar segredos e chaves, poderá reutilizar o Key Vault criado neste artigo.
Caso contrário, quando tiver concluído os recursos criados neste artigo, use o seguinte comando para excluir o grupo de recursos e todos os recursos que ele contém:
az group delete --resource-group myResourceGroup