Biblioteca cliente de certificados de Azure Key Vault para Python: versión 4.7.0
Azure Key Vault ayuda a solucionar los problemas siguientes:
- Administración de certificados (esta biblioteca): creación, administración e implementación de certificados SSL/TLS públicos y privados
- 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 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 el paquete
Instale azure-keyvault-certificates y azure-identity con pip:
pip install azure-keyvault-certificates 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
- Una Key Vault de Azure 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 CertificateClient, 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 de certificado (reemplazando el valor de VAULT_URL
por la dirección URL del almacén):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=VAULT_URL, credential=credential)
NOTA: En el caso de un cliente asincrónico, importe
azure.keyvault.certificates.aio
enCertificateClient
su lugar.
Conceptos clave
CertificateClient
Con CertificateClient , puede obtener certificados del almacén, crear nuevos certificados y nuevas versiones de certificados existentes, actualizar metadatos de certificado y eliminar certificados. También puede administrar emisores de certificados, contactos y directivas de administración de certificados. Esto se ilustra en los ejemplos siguientes.
Ejemplos
Esta sección contiene fragmentos de código que abarcan tareas comunes:
- Crear un certificado
- Recuperación de un certificado
- Actualizar las propiedades de un certificado existente
- Eliminar un certificado
- Enumerar las propiedades de los certificados
- Operaciones asincrónicas
- Creación asincrónica de un certificado
- Enumerar de forma asincrónica las propiedades de los certificados
Crear un certificado
begin_create_certificate crea un certificado que se almacenará en Azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado. Antes de crear un certificado, se puede crear una directiva de administración para el certificado o se usará nuestra directiva predeterminada. Este método devuelve un sondeo de operación de larga duración.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
create_certificate_poller = certificate_client.begin_create_certificate(
certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())
Si desea comprobar el estado de creación del certificado, puede llamar status()
a en el sondeo o get_certificate_operation con el nombre del certificado.
Recuperación de un certificado
get_certificate recupera la versión más reciente de un certificado almacenado anteriormente en el Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate("cert-name")
print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)
get_certificate_version recupera una versión específica de un certificado.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")
print(certificate.name)
print(certificate.properties.version)
Actualizar las propiedades de un certificado existente
update_certificate_properties actualiza un certificado almacenado previamente en el Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
certificate_name="cert-name", enabled=False
)
print(updated_certificate.name)
print(updated_certificate.properties.enabled)
Eliminación de un certificado
begin_delete_certificate solicitudes Key Vault eliminar un certificado, 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 certificado lo antes posible. Cuando la eliminación temporal está deshabilitada, begin_delete_certificate
es permanente.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")
deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)
Enumerar las propiedades de los certificados
list_properties_of_certificates enumera las propiedades de todos los certificados del Key Vault especificado.
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificates = certificate_client.list_properties_of_certificates()
for certificate in certificates:
# this list doesn't include versions of the certificates
print(certificate.name)
Operaciones asincrónicas
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.certificates.aio import CertificateClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = CertificateClient(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 = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
Creación asincrónica de un certificado
create_certificate crea un certificado que se almacenará en azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado. Antes de crear un certificado, se puede crear una directiva de administración para el certificado o se usará nuestra directiva predeterminada. En espera create_certificate
, devuelve el certificado creado si la creación se realiza correctamente y certificateOperation si no es así.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
create_certificate_result = await certificate_client.create_certificate(
certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)
Enumerar de forma asincrónica las propiedades de los certificados
list_properties_of_certificates enumera todas las propiedades de los certificados en el almacén del cliente:
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
print(certificate.name)
Solución de problemas
Consulte la azure-keyvault-certificates
guí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, CertificateClient genera ResourceNotFoundError:
from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
certificate_client.get_certificate("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.certificates import CertificateClient
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 = CertificateClient(
vault_url="https://my-key-vault.vault.azure.net/",
credential=credential,
logging_enable=True
)
El registro de seguimiento de red también se puede habilitar para cualquier operación única:
certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)
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 | |-------------|-------------| | hello_world.py (versión asincrónica) | create/get/update/delete certificates | | backup_restore_operations.py (versión asincrónica) | copia de seguridad y recuperación de certificados | | import_certificate.py (versión asincrónica) | importar certificados con formato PKCS#12 (PFX) y PEM en Key Vault | | list_operations.py (versión asincrónica) | enumerar certificados | | recover_purge_operations.py (versión asincrónica) | recuperar y purgar certificados | | issuers.py (versión asincrónica) | administrar emisores de certificados | | contacts.py (versión asincrónica) | administrar contactos de certificado | | parse_certificate.py (versión asincrónica) | extracción de la clave privada de un certificado |
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.
Azure SDK for Python
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de