Biblioteca de clientes do Azure Key Vault Secrets para Python – versão 4.7.0

  • Artigo

O Azure Key Vault ajuda a resolver os problemas a seguir:

  • Gerenciamento de segredos (esta biblioteca) – armazene e controle com segurança o acesso a tokens, senhas, certificados, chaves de API e outros segredos
  • Gerenciamento de chaves criptográficas (azure-keyvault-keys) – criar, armazenar e controlar o acesso às chaves usadas para criptografar seus dados
  • Gerenciamento de certificados (azure-keyvault-certificates) – criar, gerenciar e implantar certificados SSL/TLS públicos e privados
  • Administração do cofre (azure-keyvault-administration) – RBAC (controle de acesso baseado em função) e opções de backup e restauração no nível do cofre

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

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691. É necessário ter o Python 3.7 ou posterior para usar esse pacote. Para obter mais detalhes, consulte a política de suporte do SDK do Azure para Python.

Introdução

Instalar Pacotes

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

pip install azure-keyvault-secrets azure-identity

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

Pré-requisitos

Autenticar o cliente

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

Confira a documentação do azure-identity para obter mais informações sobre outros métodos de autenticação e seus tipos de credencial correspondentes.

Criar um cliente

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

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

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

Principais conceitos

Segredo

Um segredo consiste em um valor secreto e seus metadados associados e informações de gerenciamento. Essa biblioteca manipula valores secretos como cadeias de caracteres, 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 gerencia, consulte a documentação do Key Vault.

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

Exemplos

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

Definir um segredo

set_secret cria novos segredos e altera os valores dos segredos existentes. Se nenhum segredo com o nome fornecido existir, set_secret criará um novo segredo com esse nome e o valor fornecido. Se o nome fornecido estiver em uso, set_secret criará uma nova versão desse segredo, com o valor fornecido.

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)

Recuperar um segredo

get_secret recupera um segredo armazenado anteriormente 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. Ele não pode alterar o valor do segredo; use 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)

Excluir um segredo

begin_delete_secret solicita Key Vault excluir um segredo, retornando um sondador que permite aguardar a conclusão da exclusão. Aguardar é útil quando o cofre tem a exclusão reversível habilitada e você deseja limpar (excluir permanentemente) o segredo assim que possível. Quando a exclusão reversível está desabilitada, begin_delete_secret ela é 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. Essa 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

Essa biblioteca inclui um conjunto completo de APIs assíncronas. Para usá-los, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

Os clientes e credenciais assíncronos devem ser fechados quando não forem mais necessários. Esses objetos são gerenciadores de contexto assíncronos e definem métodos assíncronos 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 no 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)

Solução de problemas

Consulte o azure-keyvault-secretsguia de soluçã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 você tentar obter uma chave que não existe no cofre, SecretClient aciona 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)

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. As informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível info.

O log detalhado no nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um 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 habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

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

Próximas etapas

Vários exemplos estão disponíveis no repositório GitHub do SDK do Azure para Python. Eles fornecem código de exemplo para cenários de Key Vault adicionais: | Arquivo | Descrição | |-------------|-------------| | hello_world.py (versão assíncrona) | criar/obter/atualizar/excluir segredos | | list_operations.py (versão assíncrona) | operações de lista básica para segredos | | backup_restore_operations.py (versão assíncrona) | fazer backup e restaurar segredos | | recover_purge_operations.py (versão assíncrona) | recuperar e limpar segredos |

Documentação Adicional

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

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões