Guia de início rápido: biblioteca de cliente secreta do Azure Key Vault para Python
Introdução à biblioteca de cliente secreta 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 segredos, você evita armazenar segredos em seu código, o que aumenta a segurança do seu aplicativo.
Documentação | de referência da API Pacote de código-fonte | da biblioteca (Python Package Index)
Pré-requisitos
- Uma assinatura do Azure - crie uma gratuitamente.
- Python 3.7+.
- CLI do Azure ou Azure PowerShell.
Este início rápido pressupõe que você esteja executando a CLI do Azure ou o Azure PowerShell em uma janela de terminal Linux.
Configurar o ambiente local
Este guia de início rápido está usando 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 do Azure Identity.
Iniciar sessão no Azure
Execute o comando
az login.az loginSe 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.
Instalar os pacotes
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.
Instale a biblioteca de identidades do Microsoft Entra:
pip install azure-identityInstale a biblioteca de segredos do Key Vault:
pip install azure-keyvault-secrets
Criar um grupo de recursos e um cofre de chaves
Use o
az group createcomando para criar um grupo de recursos:az group create --name myResourceGroup --location eastusVocê pode mudar "eastus" para um local mais perto 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 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 à KEY_VAULT_NAME variável de ambiente 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 seu cofre de chaves por meio do RBAC (Controle de Acesso Baseado em Função), atribua uma função ao seu "Nome Principal do Usuário" (UPN) usando o comando az role assignment create da CLI do Azure.
az role assignment create --role "Key Vault Secrets 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 secreta do Azure Key Vault para Python permite gerenciar segredos. O exemplo de código a seguir demonstra como criar um cliente, definir um segredo, recuperar um segredo e excluir um segredo.
Crie um arquivo chamado kv_secrets.py que contém esse código.
import os
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = f"https://{keyVaultName}.vault.azure.net"
credential = DefaultAzureCredential()
client = SecretClient(vault_url=KVUri, credential=credential)
secretName = input("Input a name for your secret > ")
secretValue = input("Input a value for your secret > ")
print(f"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...")
client.set_secret(secretName, secretValue)
print(" done.")
print(f"Retrieving your secret from {keyVaultName}.")
retrieved_secret = client.get_secret(secretName)
print(f"Your secret is '{retrieved_secret.value}'.")
print(f"Deleting your secret from {keyVaultName} ...")
poller = client.begin_delete_secret(secretName)
deleted_secret = poller.result()
print(" done.")
Executar o código
Verifique se o código na seção anterior está em um arquivo chamado kv_secrets.py. Em seguida, execute o código com o seguinte comando:
python kv_secrets.py
- Se encontrar erros de permissões, certifique-se de que executou o
az keyvault set-policycomando ouSet-AzKeyVaultAccessPolicy. - Executar novamente o código com o mesmo nome secreto pode produzir o erro, "(Conflito) O nome> secreto <está atualmente em um estado excluído, mas recuperável." Use um nome secreto 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 usuário de desenvolvimento local conectado à CLI do Azure. Quando o aplicativo é implantado no Azure, o mesmo DefaultAzureCredential código 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, consulte Visão geral da identidade gerenciada.
No código de exemplo, o nome do cofre de chaves é expandido usando o valor da KVUri variável, no formato: "https://< your-key-vault-name.vault.azure.net>".
credential = DefaultAzureCredential()
client = SecretClient(vault_url=KVUri, credential=credential)
Guarde um segredo
Depois de obter o objeto cliente para o cofre de chaves, você pode armazenar um segredo usando o método set_secret :
client.set_secret(secretName, secretValue)
A chamada set_secret gera uma chamada para a API REST do Azure para o cofre de chaves.
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 segredo
Para ler um segredo do Cofre da Chave, use o método get_secret :
retrieved_secret = client.get_secret(secretName)
O valor secreto está contido em retrieved_secret.value.
Você também pode recuperar um segredo com o comando az keyvault secret show da CLI do Azure ou o cmdlet Get-AzKeyVaultSecret do Azure PowerShell.
Eliminar um segredo
Para excluir um segredo, use o método begin_delete_secret :
poller = client.begin_delete_secret(secretName)
deleted_secret = poller.result()
O begin_delete_secret método é assíncrono e retorna um objeto poller. Chamar o método do result poller aguarda a sua conclusão.
Você pode verificar se o segredo foi removido com o comando az keyvault secret show da CLI do Azure ou o cmdlet Get-AzKeyVaultSecret do Azure PowerShell.
Uma vez excluído, um segredo permanece em um estado excluído, mas recuperável por um tempo. Se você executar o código novamente, use um nome secreto diferente.
Clean up resources (Limpar recursos)
Se quiser também experimentar certificados 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