OAuth para Agentes de IA: Actuando de forma segura en nombre del usuario

OAuth 2.0 para agentes de IA: autorización delegada sin perder la atribución

Su agente necesita leer el calendario de un cliente, enviar un mensaje desde su cuenta o registrar un ticket bajo su nombre. La solución rápida es una cuenta de servicio con acceso amplio, pero todas las acciones aparecen como si fueran de “la integración” y una credencial comprometida puede exponer varias cuentas.

Prueba Apidog hoy

La solución correcta es la autorización delegada: el usuario concede a su agente un token con alcance específico y revocable. El agente actúa en nombre de ese usuario y el registro de auditoría conserva su identidad. Para eso existe OAuth 2.0.

El reto es que OAuth suele asumir un navegador y una persona haciendo clic en Permitir, mientras que los agentes normalmente se ejecutan en segundo plano. Esta guía muestra cómo adaptar OAuth a agentes, definir alcances, almacenar y actualizar tokens, gestionar la revocación y probar todo sin usar una cuenta real.

Si todavía está comparando autenticación basada en claves y autenticación delegada, consulte nuestra comparación entre claves API y OAuth.

Cuenta de servicio o acceso delegado

Elija el modelo según la propiedad de los datos:

• Cuenta de servicio: el agente tiene su propia identidad y permisos. Es adecuada para leer su base de datos, llamar a servicios internos o ejecutar trabajos programados en su infraestructura.
• Acceso delegado: el agente actúa como un usuario concreto, con sus permisos y no más. Es necesario cuando los datos pertenecen a otra persona.

El acceso delegado exige más trabajo, pero ofrece tres ventajas importantes:

1. El usuario puede ver qué concedió.
2. El usuario puede revocar el acceso.
3. Cada acción queda asociada a su identidad.

Evite usar una cuenta de servicio con acceso a toda la organización para actuar “como” cualquier usuario. Una sola credencial filtrada expondría a todos, sin revocación individual y con una auditoría engañosa.

Para cuentas de servicio, defina el alcance con mínimo privilegio y rótelo periódicamente, como se explica en claves API de menor privilegio para agentes.

Qué flujo OAuth se adapta a un agente

OAuth 2.0 define varios tipos de concesión. La especificación OAuth 2.0 contiene el conjunto completo; estos son los flujos más relevantes.

Código de autorización con PKCE

Es el flujo estándar para actuar como un usuario:

1. Redirija al usuario al proveedor.
2. Solicite únicamente los alcances necesarios.
3. Haga que el usuario apruebe el acceso.
4. Intercambie el código por tokens en su servidor.
5. Almacene de forma segura el token de actualización.

PKCE protege el intercambio y es la recomendación predeterminada para los clientes, según la Mejor Práctica Actual de Seguridad de OAuth 2.0. Consulte también este recorrido por la concesión de código de autorización.

Para un agente, el flujo se ejecuta una vez, cuando una persona conecta la integración. El agente no vuelve a abrir el navegador: utiliza el token de actualización obtenido durante esa conexión.

Credenciales de cliente

Es un flujo de máquina a máquina, sin usuario. Es correcto para cuentas de servicio, pero no sirve para actuar como una persona porque no existe consentimiento de usuario.

Concesión de autorización de dispositivo

Es útil para agentes CLI o máquinas sin navegador. El usuario recibe un código y aprueba el acceso desde otro dispositivo, como su teléfono.

Intercambio de tokens

El RFC 8693 permite intercambiar un token por otro más restringido. Así puede entregar a un subagente un token limitado a una tarea sin exponerle la concesión original del usuario.

Este mecanismo resulta especialmente útil en sistemas multiagente y complementa las reglas de límite descritas en transferencia multiagente.

Defina un alcance estricto para cada agente

Los alcances son la principal ventaja del acceso delegado. No solicite todos los permisos que la aplicación podría necesitar.

Solicite solo lo necesario

Un agente de calendario puede necesitar escritura de calendario, pero no acceso al correo, los contactos o los archivos. Los usuarios revisan la pantalla de consentimiento; una lista extensa reduce la confianza y aumenta el radio de explosión.

Consulte qué son los alcances de OAuth 2 para conocer cómo los modelan los proveedores.

Pida permisos incrementalmente

Solicite el mínimo durante la conexión y pida permisos adicionales solo cuando el usuario utilice una función que los requiera. El consentimiento vinculado a una acción concreta es más fácil de entender y justificar.

Use un token por agente

Si un agente de investigación y uno de facturación actúan para el mismo usuario, derive dos tokens con distintos alcances. Un agente de investigación comprometido no debería poder emitir reembolsos, y los registros deben identificar cuál agente actuó.

Prefiera alcances de lectura y requiera una escalada explícita para escribir. Para operaciones destructivas, añada una puerta de aprobación, como se describe en barreras de seguridad para agentes de IA.

Almacene, actualice y revoque tokens

Los tokens son credenciales. Trátelos como tales.

Almacenamiento

• Cifre los tokens de actualización en reposo.
• Use una clave o registro separado por usuario.
• No los escriba en logs, prompts ni trazas.
• Nunca permita que el modelo vea un token.

Un token dentro del contexto puede acabar en una transferencia, un registro del proveedor o un resumen. Consulte rastreo de llamadas de herramientas de agentes para conocer patrones de redacción en el límite.

Actualización

Los tokens de acceso suelen tener una vida corta. Coloque un administrador de tokens delante del cliente HTTP para actualizar la credencial cuando esté próxima a caducar y reintentar la llamada una sola vez después de un 401.

class TokenManager:
    def __init__(self, store, provider):
        self.store, self.provider = store, provider

    def access_token(self, user_id, agent_scope):
        rec = self.store.get(user_id, agent_scope)
        if rec.expires_in() > 60:
            return rec.access_token

        fresh = self.provider.refresh(
            rec.refresh_token,
            scope=agent_scope,
        )
        self.store.save(
            user_id,
            agent_scope,
            fresh,
        )  # rotation: store the new refresh token
        return fresh.access_token

Dos detalles son críticos:

1. Muchos proveedores rotan los tokens de actualización. Cada actualización produce uno nuevo e invalida el anterior. Persista el nuevo inmediatamente.
2. Serialice las actualizaciones por usuario. Dos trabajadores que actualizan a la vez pueden competir y dejar inválido el token que el otro acaba de guardar.

Revocación

El acceso puede revocarse, el token puede caducar o la cuenta puede eliminarse. Trate 401 y 403 como estados terminales:

• No reintente indefinidamente.
• Muestre si falta autenticación o un alcance.
• Identifique al usuario y el alcance afectado.
• Pida reconectar cuando sea necesario.

Reintentar un fallo de autenticación rara vez ayuda y puede activar protecciones contra abuso. Consulte diseño de errores de API para agentes de IA.

Separe el consentimiento del tiempo de ejecución

El consentimiento requiere una persona, pero la ejecución del agente no tiene por qué requerirla.

Durante la conexión

1. Una persona autoriza el acceso mediante un navegador.
2. Su servicio almacena el token de actualización.
3. El sistema asocia la concesión al usuario y al agente correspondiente.

Durante la ejecución

El agente utiliza la concesión almacenada sin intervención humana. Este diseño funciona para agentes programados y procesos en segundo plano.

Planifique también estos límites:

• Las concesiones pueden caducar después de meses sin uso o por política del proveedor.
• Detecte una concesión caducada y notifique al usuario.
• No intente escalar permisos por su cuenta.
• Si falta un alcance, solicítelo mediante un nuevo consentimiento.

Para acciones de alto riesgo, agregue una segunda aprobación en el momento de ejecutar la acción. El token responde “¿puede actuar el agente?”; la aprobación responde “¿debe hacerlo ahora?”.

Pruebe el flujo antes de usarlo en producción

Las rutas de autenticación suelen probarse poco porque requieren recorrer manualmente las pantallas del proveedor.

Construya al menos estos cinco casos:

• Ruta feliz: token válido y llamada exitosa.
• Token de acceso caducado: el proveedor devuelve 401, el administrador actualiza el token y la llamada se reintenta una vez.
• Token de actualización revocado: la actualización devuelve invalid_grant; el agente se detiene y solicita reconexión.
• Alcance insuficiente: el proveedor devuelve 403; el agente no reintenta y comunica qué alcance falta.
• Actualización concurrente: dos llamadas simultáneas para el mismo usuario provocan exactamente una actualización.

Ejecútelos contra simulaciones. En Apidog puede definir el endpoint de tokens y los endpoints protegidos, simular respuestas y probar también los cuerpos de error sin tocar un proveedor real.

Consulte ejecutar agentes contra simulaciones en lugar de producción y la guía de pruebas de API de OAuth 2.

Tres integraciones y sus necesidades

Asistente de calendario

Lee la disponibilidad y reserva reuniones para un usuario:

• Acceso delegado.
• Dos alcances específicos.
• Consentimiento en navegador durante la conexión.
• Ejecuciones posteriores en segundo plano.

El caso clave es la revocación. Si el usuario desconecta la integración, la ejecución nocturna debe detectarlo y detenerse, no reintentar una concesión muerta durante una semana.

Agente de soporte en una bandeja compartida

Actúa sobre tickets que pertenecen a un equipo. Usar la cuenta compartida del equipo puede ser válido si el recurso pertenece realmente al equipo, pero cada respuesta parecerá idéntica en el registro.

Una alternativa más auditable es una identidad de bot con alcances propios y un registro del humano que activó la ejecución. Así se conserva la atribución sin fingir que el agente es una persona.

Agente de operaciones interno

Reinicia servicios y lee paneles de su propia infraestructura:

• No maneja datos de usuarios.
• No necesita delegación.
• Usa una cuenta de servicio con alcances estrictos.
• Se concentra en rotación y radio de explosión.

La línea divisoria es la propiedad: si los datos pertenecen a alguien que podría querer revocar el acceso, use autenticación delegada. Si le pertenecen a usted, use una cuenta de servicio.

Conserve la atribución humana

La autenticación delegada responde “¿en nombre de quién?”, pero no “¿a petición de quién?”.

Guarde ambas identidades junto con el trabajo:

• ID del usuario representado.
• Nombre o ID del agente.
• Alcance utilizado.
• ID del token, nunca el token.
• Humano que solicitó o activó la ejecución.

La capa de gestión de trabajo suele ser el lugar adecuado. Por ejemplo, una tarea de Sharkly puede registrar a la persona responsable junto con el agente o equipo asignado. Consulte la documentación de Sharkly para conocer esa separación.

Después de un incidente, la pregunta suele ser “¿quién pidió esto?”. Un token por sí solo no puede responderla.

Nunca permita que el modelo vea la credencial

Una regla arquitectónica evita muchos incidentes:

El modelo nunca debe ver un token.

Inyecte el token en la capa HTTP después de que el modelo haya elegido una herramienta y generado sus argumentos:

• El esquema de la herramienta no incluye un parámetro token.
• El prompt no contiene credenciales.
• El ejecutor elimina el encabezado Authorization antes de devolver la respuesta al modelo.
• El ejecutor selecciona el usuario y el token, no el modelo.

Esto es especialmente importante en agentes porque cualquier dato dentro del contexto puede terminar en una transferencia, una traza, un mensaje de error o una respuesta al usuario.

La misma regla se aplica a la identidad del usuario. El ejecutor sabe para quién se ejecuta el trabajo y selecciona la concesión correspondiente. No deje que el modelo decida el usuario.

Lista de verificación

• [ ] Use acceso delegado cuando los datos pertenezcan a un usuario.
• [ ] Use cuentas de servicio solo para sus propios recursos.
• [ ] Use código de autorización con PKCE durante la conexión.
• [ ] Use concesión de dispositivo en máquinas sin navegador.
• [ ] Solicite alcances mínimos y específicos por agente.
• [ ] Escale permisos incrementalmente.
• [ ] Entregue a los subagentes tokens intercambiados, no copias de la concesión original.
• [ ] Cifre los tokens de actualización y manténgalos fuera de prompts, logs y trazas.
• [ ] Serialice la actualización por usuario y persista los tokens rotados.
• [ ] Trate 401 y 403 como estados terminales.
• [ ] Detecte concesiones caducadas y solicite reconexión.
• [ ] Proteja las acciones de alto riesgo con aprobación adicional.
• [ ] Pruebe los cinco escenarios contra simulaciones en CI.
• [ ] Registre quién solicitó la ejecución además del usuario representado.

La autenticación delegada requiere más trabajo que una clave compartida, pero ofrece dos garantías esenciales cuando un agente actúa en nombre de otras personas: el usuario puede retirar el acceso y la auditoría puede mostrar quién hizo qué.

Descargue Apidog para construir el flujo de tokens y probar sus casos de fallo antes de que un agente lo ejecute sin supervisión.

Preguntas frecuentes

¿Puede el agente completar por sí mismo el consentimiento de OAuth?

No, y no debería intentarlo. El consentimiento requiere que una persona decida qué conceder. Haga que un humano autorice una vez mediante un flujo normal de navegador y permita que el agente use la concesión resultante.

¿Debería cada agente tener su propio cliente OAuth?

Use clientes separados por integración de producto y tokens separados por agente dentro de cada integración, normalmente mediante intercambio de tokens. Los clientes independientes también ayudan cuando el proveedor aplica límites de tasa por cliente o necesita una revocación separada.

¿Qué ocurre si el token de actualización rota y pierdo el nuevo?

El usuario queda bloqueado y debe volver a conectarse. Persista el nuevo token en la misma transacción que consume el anterior y serialice las actualizaciones por usuario.

¿Es seguro permitir que el modelo vea un token de acceso?

No. El token pertenece a la capa HTTP y debe inyectarlo el ejecutor. Cualquier dato visible para el modelo puede terminar en una traza, un resumen o una respuesta.

¿Cómo audito qué agente hizo qué?

Registre el ID del usuario, el nombre del agente, el alcance utilizado y el identificador del token en cada llamada. Nunca registre el token. Consulte rastreo de llamadas de herramientas de agentes.

¿Qué pasa si el proveedor no admite el intercambio de tokens?

Almacene concesiones separadas por agente cuando el proveedor permita varias, o aplique la restricción de alcance en su propio gateway. El gateway debe filtrar las operaciones permitidas antes de que las llamadas salgan de su red.