Cosmos.Authorization.Azure 3.1.0

Cosmos.Authorization.Azure

Integración de Cosmos.Authorization con Azure Key Vault, para los servicios del ecosistema que corren en Azure. Lee la API key del proveedor de FGA de un secreto del vault y registra el puerto IGrantedResourcesProvider del paquete base.

El paquete base no conoce ningún secret store a propósito; esta es la pieza que lo conecta con el de Azure. Un servicio que no use Key Vault instala solo el base y le pasa la key como la consiga.

De qué vault se lee

La API key de FGA es una credencial de la organización, no del servicio: la misma la usan todos los servicios que hablen con FGA. Por eso vive una sola vez, en el vault de valores compartidos de la plataforma —uno por ambiente—, y no copiada en el vault de cada aplicación.

Cada servicio sigue teniendo su propio vault para sus secretos propios. El URI que recibe este paquete es el del vault de plataforma, no el del servicio: pasarle el SecretClient que el servicio ya usa para sus cadenas de conexión apunta al vault equivocado y el secreto no aparece.

Uso

// Contra el vault de plataforma, con la identidad administrada del servicio:
await builder.Services.AgregarAutorizacionFgaDesdeKeyVaultAsync(
    new Uri(builder.Configuration["Fga:VaultUri"]!), "WORKOS-API-KEY");

// O con un SecretClient armado para ese vault (si querés controlar credencial y reintentos):
await builder.Services.AgregarAutorizacionFgaDesdeKeyVaultAsync(secretClient, "WORKOS-API-KEY");

Alternativa sin este paquete: referencias de Key Vault

Si el servicio corre en Azure Functions, App Service o Logic Apps, la plataforma puede resolver el secreto sola y este paquete sobra. Terraform siembra el app setting con una referencia:

Fga__ApiKey = @Microsoft.KeyVault(SecretUri=https://kv-plataforma-dev.vault.azure.net/secrets/WORKOS-API-KEY/)

y el servicio usa solo el paquete base:

builder.Services.AgregarAutorizacionFga(builder.Configuration["Fga:ApiKey"]!);

Es el camino más simple donde aplica: ningún servicio conoce URIs, no hay SDK de por medio, y un administrador con control total de la Function App sigue sin poder ver el secreto. Este paquete es para los hosts donde esa comodidad no existe —un worker en Container Apps o AKS— o cuando se quiere que la aplicación controle la lectura.

Después se consume el puerto del paquete base, sin saber de Key Vault ni del proveedor de FGA:

var puede = await provider.CheckAsync(
    membershipId, new ResourceByExternalId(ResourceType.ResourceGroup, "ADPRO"), "resource-group:read", ct);

Cuándo se lee el secreto

Al componer el contenedor, una sola vez. Por eso el método es asíncrono: el registro del paquete base recibe la API key ya resuelta, así que hay que traerla antes.

Las dos consecuencias, asumidas:

• Si el vault no responde al arrancar, el servicio no arranca. Es un fallo ruidoso y temprano, no una invocación que falla en producción con el usuario esperando.
• Rotar la API key implica reiniciar el servicio.

Requisitos

La identidad administrada del servicio necesita Key Vault Secrets User sobre el vault de plataforma, con scope al secreto y no al vault entero: así el servicio lee la API key de FGA y nada más de lo que ahí viva. Es el escenario que Azure documenta como la excepción legítima para asignar roles a nivel de secreto individual — un secreto compartido entre varias aplicaciones.

La asignación funciona entre suscripciones: el rol se define en Entra y su scope es el id ARM del recurso, así que la identidad de un servicio de un ambiente puede tener permiso sobre un vault que vive en otra suscripción.