Biblioteca cliente de secretos de Azure Key Vault para Python: versión 4.7.0

  • Artículo

Azure Key Vault ayuda a solucionar los problemas siguientes:

  • Administración de secretos (esta biblioteca): almacene y controle de forma segura el acceso a tokens, contraseñas, certificados, claves de API y otros secretos.
  • Administración de claves criptográficas (azure-keyvault-keys): creación, almacenamiento y control del acceso a las claves usadas para cifrar los datos
  • Administración de certificados (azure-keyvault-certificates): creación, administración e implementación de certificados SSL/TLS públicos y privados
  • Administración de almacenes (azure-keyvault-administration): control de acceso basado en rol (RBAC) y opciones de copia de seguridad y restauración de nivel de almacén

Código | fuente Paquete (PyPI) | Paquete (Conda) | Documentación | de referencia de APIDocumentación | del producto Muestras

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691. Se requiere Python 3.7 o posterior para usar este paquete. Para más información, consulte la directiva de compatibilidad con la versión de Azure SDK para Python.

Introducción

Instalar paquetes

Instale azure-keyvault-secrets y azure-identity con pip:

pip install azure-keyvault-secrets azure-identity

azure-identity se usa para la autenticación de Azure Active Directory, como se muestra a continuación.

Requisitos previos

Autenticar el cliente

Para interactuar con el servicio azure Key Vault, necesitará una instancia de SecretClient, así como una dirección URL del almacén y un objeto de credencial. En este documento se muestra el uso de defaultAzureCredential, que es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales. Se recomienda usar una identidad administrada para la autenticación en entornos de producción.

Consulte la documentación de azure-identity para obtener más información sobre otros métodos de autenticación y sus tipos de credenciales correspondientes.

Creación de un cliente

Después de configurar el entorno para que DefaultAzureCredential use un método adecuado de autenticación, puede hacer lo siguiente para crear un cliente secreto (reemplazando el valor de VAULT_URL por la dirección URL del almacén):

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

NOTA: En el caso de un cliente asincrónico, importe azure.keyvault.secrets.aioen SecretClient su lugar.

Conceptos clave

Secreto

Un secreto consta de un valor secreto y sus metadatos y información de administración asociados. Esta biblioteca controla los valores secretos como cadenas, pero Azure Key Vault no los almacena como tal. Para obtener más información sobre los secretos y cómo Key Vault almacena y administra, consulte la documentación de Key Vault.

SecretClient puede establecer valores secretos en el almacén, actualizar metadatos secretos y eliminar secretos, como se muestra en los ejemplos siguientes.

Ejemplos

Esta sección contiene fragmentos de código que abarcan tareas comunes:

Establecimiento de un secreto

set_secret crea nuevos secretos y cambia los valores de los secretos existentes. Si no existe ningún secreto con el nombre especificado, set_secret crea un nuevo secreto con ese nombre y el valor especificado. Si el nombre especificado está en uso, set_secret crea una nueva versión de ese secreto, con el 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)

Recuperación de un secreto

get_secret recupera un secreto almacenado anteriormente en el 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)

Actualizar metadatos secretos

update_secret_properties actualiza los metadatos de un secreto. No puede cambiar el valor del secreto; use set_secret para establecer el valor de un secreto.

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 un secreto

begin_delete_secret solicitudes Key Vault eliminar un secreto, devolviendo un sondeo que le permite esperar a que finalice la eliminación. Esperar es útil cuando el almacén tiene habilitada la eliminación temporal y desea purgar (eliminar permanentemente) el secreto lo antes posible. Cuando la eliminación temporal está deshabilitada, begin_delete_secret es 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)

Enumeración de secretos

list_properties_of_secrets enumera las propiedades de todos los secretos del almacén del cliente. Esta lista no incluye los valores del secreto.

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 asincrónica

Esta biblioteca incluye un conjunto completo de API asincrónicas. Para usarlos, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.

Los clientes asincrónicos y las credenciales deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close . Por ejemplo:

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

Crear de forma asincrónica un secreto

set_secret crea un secreto en el Key Vault con los argumentos opcionales 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)

Enumerar de forma asincrónica los secretos

list_properties_of_secrets enumera las propiedades de todos los secretos del almacén del 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)

Solución de problemas

Consulte la azure-keyvault-secretsguía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

General

Key Vault clientes generan excepciones definidas en azure-core. Por ejemplo, si intenta obtener una clave que no existe en el almacén, SecretClient genera 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

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el 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
)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

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

Pasos siguientes

Hay varios ejemplos disponibles en el repositorio de GitHub del SDK de Azure para Python. Estos proporcionan código de ejemplo para escenarios de Key Vault adicionales: | Archivo | Descripción | |-------------|-------------| | hello_world.py (versión asincrónica) | create/get/update/delete secrets | | list_operations.py (versión asincrónica) | Operaciones básicas de lista para secretos | | backup_restore_operations.py (versión asincrónica) | copia de seguridad y restauración de secretos | | recover_purge_operations.py (versión asincrónica) | recuperar y purgar secretos |

Documentación adicional

Para obtener documentación más amplia sobre Azure Key Vault, consulte la documentación de referencia de API.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones