Biblioteca cliente de Administración de Azure Key Vault para Python: versión 4.3.0
Nota: La biblioteca de administración solo funciona con HSM administrado: se producirá un error en las funciones destinadas a un Key Vault.
Azure Key Vault ayuda a solucionar los problemas siguientes:
- Administración del almacén (esta biblioteca): control de acceso basado en rol (RBAC) y opciones de copia de seguridad y restauración de nivel de almacén
- 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 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
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 obtener más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.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-administration y azure-identity con pip:
pip install azure-keyvault-administration 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 3.7 o versiones posteriores
- Un HSM administrado Key Vault existente. Si necesita crear una, puede hacerlo mediante la CLI de Azure siguiendo los pasos descritos en este documento.
Autenticar el cliente
Para interactuar con el servicio Azure Key Vault, necesitará una instancia de KeyVaultAccessControlClient o KeyVaultBackupClient, así como una dirección URL del almacén (que puede ver como "Nombre DNS" en Azure Portal) 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 objeto KeyVaultAccessControlClient
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 de control de acceso (reemplazando el valor de vault_url por la dirección URL de HSM administrado):
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
NOTA: En el caso de un cliente asincrónico, importe
azure.keyvault.administration.aioenKeyVaultAccessControlClientsu lugar.
Creación de una instancia de KeyVaultBackupClient
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 de copia de seguridad (reemplazando el valor de vault_url por la dirección URL de HSM administrado):
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
NOTA: En el caso de un cliente asincrónico, importe
azure.keyvault.administration.aioenKeyVaultBackupClientsu lugar.
Creación de un objeto KeyVaultSettingsClient
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 de configuración (reemplazando el valor de vault_url por la dirección URL del HSM administrado):
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient
credential = DefaultAzureCredential()
client = KeyVaultSettingsClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
NOTA: En el caso de un cliente asincrónico, importe
azure.keyvault.administration.aioenKeyVaultSettingsClientsu lugar.
Conceptos clave
Definición de roles
Una definición de rol define las operaciones que se pueden realizar, como lectura, escritura y eliminación. También puede definir las operaciones que se excluyen de las operaciones permitidas.
Una definición de rol se especifica como parte de una asignación de roles.
Asignación de roles
Una asignación de roles es la asociación de una definición de rol a una entidad de servicio. Se pueden crear, enumerar, capturar individualmente y eliminar.
KeyVaultAccessControlClient
Un KeyVaultAccessControlClient administra las definiciones de roles y las asignaciones de roles.
KeyVaultBackupClient
KeyVaultBackupClient realiza copias de seguridad de claves completas, restauraciones de claves completas y restauraciones de claves selectivas.
KeyVaultSettingsClient
Un KeyVaultSettingsClient administra la configuración de la cuenta de HSM administrada.
Ejemplos
Esta sección contiene fragmentos de código que abarcan tareas comunes:
- Control de acceso
- Copia de seguridad y restauración
Lista de todas las definiciones de rol
Enumere las definiciones de roles disponibles para la asignación.
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)
for definition in role_definitions:
print(definition.id)
print(definition.role_name)
print(definition.description)
Establecer, obtener y eliminar una definición de rol
set_role_definition se puede usar para crear una definición de rol personalizada o actualizar una definición existente con el nombre especificado.
import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
KeyVaultAccessControlClient,
KeyVaultDataAction,
KeyVaultPermission,
KeyVaultRoleScope
)
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)
# update the custom role definition
permissions = [
KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)
# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
Lista de todas las asignaciones de roles
Antes de crear una nueva asignación de roles en el siguiente fragmento de código, enumere todas las asignaciones de roles actuales:
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)
for assignment in role_assignments:
print(assignment.name)
print(assignment.principal_id)
print(assignment.role_definition_id)
Creación, obtención y eliminación de una asignación de roles
Asigne un rol a una entidad de servicio. Esto requerirá un identificador de definición de rol y un identificador de objeto de entidad de servicio. Puede usar un identificador de la lista recuperada de definiciones de roles para el anterior y una asignación principal_id de la lista recuperada en el fragmento de código anterior para este último.
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"
# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
Realización de una copia de seguridad de clave completa
Realice una copia de seguridad de toda la colección de claves. El almacén de respaldo para copias de seguridad de claves completas es un contenedor de almacenamiento de blobs mediante la autenticación de firma de acceso compartido.
Para obtener más información sobre cómo crear un token de SAS mediante BlobServiceClient, consulte el ejemplo aquí.
Como alternativa, es posible generar un token de SAS en Explorador de Storage
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>" # replace with a sas token to your storage account
# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()
# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)
Realización de una restauración de claves completa
Restaure toda la colección de claves a partir de una copia de seguridad. El origen de datos para una restauración de clave completa es un blob de almacenamiento al que se accede mediante la autenticación de firma de acceso compartido.
También necesitará el azure_storage_blob_container_uri del fragmento de código anterior.
Para obtener más información sobre cómo crear un token de SAS mediante BlobServiceClient, consulte el ejemplo aquí.
Como alternativa, es posible generar un token de SAS en Explorador de Storage
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
sas_token = "<your-sas-token>" # replace with a sas token to your storage account
# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"
# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()
Solución de problemas
Consulte la azure-keyvault-administrationguí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 asignación de roles que no existe, KeyVaultAccessControlClient genera ResourceNotFoundError:
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
try:
client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
Los clientes de la biblioteca de administración solo se pueden usar para realizar operaciones en un HSM administrado, por lo que al intentar hacerlo en un Key Vault se producirá un error.
Pasos siguientes
Hay varios ejemplos disponibles en el repositorio de GitHub del SDK de Azure para Python. Estos ejemplos proporcionan código de ejemplo para escenarios de Key Vault adicionales: | Archivo | Descripción | |-------------|-------------| | access_control_operations.py | crear, actualizar o eliminar definiciones de roles y asignaciones de roles | | access_control_operations_async.py | crear, actualizar o eliminar definiciones de roles y asignaciones de roles con un cliente asincrónico | | backup_restore_operations.py | copia de seguridad y restauración completas | | backup_restore_operations_async.py | copia de seguridad completa y restauración con un cliente asincrónico | | settings_operations.py | enumerar y actualizar la configuración de Key Vault | | settings_operations_async.py | enumerar y actualizar la configuración de Key Vault con un cliente asincrónico |
Documentación adicional
Para obtener documentación más amplia sobre Azure Key Vault, consulte la documentación de referencia de API.
Para obtener documentación más amplia sobre HSM administrado, consulte la documentación del servicio.
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.
Azure SDK for Python