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

Introdução à biblioteca de clientes 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 chaves criptográficas, você evita armazenar essas chaves 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 (Í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 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 obter mais informações, confira Autenticar o cliente com a biblioteca de clientes da Identidade do Azure.

Entrar no Azure

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 clientes de chave do Key Vault:

   pip install azure-keyvault-keys
   

Criar um grupo de recursos e um cofre de chaves

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 Crypto 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 de chaves do Azure Key Vault para Python permite gerenciar chaves de criptografia. O exemplo de código a seguir demonstra como criar um cliente, definir uma chave, recuperar uma chave e excluir uma chave.

Crie um arquivo chamado kv_keys.py que contenha esse código.

import os
from azure.keyvault.keys import KeyClient
from azure.identity import DefaultAzureCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = "https://" + keyVaultName + ".vault.azure.net"

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

keyName = input("Input a name for your key > ")

print(f"Creating a key in {keyVaultName} called '{keyName}' ...")

rsa_key = client.create_rsa_key(keyName, size=2048)

print(" done.")

print(f"Retrieving your key from {keyVaultName}.")

retrieved_key = client.get_key(keyName)

print(f"Key with name '{retrieved_key.name}' was found.")
print(f"Deleting your key from {keyVaultName} ...")

poller = client.begin_delete_key(keyName)
deleted_key = poller.result()

print(" done.")

Executar o código

Verifique se o código na seção anterior está em um arquivo chamado kv_keys.py. Execute o código com o seguinte comando:

python kv_keys.py

Executar o código novamente com o mesmo nome de chave pode produzir o erro "(Conflito) O <nome> da chave 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 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 = KeyClient(vault_url=KVUri, credential=credential)

Salvar uma chave

Depois de obter o objeto de cliente para o cofre de chaves, você pode armazenar uma chave usando o método create_rsa_key:

rsa_key = client.create_rsa_key(keyName, size=2048)

Você também pode usar create_key ou create_ec_key.

Chamar um método create 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 uma chave

Para ler uma chave do Key Vault, use o método get_key:

retrieved_key = client.get_key(keyName)

Também é possível verificar se a chave foi definida com o comando az keyvault key show da CLI do Azure ou com o cmdlet Get-AzKeyVaultKey do Azure PowerShell.

Excluir uma chave

Para excluir uma chave, use o método begin_delete_key:

poller = client.begin_delete_key(keyName)
deleted_key = poller.result()

O método begin_delete_key é 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 a chave foi excluída com o comando az keyvault key show da CLI do Azure ou com o cmdlet Get-AzKeyVaultKey do Azure PowerShell.

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

Limpar os recursos

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

Remove-AzResourceGroup -Name myResourceGroup

Próximas etapas

• Visão geral da o Cofre da Chave do Azure
• Proteger o acesso a um cofre de chaves
• Guia do RBAC
• Guia do desenvolvedor do Azure Key Vault
• Autenticar com o Key Vault