Modelo de permisos para agentes de IA: identidad de usuario, permisos de herramientas, auditoría y aislamiento de secretos

Un equipo entrega el mismo token de administrador a un agente pensando: “total, es un sistema interno”. Luego el usuario A envía una consulta y el agente, usando identidad de administrador, lee el registro CRM del usuario B. Un modelo de permisos roto es más peligroso que no tener agente.

No es un caso hipotético. MCP Security Best Practices marca token passthrough como anti-pattern: evita controles de seguridad, rompe el audit trail y cruza trust boundaries. OWASP AI Agent Security Cheat Sheet también incluye el abuso de herramientas y la escalada de privilegios entre los riesgos principales.

El problema se reduce a tres preguntas: a quién representa el agente, con qué permiso llama y a qué puede acceder. A continuación tienes el plano completo de ingeniería: tabla de mapeo de identidad, campos de permisos de herramientas, pasos clave del Secret Vault, schema de audit log con reglas de enmascarado, tabla de decisión, checklist de diagnóstico y pasos de implementación.

Mapeo de identidad: ¿a quién representa el agente?

Cuando un agente llama a una herramienta, los logs y el sistema de permisos deben responder primero una pregunta: quién inició la llamada y en nombre de quién se ejecuta la operación. Esas dos entidades pueden coincidir o no. Confundirlas provoca descontrol de permisos y auditorías imposibles de reconstruir.

Tabla de tipos de identidad

Tipo	actor	subject	Escenario	Límite de permisos
user identity	Usuario A	Usuario A	Interacción directa del usuario	Hereda los permisos del usuario
service account	system_bot	null	Tareas de fondo, jobs programados	Permisos de sistema, independientes del usuario
delegated token	workflow_123	Usuario A	Workflow automatizado autorizado por el usuario	Scope del workflow, limitado por la autorización del usuario
tenant context	agent_456	tenant_B	Sistemas multi-tenant	Aislamiento de tenant, sin acceso entre tenants

Definición de campos: actor es la entidad que inicia la llamada, ya sea usuario, agente, workflow o sistema. El log registra su ID. subject es la entidad representada, un usuario o null. En la interacción directa, actor=subject. Cuando una cuenta de sistema ejecuta una tarea de fondo, subject=null. delegatedBy identifica qué usuario autorizó el workflow. tenantId identifica el tenant y permite aislar datos en sistemas multi-tenant.

Según la especificación MCP Authorization, los MCP servers deben verificar que el access token se emitió para ellos como intended audience. El campo audience del token debe apuntar al identificador de recurso del MCP server. El token no debe ir en el URI query string, porque los URI pueden aparecer en logs, historial del navegador y cachés de proxy.

OWASP Access Control Cheat Sheet insiste en deny by default, least privilege y comprobación en cada request. El mapeo de identidad es el primer paso de esa comprobación: actor, subject y tenantId determinan la decisión de permisos posterior.

Permisos de herramientas: ¿qué puede llamar el agente?

Registrar una herramienta no es solo definir name, description e input_schema. La referencia de herramientas del OpenAI Agents SDK incluye campos para permisos y control de ejecución.

Tabla de decisión de permisos de herramientas

Control de permiso	Escenario	Implementación	Riesgo
per-tool permission	Cada herramienta se autoriza por separado	Definir permission_level al registrar la herramienta, como read/write/admin	La configuración se vuelve más compleja y hay que mantener una matriz
scope minimization	Mínimo privilegio progresivo	Scope inicial solo con operaciones de bajo riesgo; privilegios altos mediante scope challenge	La gestión de scopes cuesta más y puede requerir ajustes dinámicos
whitelist	Lista permitida de herramientas	Permitir solo combinaciones concretas, como read_customer + summarize	Costo de mantenimiento y posible pérdida de flexibilidad
approval	Aprobación humana	Las herramientas needs_approval=true se pausan antes de ejecutar y esperan aprobación	La aprobación añade latencia y afecta la experiencia del usuario

Los campos de herramientas del OpenAI Agents SDK incluyen is_enabled para controlar la activación en tiempo de ejecución. Según el rol de usuario, tenant o workflow context, una herramienta puede deshabilitarse dinámicamente. needs_approval marca si hace falta aprobación humana. Incluso después de aprobar, se ejecuta tool_input_guardrails. tool_input_guardrails valida entradas, como detección de PII o límites de parámetros. tool_output_guardrails valida salidas, por ejemplo mediante filtrado de contenido.

MCP Security Best Practices recomienda mínimo privilegio progresivo para scope minimization: el scope inicial solo debe incluir operaciones de descubrimiento o lectura de bajo riesgo, como read:metadata y list:resources. Las operaciones de alto privilegio se añaden mediante un scope challenge preciso. Hay que evitar wildcard/full-access scopes.

OWASP AI Agent Security Cheat Sheet recomienda per-tool permission scoping: usar tool sets distintos para diferentes trust levels, exigir autorización explícita para operaciones sensibles y aplicar fail closed cuando falle la comprobación.

Aislamiento de secretos: ¿cómo obtiene credenciales el agente?

Un agente no debería tener API keys de larga duración en texto plano. OWASP Secrets Management Cheat Sheet recomienda centralizar y estandarizar la gestión de secretos. El sistema de secretos también debe soportar Authentication, Authorization, Accounting y lifecycle.

Tabla de patrones de acceso a secretos

Patrón	Riesgo	Escenario	Ejemplo
Posesión directa, como .env en claro	Alto riesgo de fuga, sin trazabilidad ni revocación	No recomendado	API key hardcodeada
Variables de entorno	Riesgo de fuga en logs, trazabilidad y revocación aún débiles	Despliegue en una sola máquina	process.env.API_KEY
secret vault	Gestión centralizada, almacenamiento cifrado, audit trail, revocación	Producción	AWS Secrets Manager, HashiCorp Vault
secret reference	El agente mantiene una reference y la cambia por un token corto durante la ejecución	Multi-tenant y escenarios de alta seguridad	vault.get(secretRef)

El ciclo de vida de un secreto tiene cuatro etapas: creation debe generar tokens cortos, no keys largas; rotation debe ejecutarse de forma periódica, por ejemplo cada 30 días, con un proceso automatizado que actualiza el secreto y notifica a los sistemas relacionados; revocation debe ofrecer un mecanismo de emergencia para desactivar el secreto en cuanto se detecte una fuga; expiration define una fecha de caducidad para que el secreto deje de funcionar automáticamente.

MCP Security Best Practices señala que token passthrough es un anti-pattern: pasar el token OAuth del usuario directamente al agente evita controles de seguridad, rompe el audit trail y cruza trust boundaries. El diseño correcto emite un delegated token cuando el usuario autoriza al agente: corto, limitado en scope y con audience explícita.

Los principios de OWASP Secrets Management son centralize, least privilege, automate y auditing. El acceso a secretos sigue el mínimo privilegio. El mantenimiento manual aumenta fugas y errores; rotation, revocation y expiration forman parte del lifecycle.

Audit log: ¿quién llamó a qué y cuándo?

El audit log debe reconstruir “quién llamó a qué herramienta, en nombre de quién, qué objeto tocó y cuál fue el resultado”, mientras enmascara parámetros y secretos.

Audit Log Schema

Campo	Descripción	Regla de enmascarado
traceId	ID de la cadena de llamadas, reutiliza el concepto trace/runId de N156	No enmascarar
timestamp	Hora de la llamada, ISO 8601	No enmascarar
actor	Entidad que inició la llamada	No enmascarar
subject	Entidad representada	No enmascarar
tool	Nombre de la herramienta	No enmascarar
action	Tipo de operación, como read/write/delete	No enmascarar
resource	Objeto objetivo	Enmascarar: customer_id → cust_***
outcome	Resultado, como success/failure/denied	No enmascarar

Reglas de enmascarado: no registrar token, secret, password, email, phone ni PII. Registrar who/what/when/where/outcome. Ejemplos: customer_id=12345 se guarda como cust_; email=user@example.com como e@***.com; token=Bearer xxx como Bearer ***; password=secret123 no se guarda.

Según OWASP Logging Cheat Sheet, los logs de seguridad deben ayudar en investigación, auditoría y monitoreo, pero no deben registrar passwords, session ids, access tokens ni datos personales sensibles. Deben guardar información trazable como who/what/when/where/outcome.

La familia audit and accountability de NIST SP 800-53 recuerda que los audit logs son la última línea de defensa del sistema de permisos. Cuando falla una comprobación, el log debe registrar el motivo: actor sin permiso, subject sin permiso sobre el target o scope insuficiente.

Tabla de decisión del modelo de permisos: elige la combinación de controles

Mapeo de identidad, permisos de herramientas, aislamiento de secretos y audit logs no son controles independientes. Se condicionan entre sí. Esta tabla muestra combinaciones para escenarios distintos.

Escenario	identity type	tool permission	secret access	audit log	Aplicación típica
Herramienta interna de bajo riesgo	service account	whitelist, solo herramientas read	Variables de entorno	actor/tool/outcome	Generación de reportes internos, sincronización programada
SaaS multi-tenant	delegated token + tenantId	per-tool permission filtrada por tenant	secret vault con aislamiento por tenant	full schema con tenantId	Agente CRM, asistente de correo
Transacción financiera	user identity + approval	scope minimization + approval	secret reference con token corto	full schema + approvalId	Aprobación de transacciones, movimiento de fondos
Operación con datos sensibles	delegated token + approval	whitelist + approval + guardrails	secret vault con revocación de emergencia	full schema + enmascarado	Exportación de datos, consulta de clientes

OWASP AI Agent Security Cheat Sheet recomienda separate tool sets para distintos trust levels y explicit authorization para operaciones sensibles. La idea central de la tabla es la composición: los escenarios de alto riesgo requieren varias capas de control, no un único mecanismo presentado como solución universal.

Checklist de diagnóstico: síntomas comunes de problemas de permisos

Estos son síntomas frecuentes, causas probables, pasos de comprobación y soluciones.

Síntoma	Causa probable	Qué comprobar	Solución
El agente recibe 403 Forbidden al llamar a una herramienta	actor no tiene tool permission o subject no tiene target permission	Revisar permission_level de actor y permisos de resource de subject	Confirmar el mapeo de identidad y ajustar la matriz de permisos
En los logs actor está vacío o subject está mezclado	Los campos de mapeo de identidad no se transmiten bien	Comprobar si agent context contiene actor/subject/tenantId	Pasar los campos de identidad por toda la cadena de llamadas
La llamada a la herramienta funciona, pero el audit log no tiene campos necesarios	Audit Log Schema incompleto	Revisar si la lógica de logging incluye todos los campos	Completar el schema y añadir traceId/approvalId
La petición del usuario A lee datos del usuario B	tenantId o subject no están aislados, o se comparte un token de administrador	Comprobar si se usan delegated tokens y si tenantId es correcto	Usar delegated token y forzar validación de tenantId
Tras secret rotation, el agente sigue usando la key antigua	Secret reference no actualizada, o rotation no aplicada	Comprobar si el vault devuelve el nuevo secret y si el agente vuelve a pedirlo	Hacer que rotation actualice automáticamente la reference
Tras aprobación, la llamada a la herramienta sigue fallando	Guardrails fallan por parámetros fuera de rango o detección PII	Revisar los logs de tool_input_guardrails	Ajustar parámetros o reglas de guardrails

Checklist de implementación: construir un modelo de permisos Agent desde cero

Estos son los 5 pasos clave para implementar el modelo de permisos.

Paso 1: definir reglas de mapeo de identidad

Puntos de decisión: ¿hace falta aislamiento multi-tenant, es decir, añadir tenantId? ¿Hay tareas de fondo, es decir, definir service account? ¿Hay workflows automatizados, es decir, usar delegated tokens?

Pseudocódigo:

interface IdentityContext {
  actor: string;        // Entidad que inicia la llamada
  subject: string | null;  // Entidad representada
  delegatedBy?: string;  // Origen de la delegación
  tenantId?: string;    // Identificador del tenant
}

Paso 2: diseñar la matriz de permisos de herramientas

Puntos de decisión: ¿hace falta aprobación, es decir, needs_approval=true? ¿Hace falta filtrado dinámico, es decir, implementar is_enabled en tiempo de ejecución? ¿Hace falta validar parámetros, es decir, implementar tool_input_guardrails?

Ejemplo de código:

interface ToolPermission {
  name: string;
  permission_level: 'read' | 'write' | 'admin';
  required_scope: string[];
  needs_approval: boolean;
  is_enabled: (context: IdentityContext) => boolean;
}

Paso 3: conectar secret vault

Puntos de decisión: ¿hacen falta credenciales cortas, es decir, usar secret reference? ¿Hace falta revocación de emergencia, es decir, asegurar que el vault pueda desactivar acceso al instante?

Ejemplo de código:

async function getSecret(secretRef: string, context: IdentityContext): Promise<string> {
  // Validar identidad
  await vault.authenticate(context.actor);
  // Validar permisos
  await vault.authorize(context.actor, secretRef);
  // Obtener un token corto
  const token = await vault.getToken(secretRef, expiresIn: '15m');
  // Registrar auditoría
  await auditLog.record({
    actor: context.actor,
    action: 'get_secret',
    resource: secretRef,
    outcome: 'success'
  });
  return token;
}

Paso 4: implementar audit logs

Puntos de decisión: ¿hace falta enmascarado, es decir, reglas de redaction? ¿Hace falta traceId, es decir, reutilizar trace/runId de N156?

Ejemplo de código:

interface AuditLogEntry {
  traceId: string;
  timestamp: Date;
  actor: string;
  subject: string | null;
  tool: string;
  action: 'read' | 'write' | 'delete';
  resource: string;  // Enmascarado
  outcome: 'success' | 'failure' | 'denied';
}

Paso 5: probar límites de permisos

Puntos de decisión: ¿vas a probar accesos no autorizados, como usuario A intentando acceder a datos de usuario B? ¿Vas a probar fuga de token, simulando revocación tras una fuga de secret? ¿Vas a probar trazabilidad de auditoría, recorriendo toda la cadena por traceId?

Checklist de pruebas: acceso no autorizado (actor=user_A, resource=tenant_B → debe devolver 403); prueba de fuga de token (vault.revoke(secretRef) → el agente no debe poder obtener un nuevo token); prueba de trazabilidad Audit (consultar la cadena completa por traceId → debe incluir actor/subject/tool/outcome).

Siguiente paso: lecturas relacionadas

El modelo de permisos de un Agent toca identidad, herramientas, Secrets y auditoría. Estas lecturas ayudan a completar el mapa.

Artículos publicados:

• Guía de Agent Sandbox: Sandbox resuelve el aislamiento de ejecución con contenedores/Docker. Este artículo cubre permisos y límites de secretos; se complementan.
• Tool Calling en la práctica: Bases del tool calling. Este artículo amplía con whitelist de herramientas, per-tool permission y validación de entrada.
• Monitoreo y recuperación de AI Agents: Bases de monitoreo y alertas. Este artículo añade campos de audit y traceId.