Início Rápido: Biblioteca de clientes do segredo do Azure Key Vault para Python

  • Artigo

Introdução à biblioteca de clientes do segredo 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 Key Vault para armazenar segredos, você evita armazenar segredos 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

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 está usando 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 saber mais, confira Autenticar o cliente na biblioteca de clientes do Azure Idendity.

Entrar no Azure

  1. Execute o comando az login.

    az login

    Se 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.

  2. Entre com suas credenciais de conta no navegador.

Instalar os pacotes

  1. 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.

  2. Instale a biblioteca de identidade do Microsoft Entra:

    pip install azure-identity

  3. Instale a biblioteca de segredos do Key Vault:

    pip install azure-keyvault-secrets

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ê poderá alterar "eastus" para um local mais próximo 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 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 conceder permissões de aplicativo ao cofre de chaves por meio do controle de acesso baseado em função (RBAC), atribua uma função usando o comando az role assignment create da CLI do Azure.

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Substitua <app-id>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos valores reais. <app-id> é a ID do aplicativo (cliente) do aplicativo registrado no Azure AD.

Criar o código de exemplo

A biblioteca de clientes do segredo do Azure Key Vault para Python permite que você gerencie 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 contenha 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. Execute o código com o seguinte comando:

python kv_secrets.py
  • Se você encontrar erros de permissões, verifique se executou o az keyvault set-policy ou Set-AzKeyVaultAccessPolicy comando.
  • Executar novamente o código com o mesmo nome de segredo pode produzir o erro "(Conflito) O <nome> do segredo está atualmente em um estado excluído, mas recuperável". Use um nome de segredo 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 usando o valor da variável KVUri no seguinte formato: "https://<your-key-vault-name>.vault.azure.net".

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

Salvar um segredo

Depois de obter o objeto de cliente para o cofre de chaves, você pode armazenar um segredo usando o método set_secret:

client.set_secret(secretName, secretValue)

Chamar set_secret gera uma chamada à 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 Key Vault, use o método get_secret:

retrieved_secret = client.get_secret(secretName)

O valor do segredo está contido em retrieved_secret.value.

Também é possível recuperar um segredo com o comando az keyvault secret show da CLI do Azure ou com o cmdlet Get-AzKeyVaultSecret do Azure PowerShell.

Excluir um segredo

Para excluir um segredo, use o método begin_delete_secret:

poller = client.begin_delete_secret(secretName)
deleted_secret = poller.result()

O método begin_delete_secret é 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 segredo foi removido com o comando az keyvault secret show da CLI do Azure ou com o cmdlet Get-AzKeyVaultSecret do Azure PowerShell.

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

Limpar os recursos

Se você também quiser experimentar certificados 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

Próximas etapas