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

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

• Uma subscrição do Azure
• Python 3.7 ou posterior
• Uma Key Vault do Azure existente. Se precisar de criar uma, pode fazê-lo com a CLI do Azure ao seguir os passos neste documento.

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
• Obter um segredo
• Atualizar metadados secretos
• Eliminar um segredo
• Listar segredos
• API Assíncrona
• Criar um segredo de forma assíncrona
• Listar segredos de forma assíncrona

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.