Acceso de agentes: ¿cómo defines los permisos de un agente de forma segura?

La mayoría de las demos de apps de IA meten tres preguntas distintas en un solo botón de inicio de sesión:

1. ¿Puede esta persona abrir el shell?
2. ¿Con qué agentes puede hablar?
3. ¿Qué conocimiento puede ver, descargar o usar como base para las respuestas?

En una app web de agentes real, dentro de una empresa, son tres planos de control distintos. Si los tratas como uno solo, acabas con un agujero de seguridad o con una pesadilla de soporte.

El acceso a la app responde a la autenticación y la presencia. El acceso a los agentes responde a la autorización y el alcance.

Figura 1. Puerta de entrada, catálogo, corpus. El acceso a la app es presencia. El acceso a agentes es alcance. El conocimiento no es una sugerencia blanda en la UI.

Contexto y restricción

El patrón vale para cualquier puerta de entrada a agentes. La superficie de chat parece tan simple como una app de consumo. El modelo de permisos tiene que comportarse igualmente como un sistema empresarial.

Si el chat está bloqueado pero la descarga de contenidos está abierta a cualquier usuario autenticado, no tienes una frontera de conocimiento. Tienes una sugerencia en la UI. La figura 1 es la separación que defendería en una revisión de arquitectura. La figura 2 es el recordatorio de Learn de que un token de la SPA no es el final de la autorización.

Figura 2. Una SPA llama a una API web. La autenticación te da un token, pero la autorización tiene que ocurrir igualmente en la API. Fuente: Microsoft Learn: flujos de autenticación y escenarios de aplicación.

Diseño

1. Un solo control de inicio de sesión para el shell

Mantén una asignación clara de "quién puede usar la app" (a menudo un único grupo de inicio de sesión en la SPA). Los grupos dinámicos están bien cuando la regla aplica a toda la organización. No sobrecargues ese grupo con todos los permisos restringidos. Su trabajo es la puerta de entrada.

2. Roles de aplicación en la API de backend para lo que puedes hacer

Asigna roles a capacidades, no a pantallas:

• roles que significan "puede usar el agente A"
• roles que significan "puede gestionar la categoría de conocimiento A"
• un administrador de emergencia (break-glass) que implica ambos cuando eso es intencionado

Aplícalo en la API. Filtra GET /api/agents para que el catálogo que muestra la UI ya sea honesto. Devuelve 403 en el chat si alguien manipula los ID de agente. No te limites a "ocultar el botón" y llamarlo seguridad. La figura 3 es la superficie del producto donde se declaran esos roles. La figura 4 es el reparto de responsabilidades que mantiene el control en la API.

Figura 3. Declara los roles de aplicación en el registro de la API y luego asígnalos a usuarios o grupos. Fuente: Microsoft Learn: agregar roles de aplicación.

Figura 4. Un catálogo honesto. La API filtra. La SPA muestra. Ocultar solo en la UI con una API abierta es teatro de seguridad.

3. El frontend habla de capacidades, no de JWT

La SPA debería preguntar a la API "¿qué puedo gestionar o navegar?" y mostrar eso. Decodificar roles en el navegador duplica la política y las copias acaban divergiendo. Un solo payload de acceso es mejor que tres copias de constantes de roles en React.

4. Gestionar puede implicar usar, de forma deliberada

Si alguien puede gestionar una categoría de conocimiento restringida, normalmente necesita el agente correspondiente. Codifícalo como una implicación explícita en un único servicio de autorización, no como conocimiento tribal. Los usuarios que solo tienen roles base nunca deberían ver categorías restringidas al navegar, al descargar ni en el alcance de la recuperación.

5. Las citas son una vía de acceso

Los usuarios abrirán el documento que citó el modelo. Si ese endpoint de blobs ignora las reglas de ruta de la navegación, tu historia de "conocimiento restringido" es puro teatro. Protege la lectura de contenidos igual que proteges el chat. La figura 5 es el control compartido.

Figura 5. El chat, la navegación y los blobs citados comparten las mismas reglas de permisos. Navegación abierta con el chat cerrado son los mismos datos por otra puerta.

Errores comunes

Autenticado = de confianza. Todo el que puede iniciar sesión puede abrir la app, así que todos ven todos los agentes y todas las carpetas. Esa es una postura de demo, no de producción.

Grupos en todas partes, roles en ninguna. Los grupos de Entra anidados para cada categoría parecen flexibles hasta que las consultas a Graph, el tamaño del token y el "¿por qué no se actualiza mi acceso?" dominan el backlog. Usa preferentemente roles de aplicación en la API para las capacidades del producto, y grupos para asignar esos roles.

Filtrar solo en la UI. El selector de agentes oculta opciones, pero la API sigue aceptando cualquier ID de agente. Cuenta con un usuario curioso y un proxy. La figura 4 hace visible ese fallo.

Navegación abierta, chat cerrado. Bloqueaste un agente restringido pero dejaste la lista y la descarga abiertas a todos los usuarios autenticados. Los mismos datos, otra puerta. La figura 5 es el aviso.

Gestionar sin recuperar (o al revés) sin decirlo. Decide si "puede gestionar esta categoría" implica "puede usar el agente que la lee". Después, escríbelo y pruébalo.

Úsalo tal cual o adáptalo

Úsalo tal cual

• Grupo de inicio de sesión = solo el shell.
• Roles de aplicación de la API de backend = agentes + categorías de conocimiento.
• Un único módulo de autorización para la lista de agentes, el chat, la navegación y los contenidos.
• La SPA consume endpoints de capacidades, sin interpretar roles en el navegador.
• Pruebas automatizadas para "un usuario con solo roles base no puede navegar ni recuperar rutas restringidas".
• Reglas de implicación explícitas (gestionar puede implicar usar), documentadas y con pruebas unitarias.

Adáptalo antes de usarlo

Unos roles más estrictos significan más trabajo en Entra y más matrices de pruebas (solo roles base, solo categoría A, administrador, break-glass). Tendrás que negociar con los responsables de identidad quién crea los roles de aplicación y quién asigna los grupos.

On-behalf-of y los tokens para varios recursos añaden piezas móviles. Un consentimiento incompleto aparece como fallos "aleatorios" de la plataforma que parecen errores del modelo.

Los controles de red (private endpoints, listas de IP permitidas) protegen el plano, pero no sustituyen la autorización por agente. Las dos capas importan, porque resuelven amenazas distintas.

Referencias principales: Microsoft Learn sobre roles de aplicación de Entra, SPA que llama a una API web, y la verificación de scopes y roles de aplicación. Usa los nombres actuales de Microsoft Foundry cuando tu puerta de entrada a agentes esté bajo ese paraguas.

Puerta de entrada. Catálogo. Corpus. Tres preguntas. Tres respuestas.