Guía práctica para sustituir credenciales permanentes de AWS por OIDC en GitHub Actions
Un administrador de sistemas detalla los errores comunes al configurar Trust Policies y thumbprints al migrar pipelines a tokens STS efímeros.
GitHub Actions ya soporta OpenID Connect (OIDC), pero la presión por cumplir estándares de seguridad está acelerando la migración de muchos equipos lejos de las credenciales IAM permanentes. El objetivo es eliminar secretos almacenados en variables de entorno y depender de tokens STS efímeros, válidos entre 15 y 60 minutos, que se emiten bajo demanda cuando el workflow se ejecuta.
El mecanismo funciona mediante la generación de un JSON Web Token (JWT) firmado criptográficamente por GitHub. La acción aws-actions/configure-aws-credentials envía este token a AWS STS a través de sts:AssumeRoleWithWebIdentity. AWS valida la firma y comprueba la Trust Policy del rol IAM para asegurar que el token proviene del repositorio y la rama correctos antes de devolver las credenciales temporales.
La configuración de infraestructura
Para implementar esto con Terraform o OpenTofu, solo se necesitan dos recursos: el proveedor OIDC de GitHub y un rol IAM con una política de confianza restringida. El proveedor debe apuntar a https://token.actions.githubusercontent.com con sts.amazonaws.com como cliente. En el rol IAM, la condición clave es la restricción en la claim sub (subject), que debe coincidir con el formato repo:usuario/repositorio:*.
En el archivo de workflow, es crucial configurar permissions: id-token: write a nivel de job, no solo globalmente, ya que algunos entornos de ejecución no heredan permisos superiores para jobs anidados. Además, se requiere contents: read para el checkout del código.
Errores comunes que cuestan horas
El autor del hilo señala tres trampas frecuentes que provocan el error "Not authorized to perform sts:AssumeRoleWithWebIdentity":
- Sensibilidad a mayúsculas: Las cadenas de condición en IAM son sensibles a mayúsculas. Si el nombre del repositorio o usuario contiene mezcla de casos (ej.
MyOrg/Repo), la condiciónsuben IAM debe replicar esa exactitud. - Thumbprints dinámicos: No se deben consultar dinámicamente las hojas de certificado de GitHub en Terraform, ya que cambian con frecuencia debido a actualizaciones de CDN. Lo correcto es hardcodear los thumbprints de la CA raíz intermedia oficial de GitHub:
6938fd4d98bab03faadb97b34396831e3780aea1y1c58a3a8518e8759bf075b76b750d4f2df264fcd. - Alcance de permisos: Verificar siempre que el permiso
id-tokenesté asociado al job específico que necesita asumir el rol.
Esta aproximación elimina la necesidad de rotar claves manualmente y permite un control granular por rama o entorno. Para equipos con arquitecturas multi-cuenta, la segregación de roles OIDC por cuenta objetivo se convierte en una práctica estándar de seguridad, aunque requiere probar bien las políticas de confianza cruzadas para evitar denegaciones silenciosas en producción.
