Handle secret versioning and rotation (Key Vault)

Cada vez que guardas un secreto con el mismo nombre en Key Vault, el vault crea una nueva versión, en vez de sobreescribir la existente. Esto es fundamental para soportar credential rotation porque permite que las credenciales nuevas y viejas coexistan durante el período de transición.

Understand how Key Vault versions secrets

Cada llamada a set_secret() con el mismo secret name crea una nueva version y le asigna un GUID unico. Llamar a get_secret() sin version param siempre devuelve la ultima version. También puedes llamar a get_secret() con una version especifica. Las versiones previas se mantienen accesibles hasta que las borras o desactivas de manera explicita.

# Code fragment - focus on creating a new version and retrieving by version ID
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()
client = SecretClient(
    vault_url="https://kv-ragpipeline-prod.vault.azure.net/",
    credential=credential
)

# Create initial version
initial = client.set_secret("cosmosdb-connection-string", "AccountEndpoint=https://...")
print(f"Version 1: {initial.properties.version}")

# Create new version with updated value
updated = client.set_secret("cosmosdb-connection-string", "AccountEndpoint=https://new...")
print(f"Version 2: {updated.properties.version}")

# Retrieve latest version (returns version 2)
latest = client.get_secret("cosmosdb-connection-string")

# Retrieve specific version (returns version 1)
specific = client.get_secret("cosmosdb-connection-string",
                              version=initial.properties.version)

Como por defecto get_secret() obtiene la ultima version, tu app no tiene que saber que version usa. De esta manera con guardar una nueva version, esta ya se propaga por la app.

Los IDs son utiles para auditorias.

List and inspect secret versions

El metodo list_properties_of_secret_versions() enumera todas las versiones de un secreto especifico. Cada version incluye ID, fechas y status. Se usa para auditar rotacion.

# Code fragment - focus on listing and inspecting secret versions
versions = client.list_properties_of_secret_versions("cosmosdb-connection-string")

for version in versions:
    print(f"Version: {version.version}")
    print(f"  Created: {version.created_on}")
    print(f"  Enabled: {version.enabled}")
    print(f"  Expires: {version.expires_on}")

Tras una rotacion podemos considerar desactivar versiones previas para forzar a que la app use la nueva version. Esto lo podemos hacer llamando a update_secret_properties() con enabled=False, lo cual previene que la versión se obtenga.

Choose rotation strategy

Manual rotation

Método más simple. Creamos una nueva version en Key Vault y reiniciamos la app.

Es util para cambios infrecuentes, pero hay una ventana entre que actualizamos el secreto y la app sigue usando el viejo.

Automated Rotation with Event Grid

Key Vault se integra con Azure Event Grid para emitir eventos cuando los secretos se aproximan a su expiration date.

El evento SecretNearExpiry se lanza 30 dias antes de que expire.
El evento SecretExpired se lanza cuando ya ha expirado.

Una Azure Function u otro handler se encarga de escuchar esos eventos, genera una nueva credencial, guarda el nuevo valor y la nueva version en el Key Vault.

Esto lo automatiza enteramente el lifecycle. Resumen:

  1. Key Vault emite SecretNearExpiry event
  2. Event Grid entrega el evento al handler registrado
  3. Una Azure Function recibe el evento
  4. La function genera una nueva credencial para el target service
  5. La function guarda la nueva credencial como una nueva secret verison en el key vault

Dual-credential rotation

Para servicios que soportan dos keys activas de manera simultanea, como Storage accounts y CosmosDB.

  1. Generamos una nueva key secundaria en el target service
  2. Guardamos la nueva key como una nueva secret version en el Key Vault
  3. Esperamos a que todas las aplicaciones pillen el nuevo valor
  4. Regeneramos la vieja primary key en el target service

De esta manera garantizamos que al menos hay una credencial valida que exista siempre.

Implement zero-downtime rotation in app code

Independientemente de la estrategia seleccionada, el codigo de la app debe encargarse de la transicion entre secreto viejo y nuevo.

El patron recomendado atrapa fallos de downstream services, hace refetch del secreto desde la Key Vault y reintenta la operacion con la nueva credencial. De esta manera evitamos restarts y soportamos rotacion.

# Code fragment - focus on retry-on-auth-failure pattern for rotation
from azure.core.exceptions import HttpResponseError

def call_downstream_service(client, secret_name, max_retries=1):
    """Retrieve secret and call service, refreshing on auth failure."""
    secret_value = client.get_secret(secret_name).value

    for attempt in range(max_retries + 1):
        try:
            # Use secret_value to authenticate with downstream service
            result = connect_to_service(secret_value)
            return result
        except AuthenticationError:
            if attempt < max_retries:
                # Credential might be rotated - refresh from Key Vault
                secret_value = client.get_secret(secret_name).value
            else:
                raise

Este patron limita la performance del impacto de rotacion cuando la primera auth falla.

Set expiration dates on secrets

IMPORTANTE

La property expires_on define la expiration date. Los secretos expirados todavia existen en el key vault y se pueden obtener a través de get_secret(). La expiracion es informativo, más que un hard limit. En si misma es para indicar que se deberia de cambiar.

/IMPORTANTE