Partilhar via

Biblioteca de cliente segredos do Azure Key Vault para Python – versão 4.7.0

  • Artigo

O Azure Key Vault ajuda a resolver os seguintes problemas:

  • Gestão de segredos (esta biblioteca) – armazene e controle de forma segura o acesso a tokens, palavras-passe, certificados, chaves de API e outros segredos
  • Gestão de chaves criptográficas (azure-keyvault-keys) – criar, armazenar e controlar o acesso às chaves utilizadas para encriptar os seus dados
  • Gestão de certificados (azure-keyvault-certificates) – criar, gerir e implementar certificados SSL/TLS públicos e privados
  • Administração do cofre (azure-keyvault-administration) – controlo de acesso baseado em funções (RBAC) e opções de cópia de segurança e restauro ao nível do cofre

Código fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do | produto Exemplos

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691. O Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, veja Azure SDK for Python version support policy (Política de suporte de versões do Azure SDK para Python).

Introdução

Instalar pacotes

Instale azure-keyvault-secrets e azure-identity com pip:

pip install azure-keyvault-secrets azure-identity

A azure-identity é utilizada para a autenticação do Azure Active Directory, conforme demonstrado abaixo.

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, precisará de uma instância de um SecretClient, bem como de um URL do cofre e de um objeto de credencial. Este documento demonstra a utilização de um DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção.

Veja a documentação do azure-identity para obter mais informações sobre outros métodos de autenticação e os respetivos tipos de credenciais correspondentes.

Criar um cliente

Depois de configurar o seu ambiente para o DefaultAzureCredential para utilizar um método de autenticação adequado, pode fazer o seguinte para criar um cliente secreto (substituindo o valor de VAULT_URL pelo URL do cofre):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)

NOTA: Em vez disso, para um cliente assíncrono, importe azure.keyvault.secrets.aio's SecretClient .

Conceitos-chave

Segredo

Um segredo consiste num valor secreto e nas respetivas informações de gestão e metadados associados. Esta biblioteca processa valores secretos como cadeias, mas o Azure Key Vault não os armazena como tal. Para obter mais informações sobre segredos e como Key Vault os armazena e gere, veja a documentação do Key Vault.

SecretClient pode definir valores secretos no cofre, atualizar metadados secretos e eliminar segredos, conforme mostrado nos exemplos abaixo.

Exemplos

Esta secção contém fragmentos de código que abrangem tarefas comuns:

Definir um segredo

set_secret cria novos segredos e altera os valores dos segredos existentes. Se não existir nenhum segredo com o nome especificado, set_secret cria um novo segredo com esse nome e o valor especificado. Se o nome especificado estiver a ser utilizado, set_secret cria uma nova versão desse segredo, com o valor especificado.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

Obter um segredo

get_secret obtém um segredo anteriormente armazenado no Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")

print(secret.name)
print(secret.value)

Atualizar metadados secretos

update_secret_properties atualiza os metadados de um segredo. Não pode alterar o valor do segredo; utilize set_secret para definir o valor de um segredo.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"

# We will also disable the secret for further use

updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)

print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)

Eliminar um segredo

begin_delete_secret pedidos Key Vault eliminar um segredo, devolvendo um poller que lhe permite esperar pela conclusão da eliminação. A espera é útil quando o cofre tem a eliminação recuperável ativada e pretende remover (eliminar permanentemente) o segredo o mais rapidamente possível. Quando a eliminação recuperável é desativada, begin_delete_secret a própria é permanente.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()

print(deleted_secret.name)
print(deleted_secret.deleted_date)

Listar segredos

list_properties_of_secrets lista as propriedades de todos os segredos no cofre do cliente. Esta lista não inclui os valores do segredo.

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()

secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

API Assíncrona

Esta biblioteca inclui um conjunto completo de APIs assíncronas. Para utilizá-las, primeiro tem de instalar um transporte assíncrono, como o aiohttp. Veja a documentação do azure-core para obter mais informações.

Os clientes assíncrono e as credenciais devem ser fechados quando já não forem necessários. Estes objetos são gestores de contexto assíncrono e definem métodos assíncronas close . Por exemplo:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Criar um segredo de forma assíncrona

set_secret cria um segredo na Key Vault com os argumentos opcionais especificados.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

secret = await secret_client.set_secret("secret-name", "secret-value")

print(secret.name)
print(secret.value)
print(secret.properties.version)

Listar segredos de forma assíncrona

list_properties_of_secrets lista as propriedades de todos os segredos no cofre do cliente.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()

async for secret_property in secret_properties:
    # the list doesn't include values or versions of the secrets
    print(secret_property.name)

Resolução de problemas

Veja o azure-keyvault-secretsguia de resolução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Key Vault clientes geram exceções definidas no azure-core. Por exemplo, se tentar obter uma chave que não existe no cofre, SecretClient gera ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    secret_client.get_secret("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Registo

Esta biblioteca utiliza a biblioteca de registo padrão para registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo de nível de DEBUG detalhado, incluindo os corpos de pedido/resposta e os cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento :

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
secret_client = SecretClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

Da mesma forma, logging_enable pode ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

secret_client.get_secret("my-secret", logging_enable=True)

Passos seguintes

Estão disponíveis vários exemplos no repositório do GitHub do Azure SDK para Python. Estes fornecem código de exemplo para cenários de Key Vault adicionais: | Ficheiro | Descrição | |-------------|-------------| | hello_world.py (versão assíncrona) | criar/obter/atualizar/eliminar segredos | | list_operations.py (versão assíncrona) | operações básicas de lista para segredos | | backup_restore_operations.py (versão assíncrona) | criar cópias de segurança e restaurar segredos | | recover_purge_operations.py (versão assíncrona) | recuperar e remover segredos |

Documentação Adicional

Para obter documentação mais extensa sobre o Azure Key Vault, veja a documentação de referência da API.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões