Su agente necesita leer el calendario de un cliente, enviar un mensaje desde su cuenta o registrar un ticket bajo su nombre. La versión rápida es tener una cuenta de servicio con acceso amplio y actuar a través de ella. Cada acción aparece como "la integración", nadie puede saber qué usuario activó qué, y una credencial comprometida expone todas las cuentas que toca.
La versión correcta es la autorización delegada: el usuario otorga a su agente un token con un alcance específico y revocable, el agente actúa como ese usuario, y el registro de auditoría los nombra. Para esto fue creado OAuth 2.0. Lo que lo hace incómodo para los agentes es que OAuth asume un navegador y una persona presente para hacer clic en "Permitir", y los agentes se ejecutan en segundo plano a las 3 AM.
Esta guía cubre qué flujo de OAuth se adapta a un agente, cómo definir el alcance y almacenar los tokens, qué hacer con la actualización y la revocación, y cómo probar todo el camino sin una cuenta en vivo. Si aún está eligiendo entre la autenticación basada en clave y la delegada, nuestra comparación de claves API y OAuth es el lugar para comenzar.
Apidog ayuda con la parte que los equipos subestiman: ejercitar cada rama del flujo, incluyendo la caducidad y la revocación, antes de que un agente los encuentre en producción.
Cuenta de servicio o acceso delegado
Elija deliberadamente, porque los dos modelos fallan de manera diferente.
Una cuenta de servicio es la propia identidad de su agente, con sus propios permisos. Se adapta al trabajo que el agente realiza en su nombre: leer su propia base de datos, llamar a sus propios servicios internos, ejecutar trabajos programados contra su infraestructura. Defina su alcance de manera estricta, como en nuestra publicación sobre claves API de menor privilegio para agentes, y rótela.
El acceso delegado es el agente actuando como un usuario específico, con los permisos de ese usuario y no más. Es necesario siempre que los datos pertenezcan a otra persona. Tres propiedades lo hacen valer el trabajo extra: el usuario puede ver lo que se le concedió, el usuario puede revocarlo, y cada acción lleva su identidad en el registro.
El modo de fallo a evitar es una cuenta de servicio con acceso a toda la organización utilizada para actuar "como" usuarios. Funciona, y significa que una única credencial filtrada expone a todos, sin revocación por usuario y sin un registro de auditoría honesto.
Qué flujo se adapta a un agente
OAuth 2.0 define varios tipos de concesión, y solo unos pocos tienen sentido aquí. La especificación OAuth 2.0 tiene el conjunto completo; estos son los que usará.
Código de autorización con PKCE. El flujo estándar para actuar como usuario. El usuario es redirigido al proveedor, aprueba los alcances, y su servicio intercambia el código por tokens. PKCE protege el intercambio y ahora es la recomendación predeterminada para cada tipo de cliente, según la Mejor Práctica Actual de Seguridad de OAuth 2.0. Nuestro recorrido por la concesión de código de autorización cubre la mecánica paso a paso.
El punto específico del agente: este flujo se ejecuta una vez, con el humano presente, en el momento de la conexión. El agente nunca lo ejecuta. Utiliza el token de actualización que produjo el flujo. Separe esos dos momentos en su diseño y la mayor parte de la incomodidad desaparece.
Credenciales de cliente. De máquina a máquina, sin usuario involucrado. Correcto para cuentas de servicio y erróneo para actuar como usuario, porque no hay un usuario para consentir.
Concesión de autorización de dispositivo. Para agentes en máquinas sin navegador. El usuario obtiene un código y lo aprueba en su teléfono. Útil para agentes de CLI y entornos sin cabeza.
Intercambio de tokens. RFC 8693 permite a un servicio intercambiar un token por uno más restringido. Así es como se le da a un subagente un token limitado a un alcance para una tarea, derivado de la concesión más amplia del usuario, sin entregarle el original. Si ejecuta sistemas multiagente, este es el mecanismo que hace prácticas las credenciales por agente, y se ajusta a las reglas de límite en nuestra publicación sobre transferencia multiagente.
Defina el alcance de manera estricta y por agente
Los alcances son donde el acceso delegado se justifica, y donde la mayoría de las implementaciones se vuelven perezosas al solicitar todo lo que la aplicación podría necesitar.
Solicite solo lo que este agente hace. Un agente de programación necesita escritura de calendario y nada más. Ni correo, ni contactos, ni archivos. Los usuarios leen la pantalla de consentimiento, y una lista larga es un problema de confianza y un problema de radio de explosión. Nuestro explicador sobre alcances de OAuth 2 cubre cómo los proveedores los modelan.
Pregunte incrementalmente. Solicite lo mínimo al momento de la conexión, luego solicite más cuando el usuario pida una función que lo necesite. El consentimiento vinculado a una solicitud concreta es más fácil de otorgar y más fácil de justificar.
Dele a cada agente su propio token. Si un agente de investigación y un agente de facturación actúan para el mismo usuario, derive dos tokens con diferentes alcances en lugar de compartir uno. Entonces, un agente de investigación comprometido no puede emitir reembolsos, y el registro le dice qué agente actuó.
Prefiera los alcances de lectura por defecto y requiera una escalada explícita para las escrituras. Combine esto con una puerta de aprobación en llamadas destructivas, como en nuestra publicación sobre barreras de seguridad de agentes de IA, para que un token que puede escribir no sea lo único que se interponga entre el agente y un error.
Almacenar, actualizar y revocar
Los tokens son credenciales, así que trátelos como credenciales.
Almacenamiento. Cifre los tokens de actualización en reposo, con clave por usuario. Nunca los escriba en los registros, nunca los ponga en los prompts y nunca permita que un modelo vea uno. Un token en contexto es un token en su almacén de trazas, los registros de su proveedor y posiblemente un resumen. Nuestra publicación sobre rastreo de llamadas de herramientas de agente cubre la redacción en el límite en lugar de en el tiempo de lectura.
Actualización. Los tokens de acceso son de corta duración por diseño. El agente nunca debe gestionarlo por sí mismo; un administrador de tokens delante del cliente HTTP actualiza cuando la caducidad está cerca y reintenta la llamada una vez en 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 importan. Los proveedores rotan cada vez más los tokens de actualización, emitiendo uno nuevo en cada actualización e invalidando el antiguo, así que persista el nuevo inmediatamente o bloqueará al usuario. Y serialice las actualizaciones por usuario, ya que dos actualizaciones concurrentes con un proveedor rotatorio competirán y una perderá.
Revocación. Los usuarios revocan el acceso, los tokens caducan, los administradores eliminan cuentas. El agente debe manejar 401 y 403 como terminales en lugar de reintentables. Reintentar un fallo de autenticación nunca ayuda y puede activar protecciones contra el abuso. Devuelva un mensaje claro que nombre al usuario y al alcance para que un humano pueda actuar, siguiendo los patrones de error en nuestra publicación sobre diseño de errores de API para agentes de IA.
El problema del consentimiento
La parte incómoda de los agentes más OAuth: el consentimiento necesita un humano, y los agentes se ejecutan sin supervisión.
Separe el tiempo de conexión del tiempo de ejecución y se vuelve manejable. En el momento de la conexión, una persona autoriza una vez, con un navegador, y usted almacena un token de actualización. En el tiempo de ejecución, el agente utiliza esa concesión sin intervención humana. Esto funciona para agentes programados y en segundo plano, que son la mayoría.
Dos límites a planificar. Las concesiones caducan, a veces después de meses sin uso, a veces por política. Detecte una concesión caducada, detenga la ejecución y notifique al usuario, en lugar de fallar silenciosamente cada noche. Y el consentimiento tiene un límite de alcance: un agente que necesita un alcance que el usuario nunca concedió debe pedirlo en lugar de escalarlo por sí mismo.
Para cualquier cosa de alto riesgo, agregue una segunda puerta en el momento de la acción. El token demuestra que el agente puede actuar; una puerta de aprobación decide si debe hacerlo. Esas son preguntas diferentes y ambas merecen una respuesta.
Pruebe el flujo antes de que un agente lo encuentre
Las rutas de código de autenticación son la parte menos probada de la mayoría de las integraciones, porque ejercitarlas manualmente significa hacer clic a través de las pantallas de un proveedor.
Construya estos cinco casos:
- Ruta feliz. Un token de acceso válido, una llamada exitosa. La línea base.
- Token de acceso caducado. El proveedor devuelve
401, el administrador actualiza, la llamada se reintenta una vez y tiene éxito. Esta es la ruta real más común y a menudo la menos probada. - Token de actualización revocado. La actualización devuelve
invalid_grant. El agente debe detenerse e informar, no entrar en bucle. - Alcance insuficiente. Un
403con un error de alcance. El agente no debe reintentar y debe indicar qué alcance falta. - Actualización concurrente. Dos llamadas para el mismo usuario a la vez. Debe ocurrir exactamente una actualización.
Ejecútelos contra simulaciones. En Apidog puede definir el endpoint de tokens y los endpoints protegidos, luego simular cada respuesta, incluidos los cuerpos de error, para que toda la matriz se ejecute sin tocar un proveedor real. Nuestra publicación sobre ejecutar agentes contra simulaciones en lugar de producción cubre el hábito más amplio, y nuestra guía de pruebas de API de OAuth 2 cubre el detalle a nivel de solicitud.
Tres integraciones y lo que necesitan
Un asistente de calendario. Lee la disponibilidad y reserva reuniones para un usuario. Acceso delegado, dos alcances, consentimiento en el navegador en el momento de la conexión, ejecuciones en segundo plano después. El fallo interesante es la revocación: el usuario desconecta la integración y la ejecución nocturna debe detectarlo y detenerse en lugar de reintentar una concesión muerta durante una semana.
Un agente de soporte dentro de una bandeja de entrada compartida. Actúa sobre tickets que pertenecen a un equipo. Aquí la cuestión de la identidad se agudiza. Actuar como la cuenta compartida del equipo es defendible, ya que el recurso realmente pertenece al equipo, pero cada respuesta se ve idéntica en el registro de auditoría. Mejor es una identidad de bot con sus propios alcances más un registro de qué humano activó la ejecución, lo que mantiene la atribución intacta sin pretender que el agente es una persona.
Un agente de operaciones interno. Reinicia servicios y lee paneles en su propia infraestructura. Sin datos de usuario, sin delegación. Una cuenta de servicio con alcances estrechos es la respuesta correcta, y el trabajo se dedica a la rotación y el radio de explosión en lugar de al consentimiento.
La línea divisoria es la propiedad. Si los datos pertenecen a alguien que razonablemente podría querer revocar su acceso, use la autenticación delegada. Si le pertenecen a usted, use una cuenta de servicio y dedique el esfuerzo a la definición del alcance.
Mantenga al humano en la atribución
La autenticación delegada responde "en nombre de quién". No responde "a petición de quién", y para el trabajo de agente, usted quiere ambas cosas. Un token prueba que el agente puede actuar como un usuario; no registra qué persona solicitó la ejecución.
Mantenga esa segunda identidad junto al trabajo. Donde los agentes ejecutan tareas asignadas, la capa de gestión del trabajo es el lugar natural: una tarea de Sharkly registra a la persona responsable del trabajo junto con el Agente o Equipo asignado para ejecutarlo, lo que mantiene la responsabilidad humana y la ejecución del agente como dos hechos separados y visibles. La documentación de Sharkly describe esa división en detalle. Sin embargo, lo almacene, la pregunta de auditoría después de un incidente suele ser "¿quién pidió esto?", y un token por sí solo no puede responderla.
No permita que el modelo tenga la credencial
Una regla arquitectónica previene la mayoría de los incidentes de autenticación en los sistemas de agentes: el modelo nunca ve un token.
Los tokens son inyectados por el ejecutor en la capa HTTP, después de que el modelo ha elegido una herramienta y producido argumentos. El esquema de la herramienta no tiene un parámetro token, el prompt no contiene credenciales y la respuesta que lee el modelo tiene el encabezado Authorization eliminado.
Esto es más importante para los agentes que para los clientes comunes debido a cómo viaja la entrada del modelo. Cualquier cosa en contexto puede resumirse en una transferencia, escribirse en un rastro, repetirse en un mensaje de error o devolverse a un usuario que pidió al agente que se explicara. Ninguno de esos caminos es hostil; todas son características normales que se convierten en fugas en el momento en que una credencial está en el ámbito.
La misma regla se aplica a la identidad del usuario. El ejecutor sabe para qué usuario actúa esta ejecución y selecciona el token a partir de eso. Dejar que el modelo nombre al usuario es una decisión de autorización tomada por el componente menos predecible del sistema.
Una lista de verificación
- Acceso delegado donde los datos pertenezcan a un usuario, cuentas de servicio solo para sus propios recursos.
- Código de autorización con PKCE en el momento de la conexión, concesión de dispositivo para máquinas sin cabeza.
- Alcances solicitados por agente, mínimos, escalados incrementalmente.
- Los subagentes obtienen tokens intercambiados, no copias de la concesión del usuario.
- Tokens de actualización cifrados en reposo y nunca en prompts, registros o trazas.
- Actualización gestionada por un administrador de tokens, serializada por usuario, rotación persistida.
401y403tratados como terminales, con un mensaje que nombra al usuario y al alcance.- Concesiones caducadas detectadas y mostradas al usuario, no reintentadas todas las noches.
- Acciones de alto riesgo protegidas por aprobación además del token.
- Los cinco escenarios de autenticación probados contra simulaciones en CI.
La autenticación delegada requiere más trabajo que una clave compartida, y le brinda las dos cosas que necesita cuando un agente actúa en nombre de otras personas: el usuario puede retirarla y el registro dice quién hizo qué. Descargue Apidog para construir el flujo de tokens y sus casos de fallo antes de que un agente lo ejecute sin supervisión.
Preguntas frecuentes
¿Puede el agente completar el flujo de consentimiento de OAuth por sí mismo? No, y no debería intentarlo. El consentimiento requiere que una persona decida qué conceder. Haga que un humano autorice una vez a través de un flujo de navegador normal, luego deje que el agente use la concesión resultante.
¿Debería cada agente tener su propio cliente OAuth? Clientes separados por integración de producto, y tokens separados por agente dentro de él, generalmente a través de intercambio de tokens. Los clientes distintos ayudan cuando los proveedores aplican límites de tasa por cliente o cuando desea una revocación independiente.
¿Qué sucede si el token de actualización rota y me pierdo el nuevo? El usuario queda bloqueado y tiene que volver a conectarse. Persista el nuevo token de actualización en la misma transacción que consume el antiguo, y serialice las actualizaciones por usuario para que dos trabajadores no compitan.
¿Es seguro dejar que el modelo vea un token de acceso? No. Los tokens pertenecen a la capa HTTP, inyectados por su ejecutor. Cualquier cosa que un modelo vea puede terminar en una traza, un resumen o una respuesta, como se cubre en nuestra publicación sobre claves API de menor privilegio para agentes.
¿Cómo audito qué agente hizo qué? Registre el ID de usuario, el nombre del agente, el alcance utilizado y el identificador del token en cada llamada, nunca el token en sí. Nuestra publicación sobre rastreo de llamadas de herramientas de agente cubre la forma del registro.
¿Qué pasa si el proveedor no admite el intercambio de tokens? Almacene concesiones separadas por agente donde el proveedor permita múltiples, o imponga la restricción de alcance en su propio gateway para que las llamadas de cada agente se filtren a sus operaciones permitidas antes de que salgan de su red.