Puntos clave
- Pon el chat, la navegación, la descarga, la subida, la reindexación y las citas en un único módulo de autorización.
- Usa la misma familia de roles para el catálogo de agentes y para las categorías de conocimiento.
- Filtra la biblioteca y limita el retrieval en el servidor antes de que la SPA renderice nada.
- Las rutas de citas y de contenido deben llamar a las mismas comprobaciones de ruta que la navegación por la biblioteca.
- Escribe reglas de implicación (manage implica use, o no) y pruébalas con tests unitarios.
- Prueba las matrices de solo general, solo especializado, admin y break-glass con nombre.
Un agente que responde a partir de documentos solo es tan fiable como los permisos de los documentos que tiene detrás.
Los equipos suelen proteger con cuidado el endpoint del chat y luego dejan la navegación por la biblioteca y la descarga de los archivos citados abiertas a cualquiera que pueda iniciar sesión. Eso no es un límite de conocimiento. Es una segunda puerta con una interfaz más bonita.
Modelo con nombre: un único módulo de permisos
- Puertas: chat, navegación, descarga, subida, reindexación y obtención de citas.
- Control: un único módulo de autorización en la API con app roles y comprobaciones de ruta.
- Catálogo + corpus: la misma familia de roles para agentes y categorías de conocimiento.
- Contrato de la UI: el frontend renderiza un payload de capacidades; no decodifica JWT.
- Fail closed: si falta el permiso sobre la ruta, la respuesta es 403, no una lista vacía muy amable mientras los bytes se sirven por otro lado.
Figura 1. El chat, la navegación, la descarga, las citas, la subida y la reindexación son puertas. El módulo de permisos es el control. Los agentes y las carpetas de conocimiento comparten una familia de roles para que un principal con acceso solo general no pueda entrar por una puerta más discreta.
Contexto y restricción
Este patrón es fácil de construir sin querer en una app de agentes. La experiencia de chat parece estricta. La biblioteca parece útil. Las citas parecen inofensivas. Juntas recrean el acceso a todo el corpus para cualquiera que simplemente esté autenticado.
Trato las rutas de conocimiento como categorías con los mismos roles que controlan los agentes. Un principal con acceso solo general nunca ve carpetas especializadas en la biblioteca, nunca descarga esos archivos y nunca los recibe inyectados en el alcance del retrieval de un turno.
Cuando un usuario abre una cita, sigue siendo una lectura de contenido. Contrólala como el chat. Si la respuesta hacía referencia a un archivo que el usuario no puede abrir, o has recuperado de más o has controlado de menos la interfaz de citas. Las dos cosas son errores de diseño.
La figura 2 es la página de Learn donde las capacidades del producto se convierten en app roles de la API. Mantén estables los nombres. Prefiere roles que viajan con el registro de la aplicación antes que un nuevo grupo anidado de Entra para cada carpeta.
Figura 2. Las capacidades del producto van como app roles en la API. Los grupos sirven para asignar. Los roles resisten mejor las reorganizaciones de grupos cuando el producto tiene que hacer cumplir capacidades. Fuente: Microsoft Learn: add app roles.
La forma del problema
Las apps de agentes empresariales suelen acabar con una biblioteca compartida: guías generales más paquetes especializados. Piensa en ellos como conjuntos de documentos separados con públicos más reducidos, como el paquete A y el paquete B. Producto quiere unos cuantos resultados honestos:
- algunos usuarios solo con el agente general y los documentos generales
- algunos usuarios con un agente especializado y su árbol de carpetas
- administradores que pueden subir y reindexar sin convertirse en modo dios por accidente
- auditores que pueden explicar por qué una persona vio un archivo
Si la navegación lista todas las carpetas y /api/content/... sirve cualquier ruta de blob a cualquier usuario autenticado, el conocimiento especializado se filtra por la interfaz aunque el selector de agentes parezca restringido. El modelo no "alucinó el acceso". Lo concedió tu API.
Diseño
1. App roles en la API del backend
Declara roles para el uso de agentes y para gestionar o navegar por categorías. Mantén estables los nombres. Prefiere roles que viajan con el registro de la aplicación antes que grupos anidados de Entra para cada carpeta. Los grupos sirven para asignar. Los roles son mejores para capacidades del producto que tienen que sobrevivir a las reorganizaciones de grupos.
2. El servidor filtra antes de que la UI tenga voto
Filtra la lista de la biblioteca en el servidor. Limita las rutas de retrieval antes de que se ejecute el modelo. Devuelve 403 en las rutas de contenido que no pasan la comprobación de ruta. La SPA nunca debería ser el único sitio donde desaparece una carpeta. La figura 3 es ese reparto de responsabilidades.
Figura 3. La SPA habla en capacidades. La API es dueña del límite. Ocultar una carpeta solo en React no es un modelo de permisos.
3. El frontend habla en capacidades, no en JWT
Expón un payload de acceso: qué puede navegar y gestionar el usuario y qué agentes tiene permitidos. Renderiza a partir de eso. Decodificar nombres de roles en React duplica la política, y se desincroniza en cuanto alguien cambia el nombre de un rol en Entra.
La figura 4 es el planteamiento de Learn para la autenticación de la SPA contra la API: el inicio de sesión es solo el envoltorio. Los permisos de conocimiento siguen necesitando comprobaciones en la API en cada ruta de contenido.
Figura 4. El inicio de sesión es solo el envoltorio. Los permisos de conocimiento siguen necesitando comprobaciones en la API. Fuente: Microsoft Learn: authentication flows and app scenarios.
4. Implicaciones explícitas
Gestionar una categoría puede implicar usar el agente correspondiente. O puede que no. Elige una opción. Escríbela. Pruébala con tests unitarios. El conocimiento tribal ("los administradores siempre tienen el agente") se convierte en un incidente de producción cuando un usuario recibe manage sin chat, o chat sin manage, y nadie se pone de acuerdo sobre qué es lo correcto.
5. Las ACL del almacenamiento refuerzan la app, no la sustituyen
Las ACL de los blobs y los app roles deberían apuntar en la misma dirección. Los usuarios llegan primero a la capa de la aplicación. Si la app es permisiva, el almacenamiento nunca tiene ocasión de salvarte en las descargas desde el navegador a través de tu propia API.
6. Prueba la matriz de principals
Entrega tests para solo general, solo especializado, varios paquetes, admin y break-glass con nombre. La figura 5 es la forma de matriz que quiero en la suite antes de añadir el siguiente paquete.
Figura 5. Solo general nunca ve carpetas especializadas. Solo especializado se queda dentro de un árbol. La subida y la reindexación de admin tienen alcance limitado, no son modo dios. El break-glass tiene nombre, es poco frecuente y se revisa.
Errores comunes
Biblioteca útil, navegación abierta. Los usuarios con sesión iniciada pueden navegar por todo porque la biblioteca es útil. Útil no es un modelo de permisos.
Agente filtrado, blob abierto. El selector de agentes tiene alcance limitado. La descarga del blob no. Los mismos bytes, otra puerta.
Alcance de retrieval enviado por el navegador. El alcance del retrieval es una lista de carpetas que llega del navegador sin límite en el servidor. Da por hecho que habrá un proxy y un usuario curioso.
ACL y roles en desacuerdo. Las ACL del almacenamiento y los app roles no coinciden. Las citas dan 403 a gente que ya ha visto la respuesta, o se abren para gente que no debería verlas.
Break-glass por defecto. El administrador break-glass es el grupo por defecto de la biblioteca. El break-glass debería tener nombre, ser poco frecuente y revisarse.
Reindexación más amplia que manage. Un botón de reindexarlo todo para alguien que solo puede gestionar una categoría revela intenciones aunque los archivos se queden donde están.
Úsalo tal cual o adáptalo
Úsalo tal cual
- La misma familia de roles para el catálogo de agentes y las categorías de conocimiento.
- La navegación no está abierta a todos los usuarios con sesión iniciada si el chat tiene alcance limitado.
- Las rutas de citas y de contenido llaman a las mismas comprobaciones de ruta que la biblioteca.
- Tests para las matrices de solo general, solo especializado y admin.
- Reglas de implicación por escrito (manage implica use, o no).
- Nombres de carpetas genéricos (carpeta A, carpeta B) en la documentación pública y en las capturas.
Adáptalo antes de usarlo
Un RBAC de conocimiento más estricto supone más trabajo en Entra y una matriz de tests más grande: solo general, solo especializado, varios paquetes, admin, break-glass. Pasarás tiempo con los responsables de identidad aclarando quién crea los roles y quién asigna los grupos.
También puedes frustrar a usuarios avanzados que quieren que "les enseñes todo y ya". Esa es una conversación de producto. No la resuelvas abriendo la navegación en silencio.
Los permisos de indexación y reindexación necesitan el mismo cuidado que la subida. Limita el botón a las categorías que el principal puede gestionar.
Referencias principales: Add app roles, Verify scopes and app roles, SPA calling a web API. Usa los nombres actuales de Microsoft Foundry cuando el host del agente haya pasado a estar bajo ese paraguas.
Un chat sin control del corpus es una demo. El control del corpus sin control de las citas es una fuga con notas al pie. Ponlos detrás del mismo control.