Partilhar via

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

Introdução à biblioteca de cliente de 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. Ao usar o Cofre da Chave para armazenar certificados, você evita armazenar certificados em seu código, o que aumenta a segurança do seu aplicativo.

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

Pré-requisitos

Este início rápido pressupõe que estás a executar a CLI do Azure ou o Azure PowerShell num terminal Linux.

Configurar o ambiente local

Este guia de início rápido usa a biblioteca de Identidade 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 suas chamadas. Para obter mais informações, consulte Autenticar o cliente com a biblioteca de cliente Azure Identity.

Iniciar sessão no Azure

  1. 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 em https://aka.ms/devicelogin e insira o código de autorização exibido no seu terminal.

  2. Inicie sessão com as credenciais da sua conta no browser.

Instalar os pacotes

  1. Em um terminal ou prompt de comando, crie uma pasta de projeto adequada e, em seguida, crie e ative um ambiente virtual Python conforme descrito em Usar ambientes virtuais Python

  2. Instale a biblioteca de identidades do Microsoft Entra:

    pip install azure.identity

  3. Instale a biblioteca do cliente de certificados do Key Vault.

    pip install azure-keyvault-certificates

Criar um grupo de recursos e um cofre de chaves

  1. Use o comando az group create para criar um grupo de recursos:

    az group create --name myResourceGroup --location eastus

    Você pode mudar "eastus" para um local mais perto de você, se preferir.

  2. Use az keyvault create para criar o cofre de chaves:

    az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup

    Substitua <your-unique-keyvault-name> por um nome exclusivo em todo o Azure. Normalmente, utiliza o seu nome pessoal ou da empresa juntamente com outros números e identificadores.

Definir a variável ambiental 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>

Conceder acesso ao seu cofre de chaves

Para obter permissões para o seu cofre de chaves através do RBAC (Controle de Acesso Baseado em Função), atribua um papel ao seu "Nome Principal do Usuário" (UPN) utilizando o comando az role assignment create na Azure CLI.

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 o código de exemplo

A biblioteca de cliente de certificados do Azure Key Vault para Python permite gerenciar certificados. O exemplo de código a seguir demonstra como criar um cliente, definir um certificado, recuperar um certificado e excluir um certificado.

Crie um arquivo chamado kv_certificates.py que contém 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. Em seguida, execute o código com o seguinte comando:

python kv_certificates.py
  • Se encontrar erros de permissões, certifique-se de que executou o az keyvault set-policy comando ouSet-AzKeyVaultAccessPolicy.
  • Executar novamente o código com o mesmo nome de chave pode produzir o erro, "(Conflito) O nome> do certificado <está atualmente 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 de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar a classe DefaultAzureCredential fornecida pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em 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 utilizador de desenvolvimento local conectado à CLI do Azure. Quando a aplicação é implementada no Azure, o mesmo DefaultAzureCredential 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 gerenciada.

No código de exemplo, o nome do cofre de chaves é expandido para o URI do cofre de chaves, no formato https://\<your-key-vault-name>.vault.azure.net.

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

Guardar um certificado

Depois de obter o objeto cliente para o cofre de chaves, poderás 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 através do método CertificatePolicy.get_default.

Chamar um begin_create_certificate método gera uma chamada assíncrona para a API REST do Azure para o Key Vault. A chamada assíncrona retorna um objeto poller. Para aguardar o resultado da operação, chame o método result do poller.

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 Azure Key Vault, use o método get_certificate:

retrieved_certificate = client.get_certificate(certificateName)

Você também pode 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 eliminar 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 poller. Chamar o método do result poller espera pela sua conclusão.

Você pode verificar se o certificado foi eliminado usando o comando az keyvault certificate show da CLI do Azure ou o cmdlet Get-AzKeyVaultCertificate do Azure PowerShell.

Uma vez excluído, um certificado permanece em um estado excluído, mas recuperável por um tempo. Se você executar o código novamente, use um nome de certificado diferente.

Limpar recursos

Se quiser também experimentar segredos e chaves, pode reutilizar o Cofre da Chave criado neste artigo.

Caso contrário, quando terminar os recursos criados neste artigo, use o seguinte comando para excluir o grupo de recursos e todos os recursos contidos:

az group delete --resource-group myResourceGroup

Próximos passos