Compartir a través de

Biblioteca cliente de Claves de Azure Key Vault para Python, versión 4.3.1

Azure Key Vault ayuda a solucionar los problemas siguientes:

  • Administración de claves criptográficas (esta biblioteca): creación, almacenamiento y control del acceso a las claves usadas para cifrar los datos
  • Administración de secretos (azure-keyvault-secrets): almacene y controle de forma segura el acceso a tokens, contraseñas, certificados, claves de API y otros secretos.
  • 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) | Documentación | de referencia de API | Documentación del productoMuestras

Introducción

Instalar paquetes

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

pip install azure-keyvault-keys azure-identity

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

Requisitos previos

  • Una suscripción de Azure

  • Python 2.7, 3.5.3 o versiones posteriores

  • Un Key Vault. Si necesita crear uno, puede usar azure Cloud Shell para crear uno con estos comandos (reemplace "my-resource-group" y "my-key-vault" por sus propios nombres únicos):

    (Opcional) si desea que un nuevo grupo de recursos contenga la Key Vault:

    az group create --name my-resource-group --location westus2

    Cree el Key Vault:

    az keyvault create --resource-group my-resource-group --name my-key-vault

    Salida:

    {
    "id": "...",
    "location": "westus2",
    "name": "my-key-vault",
    "properties": {
        "accessPolicies": [...],
        "createMode": null,
        "enablePurgeProtection": null,
        "enableSoftDelete": null,
        "enabledForDeployment": false,
        "enabledForDiskEncryption": null,
        "enabledForTemplateDeployment": null,
        "networkAcls": null,
        "provisioningState": "Succeeded",
        "sku": { "name": "standard" },
        "tenantId": "...",
        "vaultUri": "https://my-key-vault.vault.azure.net/"
    },
    "resourceGroup": "my-resource-group",
    "type": "Microsoft.KeyVault/vaults"
}

    La "vaultUri" propiedad es la vault_url usada por KeyClient.

Autenticar el cliente

En este documento se muestra cómo usar DefaultAzureCredential para autenticarse como entidad de servicio. Sin embargo, KeyClient acepta cualquier credencial de azure-identity . Consulte la documentación de azure-identity para más información sobre otras credenciales.

Creación de una entidad de servicio (opcional)

Este fragmento de código de Azure Cloud Shell muestra cómo crear una nueva entidad de servicio. Antes de usarlo, reemplace "your-application-name" por un nombre más adecuado para la entidad de servicio.

Cree una entidad de servicio:

az ad sp create-for-rbac --name http://my-application --skip-assignment

Salida:

{
    "appId": "generated app id",
    "displayName": "my-application",
    "name": "http://my-application",
    "password": "random password",
    "tenant": "tenant id"
}

Use la salida para establecer AZURE_CLIENT_ID ("appId" anterior), AZURE_CLIENT_SECRET ("contraseña" anterior) y AZURE_TENANT_ID ("inquilino" anterior) variables de entorno. En el ejemplo siguiente se muestra una manera de hacerlo en Bash:

export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"

Autorice a la entidad de servicio para realizar operaciones de clave en el Key Vault:

az keyvault set-policy --name my-key-vault --spn $AZURE_CLIENT_ID --key-permissions backup delete get list create update decrypt encrypt

Permisos posibles:

  • Administración de claves: backup, delete, get, list, purge, recover, restore, create, update, import
  • Operaciones criptográficas: descifrado, cifrado, unwrapKey, wrapKey, verify, sign

Creación de un cliente

Una vez establecida la AZURE_CLIENT_ID, AZURE_CLIENT_SECRET y AZURE_TENANT_ID variables de entorno, DefaultAzureCredential podrá autenticar KeyClient.

La construcción del cliente también requiere la dirección URL del almacén, que puede obtener desde la CLI de Azure o Azure Portal. En Azure Portal, esta dirección URL es el "nombre DNS" del almacén.

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

credential = DefaultAzureCredential()

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

Conceptos clave

Teclas

Azure Key Vault puede crear y almacenar claves de curva RSA y elípticas. Ambos se pueden proteger opcionalmente mediante módulos de seguridad de hardware (HSM). Azure Key Vault también puede realizar operaciones criptográficas con ellos. Para obtener más información sobre las claves y las operaciones y algoritmos admitidos, consulte la documentación de Key Vault.

KeyClient puede crear claves en el almacén, obtener claves existentes del almacén, actualizar metadatos de clave y eliminar claves, como se muestra en los siguientes.

Ejemplos

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

Crear una clave

create_rsa_key y create_ec_key crear claves de curva RSA y elípticas en el almacén, respectivamente. Si ya existe una clave con el mismo nombre, se crea una nueva versión de esa clave.

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

credential = DefaultAzureCredential()

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

# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Recuperar una clave

get_key recupera una clave almacenada anteriormente en el almacén.

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

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)

Actualizar una clave existente

update_key_properties actualiza las propiedades de una clave almacenada previamente en el Key Vault.

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

credential = DefaultAzureCredential()

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

# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)

print(updated_key.name)
print(updated_key.properties.enabled)

Eliminar una clave

begin_delete_key solicita Key Vault eliminar una clave, devolviendo un sondeo que permite esperar a que finalice la eliminación. La espera resulta útil cuando el almacén tiene habilitada la eliminación temporal y desea purgar (eliminar permanentemente) la clave lo antes posible. Cuando la eliminación temporal está deshabilitada, begin_delete_key es permanente.

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

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

Enumeración de claves

list_properties_of_keys enumera las propiedades de todas las claves del almacén del cliente.

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

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

for key in keys:
    # the list doesn't include values or versions of the keys
    print(key.name)

Operaciones criptográficas

CryptographyClient permite operaciones criptográficas (cifrar/descifrar, encapsular/desencapsular, firmar/comprobar) mediante una clave determinada.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

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

key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"

result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)

Consulte la documentación del paquete para obtener más detalles de la API de criptografía.

API asincrónica

Esta biblioteca incluye una API asincrónica completa compatible con Python 3.5 y versiones posteriores. Para usarlo, 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 deben cerrarse cuando ya no sean necesarios. Cada cliente asincrónico es un administrador de contexto asincrónico y define un método asincrónico close . Por ejemplo:

from azure.keyvault.keys import KeyClient

# call close when the client is no longer needed
client = KeyClient()
...
await client.close()

# alternatively, use the client as an async context manager
client = KeyClient()
async with client:
  ...

Creación asincrónica de una clave

create_rsa_key y create_ec_key crear claves de curva RSA y elípticas en el almacén, respectivamente. Si ya existe una clave con el mismo nombre, se crea una nueva versión de la clave.

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

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

# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Enumerar claves de forma asincrónica

list_properties_of_keys enumera las propiedades de todas las claves del almacén del cliente.

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

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

async for key in keys:
    print(key.name)

Solución de problemas

General

Key Vault los clientes generan excepciones definidas en azure-core. Por ejemplo, si intenta obtener una clave que no existe en el almacén, KeyClient genera ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError

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

try:
    key_client.get_key("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 de DEPURACIÓN, 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.keys import KeyClient
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
client = KeyClient(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:

client.get_key("my-key", 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:

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

  • Last updated on