OIDC para agentes de IA: credenciales efímeras en GitHub Actions
OIDC para agentes de IA sustituye secretos estáticos por identidad verificable y credenciales cortas. Guía práctica para GitHub Actions, entornos y controles que no dependen del prompt.
OIDC para agentes de IA es el patrón por el que GitHub Actions presenta un token firmado sobre el workflow que está ejecutando, y un proveedor cloud lo intercambia por credenciales temporales para un rol concreto. La definición citable es sencilla: OIDC permite federar la identidad de una carga de trabajo sin copiar una clave secreta de larga duración en el repositorio.
Checklist
El problema de los secretos estáticos en agentes
Un secreto tradicional de CI suele sobrevivir semanas o meses, aparece en variables de repositorio u organización y acaba disponible para más workflows de los que necesita. Cuando el job ejecuta un agente de código, el secreto puede quedar al alcance de comandos, dependencias, logs, herramientas MCP o texto que el modelo no debería haber considerado confiable.
Rotar no basta si el mismo valor se replica en veinte repositorios. Revocar tampoco es instantáneo cuando no sabes qué workflow lo usó ni qué sistemas consultó. La identidad federada mejora el punto de partida: el runner pide una credencial después de demostrar quién es, para qué audiencia y bajo qué contexto de ejecución.
No daría una credencial cloud permanente a un agente que solo necesita publicar una imagen, leer un bucket o ejecutar una migración acotada. Si la tarea exige una excepción, esa excepción debe quedar escrita en una policy y tener un owner, no escondida en instrucciones de prompt.
Workflow → rol por entorno
¿Te está sirviendo? Hay una dosis cada semana
Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratisLa asignación mantenible es explícita: workflow de staging → rol de staging; workflow de producción → rol de producción. No uses el mismo rol por comodidad. Staging puede crear recursos efímeros y escribir logs; producción debería limitarse al artefacto y operación aprobada.
Restringe el subject a un repositorio y environment, o a un repositorio y ref protegida cuando el proveedor no modele environments como esperas. Añade la audience exacta que usará el SDK o acción oficial. Una policy que solo comprueba que el issuer sea GitHub equivale a permitir que cualquier workflow aparente asuma el rol.
Google Workload Identity Federation usa atributos y condiciones; Microsoft Entra valida federated identity credentials; AWS IAM usa un proveedor OIDC y condiciones sobre claims. El concepto común es mapear evidencia del workflow a un principal pequeño, no entregar acceso a toda la cuenta.
Least privilege que sobreviva a un agente
Least privilege no significa solo quitar acciones peligrosas de una lista. Significa delimitar recursos, verbos, regiones, namespaces y duración para el caso real. Un agente que publica una imagen no necesita enumerar cuentas, modificar IAM ni leer todos los buckets. Una migración necesita una base concreta, una ventana concreta y un rollback.
Puntos a revisar
Lo que conviene comprobar
Separa roles de lectura, validación y mutación. Si el agente solo genera un plan, usa lectura. Si una acción mutante es imprescindible, exige un job posterior con environment protegido y un artefacto verificable. El prompt puede describir la tarea, pero no puede elevar el rol ni ampliar la policy.
Prueba el rechazo: otro repositorio, otra rama, un fork, una audience incorrecta y un workflow reutilizable deben fallar. Un deny visible es evidencia de diseño; un workflow que nunca cruzó la frontera no demuestra nada.
Checklist
Autorización fuera del prompt
Un prompt puede pedir «despliega a producción», pero no debe ser la autoridad que lo permite. El agente interpreta texto y contexto externo; GitHub Actions y el proveedor cloud deben interpretar claims, policy, branch protection y approvals. Esto importa cuando el texto viene de una issue, comentario de PR o archivo modificado por un tercero.
La regla es que el agente pueda proponer y el sistema pueda comprobar. Usa outputs estructurados, allowlists de comandos, rutas de artefactos y una policy versionada. Si el agente intenta pedir más permisos, debe ser un fallo registrable, no una negociación dentro del chat.
OIDC complementa un sandbox y controles de herramientas; no los reemplaza. Una identidad federada con acceso de escritura sigue siendo peligrosa si el agente puede ejecutar cualquier shell o exfiltrar datos. Mira la cadena completa: input, modelo, herramientas, runner, identidad y API.
Checklist
PRs, forks y límites
Los pull requests desde forks son el caso incómodo. El código puede imprimir variables, modificar el workflow o aprovechar permisos del runner. No entregues credenciales de producción a jobs que ejecutan código no confiable. Usa validación con lectura y un job de confianza que opere sobre artefactos revisados.
Revisa pull_request_target y workflows reutilizables. Cambiar el evento para recuperar secretos puede hacer que código del PR se ejecute en el contexto privilegiado del repositorio base. Si no explicas qué checkout se ejecuta y qué ref firma el token, la arquitectura no está lista.
Los tokens OIDC no arreglan un runner comprometido ni una action de terceros maliciosa. Fija versiones, revisa dependencias y evita que el agente controle el paso que solicita identidad. El job privilegiado debe verificar procedencia del artefacto antes del intercambio.
Define expiración corta, concurrencia máxima, rate limits y separación de cuentas. Practica el incidente: token usado desde un workflow inesperado, claim de branch incorrecto, fuga en logs y despliegue parcial. La documentación no sustituye a un ejercicio.
Errores habituales
El error más común es copiar un ejemplo y dejar un subject demasiado amplio. El segundo es conceder id-token: write a todo el workflow. El tercero es usar una credencial OIDC para que un agente tenga permisos de administrador porque dura poco. Corto no significa inocuo.
También se olvida proteger el environment, se acepta cualquier branch o se mezcla staging y production en el mismo rol. Nunca imprimas el JWT en debug: trátalo como credencial mientras no expire.
No confundas federación con autenticación de usuarios. Aquí autorizamos una carga de trabajo automatizada. Si el agente actúa en nombre de una persona, necesitas delegación y consentimiento distintos; no reutilices el rol del workflow como identidad humana.
Preguntas frecuentes
¿OIDC elimina los secretos de GitHub Actions?
No. Reduce la necesidad de secretos estáticos para obtener identidad cloud, pero puede haber credenciales de terceros. Tampoco evita que un proceso autorizado abuse de su rol.
¿Puede un agente solicitar un token OIDC?
El workflow puede solicitarlo si tiene id-token: write. El agente no debería decidir cuándo ni para qué rol se intercambia: esa operación debe estar en un paso fijo y en una policy que no pueda modificar.
¿Qué subject debo usar?
Uno que represente el límite real: repositorio y environment, o repositorio y ref protegida. Elige una forma que puedas probar y auditar.
¿Es seguro OIDC en pull requests de forks?
No para entregar automáticamente producción al código del fork. Trátalo como no confiable y separa validación de despliegue.
¿Qué pasa si se filtra el token?
La ventana es limitada, pero debes retirar el binding o rol, bloquear environment, revisar logs y comprobar acciones. Diseña el kill switch antes del workflow.
¿OIDC sustituye un sandbox?
No. Resuelve identidad y credenciales; el sandbox limita filesystem, red y comandos. Un agente necesita ambas capas cuando ejecuta código.
Diseñar OIDC para un agente en GitHub Actions
- Inventariar la acción. describe API, recursos, entorno y duración que necesita el agente.
- Separar workflows. valida PRs sin privilegios y despliega desde un job de confianza con artefactos revisados.
- Configurar proveedor. registra issuer, audience exacta y mapping de claims para repositorio, ref o environment.
- Crear roles pequeños. asigna un rol por entorno y concede acciones y recursos mínimos.
- Limitar YAML. declara permissions explícitos, usa id-token: write solo donde se solicite y fija actions revisadas.
- Proteger producción. añade reviewers, branch protection, condiciones de evento y verificación de artefacto.
- Probar rechazos. ejecuta fork, rama, audience, repositorio y workflow reutilizable incorrectos; conserva evidencia.
- Preparar kill switch. documenta quién retira binding y bloquea environment; ensaya el procedimiento.
- Medir y revisar. correlaciona run_id con logs cloud y revisa claims, roles y excepciones.
Checklist
Conclusión
OIDC para agentes de IA es una mejora concreta: el workflow demuestra identidad, el proveedor valida claims y entrega credenciales efímeras para un rol acotado. Es más defendible que guardar una llave cloud permanente junto a un agente que procesa texto no confiable.
La federación no convierte a un agente en confiable por defecto. La seguridad aparece cuando subject, audience, environment, least privilege, separación de forks, trazabilidad y kill switch forman un sistema verificable. Si la policy no explica por qué ese run obtiene ese rol, el diseño no ha terminado.
Fuentes y referencias
También te puede interesar
Prompt injection en agentes de IA: guía prácticaMCP en producción: seguridad, permisos y supply chainCodex con internet: sandbox y seguridadClaude Code en GitHub Actions: seguridad de CIAgentes SQL seguros: arquitectura y permisosRecibe una lectura semanal de herramientas IA para devs
Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratis
