Azure Key Vault para IA: objetos, SDK, rotación y caché

radio_button_uncheckedshort_text1. Escenario y objetivos de aprendizaje

Una canalización RAG crea incrustaciones con Azure OpenAI Service, lee vectores de Azure Cosmos DB y escribe documentos procesados en Azure Blob Storage. Desarrollo, preproducción y producción usan credenciales distintas. Guardar cadenas de conexión y claves de API en archivos incorporados al repositorio expone los valores, mientras que rotar mediante una nueva implementación dificulta responder a un compromiso en cuatro horas sin interrupción.

• Elegir el objeto correcto de Key Vault para un secreto, una clave criptográfica o un certificado.
• Autenticar con Microsoft Entra ID y autorizar con RBAC de Azure y privilegio mínimo.
• Recuperar valores y metadatos con clientes síncronos o asíncronos del SDK de Python.
• Usar versiones, rotación, reintentos e invalidación de caché para transiciones seguras.
• Reducir llamadas al almacén sin prolongar una credencial comprometida.

Resumen rápido

El diseño sustituye credenciales en código por un almacén central auditado e incorpora rotación, transición y vigencia de caché a la arquitectura.

radio_button_uncheckedshort_text2. Capacidades, niveles e interfaces de Key Vault

Azure Key Vault almacena secretos, claves y certificados y cifra los datos en reposo. Microsoft Entra ID autentica y RBAC de Azure autoriza. Las aplicaciones pueden usar API REST, CLI de Azure, portal o SDK para Python, .NET, Java, JavaScript y Go.

Resumen rápido

Los almacenes guardan tres objetos; Standard y Premium difieren sobre todo en la protección de claves, mientras HSM administrado es independiente y solo para claves.

radio_button_uncheckedshort_text3. Secretos: valores opacos con metadatos

Un secreto es una cadena opaca de hasta 25 KB para claves de API, contraseñas, tokens, cadenas de conexión, claves SSH privadas o credenciales compuestas pequeñas. El servicio no interpreta el valor. content_type, propiedades de versión y etiquetas describen formato, propietario, entorno y rotación.

No convierta Key Vault en base de configuración o contenido. Los puntos de conexión, nombres de servicio y marcas de características pertenecen a Configuración de la aplicación; las cargas grandes, a Azure Storage con cifrado. Las etiquetas son visibles para quien lista metadatos y nunca deben contener credenciales.

Resumen rápido

Los secretos son cadenas sensibles pequeñas; los metadatos los describen, pero la configuración normal y el contenido grande se guardan en otros servicios.

radio_button_uncheckedshort_text4. Claves: criptografía sin exportar el material

Las claves realizan cifrado, descifrado, firma, verificación y encapsulado. Las operaciones del servidor mantienen la clave privada dentro del límite del servicio. RSA por software admite 2048, 3072 y 4096 bits; EC admite P-256, P-384, P-521 y secp256k1/P-256K. Premium agrega variantes HSM. Las claves simétricas oct-HSM siguen en versión preliminar.

Elija una clave, no un secreto, cuando otro servicio necesite una clave administrada por el cliente, cuando la aplicación deba firmar o encapsular remotamente o cuando la directiva exija material no exportable.

Resumen rápido

Una clave ofrece operaciones criptográficas controladas sin exponer su material privado protegido.

radio_button_uncheckedshort_text5. Certificados y objetos de clave y secreto vinculados

Un certificado de Key Vault administra X.509 y su clave privada, incluida emisión, renovación, revocación e integración con autoridades para HTTPS o TLS mutuo. Crear o importar un certificado también crea una clave y una representación de secreto, por lo que leer la clave privada exige un rol cuidadosamente elegido.

Use el objeto certificado para credenciales TLS con ciclo de vida en lugar de almacenar un paquete como secreto arbitrario. Así conserva directiva, emisor, renovación y versiones.

Resumen rápido

Los certificados agregan ciclo de vida X.509 y crean objetos relacionados; el acceso a la clave privada debe restringirse.

radio_button_uncheckedshort_text6. Límites del almacén, nombres y etiquetas

Un límite práctico es un almacén por aplicación, región y entorno. Separar desarrollo, preproducción y producción reduce el radio de impacto y simplifica roles. Una identidad comprometida en desarrollo no debe descubrir credenciales de producción.

• El nombre del almacén es globalmente único, tiene 3–24 caracteres, empieza con letra, termina con letra o dígito, acepta alfanuméricos y guiones y prohíbe guiones consecutivos.
• Use nombres descriptivos como cosmosdb-connection-string y openai-api-key.
• Cada secreto admite hasta 15 etiquetas; los límites actuales son 512 caracteres en nombre y 256 en valor.
• Entorno, equipo, aplicación, rotación y clasificación son etiquetas útiles; el valor secreto nunca lo es.

Resumen rápido

Almacenes separados crean límites de seguridad; nombres coherentes y etiquetas no sensibles hacen operable el inventario.

radio_button_uncheckedshort_text7. RBAC de Azure, plano de control y plano de datos

El plano de control crea y configura el recurso mediante Azure Resource Manager. El plano de datos lee y cambia objetos en el punto de conexión del almacén. Key Vault Contributor administra el recurso, pero no lee valores del plano de datos.

Prefiera RBAC de Azure a las directivas heredadas, asigne en el ámbito del almacén, use Privileged Identity Management para administración just-in-time y evite concesiones amplias. Las versiones actuales de la API establecen RBAC como modelo predeterminado en almacenes nuevos.

Resumen rápido

La identidad autentica; el rol del plano de datos autoriza operaciones, y Contributor del plano de control no lee secretos.

radio_button_uncheckedshort_text8. Identidad administrada y cadena actual de credenciales

Una identidad administrada permite autenticar Azure Container Apps, AKS, Servicio de Aplicaciones, Azure Functions y otros recursos sin secreto de cliente. Asigne Key Vault Secrets User si la aplicación solo lee en tiempo de ejecución.

DefaultAzureCredential permite el mismo código local y en Azure. La cadena actual de Python puede intentar Environment, Workload Identity, Managed Identity, Shared Token Cache, Visual Studio Code, CLI de Azure, Azure PowerShell, Azure Developer CLI, navegador interactivo opcional y broker. La cadena cambia entre versiones. En producción, Microsoft recomienda comprender el requisito y considerar ManagedIdentityCredential para reducir ambigüedad y sobrecarga.

Resumen rápido

La identidad administrada elimina credenciales almacenadas; DefaultAzureCredential une entornos, pero la cadena de producción debe ser explícita y observable.

radio_button_uncheckedshort_text9. Eliminación temporal, protección de purga y recuperación

La eliminación temporal está habilitada de forma predeterminada y no puede desactivarse después. Los almacenes y objetos permanecen recuperables durante 7–90 días, configurados al crear el almacén, con 90 como valor predeterminado. El período no cambia después.

La protección de purga es opcional pero muy recomendada en producción. Cuando está habilitada, ni un principal privilegiado elimina permanentemente antes del fin de retención. Recuperar un almacén no restaura asignaciones RBAC ni suscripciones de Cuadrícula de Eventos; el runbook debe recrearlas.

Resumen rápido

La eliminación temporal crea la ventana, la protección de purga la impone y la recuperación aún requiere reconstruir roles y suscripciones.

radio_button_uncheckedshort_text10. Instalar el SDK de Python y crear SecretClient

azure-keyvault-secrets proporciona SecretClient y azure-identity las credenciales. La URL es https://<vault-name>.vault.azure.net/. Cree credencial y cliente una vez y reutilícelos para conservar cachés de tokens y conexiones HTTP.

pip install azure-identity azure-keyvault-secrets

az keyvault show --name <vault-name> --query properties.vaultUri

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()
client = SecretClient(
    vault_url="https://<vault-name>.vault.azure.net/",
    credential=credential,
)

client.set_secret(
    "openai-api-key",
    "<secret-value>",
    content_type="text/plain",
    tags={"environment": "production", "owner": "ai-platform"},
)

Resumen rápido

Instale identidad y secretos, cree un SecretClient reutilizable y sin contraseña y nunca registre el valor almacenado.

radio_button_uncheckedshort_text11. Recuperar valores, metadatos e inventarios con seguridad

get_secret(nombre) sin versión devuelve la versión habilitada más reciente. KeyVaultSecret contiene value y propiedades de versión, creación, expiración, estado, tipo y etiquetas. Registre solo nombre y versión.

list_properties_of_secrets() enumera metadatos sin recuperar valores. Es útil para inventario y validación al iniciar, antes de aceptar tráfico.

from azure.core.exceptions import (
    HttpResponseError, ResourceNotFoundError, ServiceRequestError
)

def read_secret(client: SecretClient, name: str) -> str:
    try:
        secret = client.get_secret(name)  # latest enabled version
        print(f"Loaded {name}, version={secret.properties.version}")
        return secret.value
    except ResourceNotFoundError as exc:
        raise RuntimeError(f"Missing secret: {name}") from exc
    except HttpResponseError as exc:
        raise RuntimeError(f"Key Vault rejected {name}: {exc.status_code}") from exc
    except ServiceRequestError as exc:
        raise RuntimeError("Network path to Key Vault failed") from exc

for props in client.list_properties_of_secrets():
    print(props.name, props.enabled, props.content_type, props.tags)

Resumen rápido

get_secret lee un valor; la lista de propiedades descubre y valida objetos sin revelar su contenido.

radio_button_uncheckedshort_text12. Excepciones, acceso asíncrono y vida del cliente

ResourceNotFoundError suele indicar nombre o almacén incorrecto. HttpResponseError cubre autenticación, autorización, limitación y otras respuestas. ServiceRequestError indica transporte, DNS, tiempo de espera o conectividad. Clasifique antes de reintentar para no amplificar fallos permanentes.

El cliente aio evita bloquear el bucle de eventos de FastAPI o aiohttp. Cliente y credencial son administradores de contexto asíncronos. En un servicio web, créelos al iniciar, reutilice entre solicitudes y ciérrelos al detener.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

async def load_runtime_secret() -> str:
    async with DefaultAzureCredential() as credential:
        async with SecretClient(
            vault_url="https://<vault-name>.vault.azure.net/",
            credential=credential,
        ) as client:
            secret = await client.get_secret("openai-api-key")
            return secret.value

# In a web service, create and reuse one client during app startup,
# then close the client and credential during app shutdown.

Resumen rápido

Diferencie ausencia, rechazo y transporte; las aplicaciones asíncronas deben reutilizar un cliente y cerrarlo correctamente.

radio_button_uncheckedshort_text13. Versiones, expiración, auditoría y reversión

Cada set_secret con el mismo nombre crea un identificador inmutable, sin sobrescribir el anterior. La lectura sin versión devuelve la habilitada más reciente; una lectura versionada recupera el valor histórico exacto. La lista de versiones muestra creación, expiración y estado para auditoría y rollback.

expires_on es una señal de ciclo de vida, no un bloqueo rígido: el secreto expirado aún puede recuperarse. Combine expiración, supervisión y automatización, y deshabilite la versión antigua solo cuando todas las instancias hayan migrado.

from datetime import datetime, timedelta, timezone

created = client.set_secret(
    "cosmosdb-connection-string",
    "<new-value>",
    expires_on=datetime.now(timezone.utc) + timedelta(days=90),
    tags={"rotation-policy": "90-days", "service": "cosmos-db"},
)

latest = client.get_secret("cosmosdb-connection-string")
exact = client.get_secret("cosmosdb-connection-string", created.properties.version)

for version in client.list_properties_of_secret_versions("cosmosdb-connection-string"):
    print(version.version, version.created_on, version.expires_on, version.enabled)

# Disable the previous version only after every instance has moved.
client.update_secret_properties(
    "cosmosdb-connection-string", "<old-version>", enabled=False
)

Resumen rápido

Las versiones permiten coexistencia; la expiración inicia operaciones y la deshabilitación termina el uso tras implementación o ventana de reversión.

radio_button_uncheckedshort_text14. Rotación manual, con Cuadrícula de Eventos y credencial doble

1. Cree la credencial en el servicio destino.
2. Guárdela como nueva versión.
3. Invalide cachés o notifique instancias.
4. Confirme la adopción.
5. Deshabilite o regenere la anterior y guarde evidencias.

Microsoft.KeyVault.SecretNewVersionCreated, SecretNearExpiry y SecretExpired son eventos actuales. La expiración o notificación no rota por sí sola una credencial externa; el controlador coordina servicio y almacén.

Resumen rápido

La capacidad del servicio destino define la estrategia; crear una versión es solo una etapa de la rotación completa.

radio_button_uncheckedshort_text15. Transición sin interrupción y actualización tras fallo

Durante la rotación, distintas instancias pueden conservar valores de caché diferentes. La aplicación llama con la credencial actual, interpreta un rechazo de autenticación como posible rotación, recupera la versión habilitada más reciente y reintenta una sola vez. Así evita bucles y limita la lectura adicional al período de transición.

from azure.core.exceptions import HttpResponseError

def call_with_rotation_refresh(client, cache, name, downstream_call):
    value = cache.get(name)
    try:
        return downstream_call(value)
    except AuthenticationError:
        # One refresh and one retry: do not create an infinite loop.
        fresh = client.get_secret(name).value
        cache.put(name, fresh)
        return downstream_call(fresh)

Resumen rápido

Mantenga versiones válidas durante el despliegue, actualice una vez ante fallo, observe convergencia y revoque al final.

radio_button_uncheckedshort_text16. Caché temporal, ámbito y presupuesto de vigencia

Una llamada remota tarda decenas de milisegundos y la memoria local microsegundos. Leer Key Vault en cada solicitud aumenta latencia y puede alcanzar límites. Un TTL con reloj monotónico evita que ajustes del reloj alteren la edad.

import time

class SecretCache:
    def __init__(self, client: SecretClient, ttl_seconds: int = 900):
        self.client = client
        self.ttl = ttl_seconds
        self.values: dict[str, tuple[str, float]] = {}

    def get(self, name: str) -> str:
        value = self.values.get(name)
        now = time.monotonic()
        if value and now - value[1] < self.ttl:
            return value[0]
        secret = self.client.get_secret(name)
        self.values[name] = (secret.value, now)
        return secret.value

    def invalidate(self, name: str) -> None:
        self.values.pop(name, None)

Defina TTL según obsolescencia admitida: 5–15 minutos más Cuadrícula de Eventos para rotación frecuente, 30–60 minutos para cambios mensuales o trimestrales y precarga con actualización cada horas para valores estáticos. Ante compromiso, invalide o reinicie inmediatamente.

Resumen rápido

Empiece con memoria, derive TTL de la vigencia permitida y asocie un mecanismo explícito de actualización.

radio_button_uncheckedshort_text17. Invalidación, límites, backoff y laboratorio guiado

Suscríbase a Microsoft.KeyVault.SecretNewVersionCreated y enrute mediante webhook, Bus de Servicio o Azure Functions. Valide origen y tipo y quite solo el secreto indicado. Conserve TTL como respaldo.

Los límites actuales por almacén, región y 10 segundos permiten 4000 transacciones restantes; CREATE secret, IMPORT certificate e IMPORT key comparten 300 escrituras. La suscripción agrega cinco veces el límite. Ante 429, use backoff exponencial con jitter. Respuestas persistentes indican falta de caché, TTL corto o estampida de despliegue; escalone inicios y reutilice clientes.

Laboratorio Flask guiado

1. Cree o elija un almacén con RBAC, eliminación temporal y protección de purga; use Secrets Officer para desarrollo y Secrets User para la aplicación.
2. Descargue o clone un proyecto inicial Flask, ábralo en Visual Studio Code, cree un entorno Python 3.12+, instale azure-identity, azure-keyvault-secrets y Flask e inicie sesión con la versión más reciente de CLI de Azure y az login.
3. Complete la aplicación inicial con SecretClient, guarde secretos con tipo y etiquetas e imprima solo nombres, versiones y metadatos.
4. Ejecute las operaciones: liste propiedades, lea un valor, cree otra versión y confirme la lectura sin versión.
5. Agregue caché de 15 minutos, lea repetidamente, rote, invalide y confirme el valor nuevo.
6. Pruebe las tres excepciones y registros de 429 sin imprimir secretos.
7. Elimine recursos y asignaciones del laboratorio.

Resumen rápido

Los eventos aceleran la vigencia, TTL cubre notificaciones perdidas, los límites favorecen caché y el laboratorio valida el ciclo completo.

radio_button_uncheckedshort_text18. Revisión de evaluación, lista final y referencias

Lista de comprobación final

• Separe almacén por aplicación, región y entorno.
• Elija el objeto por sus operaciones.
• Use identidad administrada y RBAC mínimo.
• Habilite protección de purga y documente recuperación.
• Reutilice SecretClient y nunca registre valores.
• Trate destino, versión, caché y revocación como un flujo.
• Use Cuadrícula de Eventos, TTL y una actualización tras fallo.
• Supervise acceso, expiración, 429, finalización y deshabilitación.

1. ¿Qué es Azure Key Vault?
2. RBAC de Azure para Key Vault
3. Eliminación temporal de Key Vault
4. Inicio rápido del cliente Python
5. Cadena DefaultAzureCredential
6. Eventos de Key Vault
7. Protección de secretos
8. Límites de Key Vault
9. Guía de limitación

Resumen rápido

La solución completa alinea objeto, identidad, RBAC, recuperación, SDK, versiones, rotación, caché, límites y supervisión en un diseño auditable.