Durante años, la autenticación en la web siguió una suposición de diseño: un ser humano se sienta detrás de un navegador. Haga clic en un botón. Llene un formulario. Verificar un correo electrónico. Copie una clave API y péguela en otro lugar.
Ese modelo no funciona cuando el usuario delega trabajo a un agente. Los agentes ya están escribiendo código, abriendo solicitudes de extracción, clasificando tickets, consultando sistemas y actualizando registros. Pero la mayoría de los productos todavía no tienen una forma real de que un agente se registre. La solución alternativa (darle a un agente una clave API sin formato o un token de sesión) produce credenciales sin alcance, difíciles de auditar por sesión e imposibles de revocar selectivamente. WorkOS propone una alternativa estructurada: auth.md, un protocolo abierto para el registro de agentes.
¿Qué es auth.md?
auth.md es un pequeño archivo Markdown que una aplicación publica en una ubicación conocida, normalmente https://service.com/auth.md. El archivo les dice a los agentes cómo registrarse en ese servicio: qué flujos son compatibles, qué alcances existen y cómo se emiten, auditan y revocan las credenciales.
Debido a que es Markdown de texto sin formato, el mismo archivo funciona como documentación para desarrolladores humanos y como un artefacto en tiempo de ejecución que los agentes pueden leer mediante programación. Un agente busca el archivo, lee las secciones estructuradas, elige el flujo correcto y se registra, sin que un humano complete un formulario.
Discovery funciona en dos saltos. La fuente de la verdad legible por máquina se encuentra en /.well-known/oauth-protected-resource (Metadatos de recursos protegidos o PRM). Promueve el recurso y apunta al servidor de autorización. Los metadatos del servidor de autorización en /.well-known/oauth-authorization-server llevan el bloque agent_auth, el objeto estructurado que indica a los agentes qué flujos son compatibles y cuáles son los valores de Register_uri, Claim_uri, revocation_uri e Identity_types_supported. El archivo auth.md es el complemento que indica a los agentes esta ruta de descubrimiento.
En cualquier 401 de la API, el servicio debe devolver un encabezado WWW-Authenticate: Bearer Resource_metadata=”…” para que los agentes puedan iniciar el descubrimiento sin leer primero la documentación.
Los dos flujos de registro
auth.md define dos flujos principales. Una aplicación puede admitir uno o ambos.
Flujo verificado por el agente: el proveedor de identidad del agente (OpenAI, Anthropic, Cursor o cualquier plataforma confiable) da fe de la identidad del usuario en el momento del registro. El agente solicita un ID-JAG específico de la audiencia a su proveedor y luego lo envía al punto final /agent/auth de la aplicación. La aplicación decodifica el encabezado ID-JAG para obtener kid y alg, busca el emisor en su lista de proveedores confiables, recupera el JWKS del proveedor, verifica la firma, valida las reclamaciones (aud, exp, iat, jti, client_id) y devuelve las credenciales de forma sincrónica. Sin OTP, sin ida y vuelta por correo electrónico, no se requiere interacción humana.
El resultado es un registro de delegación por (iss, sub, aud) que el proveedor puede revocar en cualquier momento enviando un token de cierre de sesión al revocation_uri del servicio. Las aplicaciones que ya suministran JIT a usuarios de OIDC o SAML reconocerán este patrón: tiene la misma forma con un emisor diferente. Una restricción importante: los tokens de acceso emitidos a partir de la verificación ID-JAG no deben incluir un token de actualización. El agente debe presentar un ID-JAG nuevo para ampliar el acceso.
Flujo reclamado por el usuario: esta es una ruta basada en OTP que no requiere la participación del proveedor de agentes. El agente se registra en la aplicación y el usuario vincula el registro leyendo un código único de un correo electrónico enviado al agente. Los dos puntos finales de reclamo son /agent/auth/claim (para activar el correo electrónico OTP) y /agent/auth/claim/complete (para enviar el código).
Este flujo tiene dos formas iniciales. En la variante de inicio anónimo, el agente se registra automáticamente sin identidad y recibe una credencial inmediatamente, con el alcance de reclamar previamente los permisos que define la aplicación. En cualquier momento antes de que expire el registro, el agente ejecuta la ceremonia OTP para vincular la credencial a un usuario real y actualizar los alcances. La clave API no se rota en el momento de la reclamación: los alcances se actualizan en su lugar.
En la variante de correo electrónico requerido, el agente proporciona un correo electrónico de usuario al registrarse. La credencial se retiene por completo hasta que se complete la ceremonia de la OTP. Utilícelo cuando cualquier uso previo a la reclamación sea inaceptable.
Coincidencia de usuarios y auditoría
Cuando se emiten las credenciales, el servicio debe hacer coincidir el registro con un usuario existente o proporcionar uno nuevo. El orden de resolución recomendado es: hacer coincidir primero un registro de delegación anterior para el mismo (iss, sub) par; luego haga coincidir un correo electrónico verificado; luego, proporcione JIT a un nuevo usuario según la política de la aplicación, o rechácelo si el producto requiere incorporación manual.
Para la observabilidad y la respuesta a incidentes, los documentos recomiendan registrar un conjunto estándar de eventos de auditoría: registro.creado, reclamo.requerido, otp.generado, reclamo.confirmado, registro.expirado y registro.revocado. Para los flujos ID-JAG, incluya iss, sub y agent_platform para que los operadores puedan correlacionarse con los registros del lado del proveedor.
Explicador visual de Marktechpost
Conclusiones clave
auth.md es un protocolo abierto: las aplicaciones alojan un archivo Markdown en service.com/auth.md que describe cómo los agentes se registran y obtienen credenciales específicas. Se admiten dos flujos: agente verificado (basado en ID-JAG, sincrónico, sin interacción humana) y reclamado por el usuario (basado en OTP, no se requiere integración de proveedor). El descubrimiento es de dos saltos: PRM en /.well-known/oauth-protected-resource apunta al servidor de autorización, cuyos metadatos contienen el bloque agent_auth con URL de punto final y flujos admitidos. El protocolo compone los estándares OAuth existentes (RFC 9728, ID-JAG) y no está vinculado a la infraestructura de WorkOS.
Consulte el repositorio y los detalles técnicos. Además, no dude en seguirnos en Twitter y no olvide unirse a nuestro SubReddit de más de 150.000 ML y suscribirse a nuestro boletín. ¡Esperar! estas en telegrama? Ahora también puedes unirte a nosotros en Telegram.
¿Necesita asociarse con nosotros para promocionar su repositorio de GitHub O su página principal de Hugging O su lanzamiento de producto O seminario web, etc.? Conéctate con nosotros