OIDC de GitHub Actions a AWS: sin claves de larga duración
Última actualización
Almacenar AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY como secretos de GitHub significa que una clave filtrada funciona desde cualquier lugar hasta que alguien la detecte y la rote. OpenID Connect (OIDC) las sustituye: cada ejecución de workflow solicita a GitHub un token firmado, y AWS lo intercambia por credenciales temporales que caducan en una hora o menos. Esta guía muestra la configuración y cómo restringirla correctamente.
Cómo funciona
- El workflow solicita un token de ID a GitHub. El token indica qué repositorio, rama y entorno ejecutan el job.
- El job presenta el token a AWS STS con
AssumeRoleWithWebIdentity. - AWS comprueba la firma frente al proveedor de identidad que registró, evalúa la política de confianza del rol frente a las claims del token y devuelve credenciales temporales.
No hay ningún secreto en GitHub. La seguridad depende de las condiciones de la política de confianza, por lo que redactarlas con cuidado es la parte esencial.
Paso 1: Crear el proveedor de identidad
En IAM, añada un proveedor de OpenID Connect con:
- URL del proveedor:
https://token.actions.githubusercontent.com - Audiencia:
sts.amazonaws.com
AWS valida las firmas de los tokens de GitHub con su propia biblioteca de CA raíz de confianza, por lo que ya no necesita gestionar una huella digital (thumbprint) para este proveedor. En la consola son unos pocos clics; con la CLI:
aws iam create-open-id-connect-provider \
--url https://token.actions.githubusercontent.com \
--client-id-list sts.amazonaws.com
Necesita un proveedor por cuenta, compartido por todos los roles.
Paso 2: Crear un rol con una política de confianza restrictiva
La claim sub (subject) identifica el contexto del workflow. Formatos habituales:
- Rama:
repo:ORG/REPO:ref:refs/heads/main - Entorno:
repo:ORG/REPO:environment:production - Pull request:
repo:ORG/REPO:pull_request - Etiqueta:
repo:ORG/REPO:ref:refs/tags/v1.0.0
Política de confianza para despliegues desde el entorno production de un repositorio:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:environment:production"
}
}
}
]
}
Use StringEquals with an exact sub where you can. If you need several branches, use StringLike with a narrow pattern such as repo:my-org/my-repo:ref:refs/heads/release/. Never use a trust policy that checks only aud, and never repo:my-org/:*: that lets any repository in the organization, including ones with weak review, assume the role.
Adjunte una política de permisos con solo lo que necesita el job, como s3:PutObject sobre un bucket o una política de subida a ECR para un repositorio. Usar roles separados para build, deploy-staging y deploy-production reduce el alcance de un posible incidente, y los subjects basados en entornos le permiten exigir aprobación manual en producción.
Paso 3: Usarlo en el workflow
El job necesita permiso para solicitar el token:
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/gha-deploy-production
aws-region: us-east-1
role-session-name: gha-${{ github.run_id }}
- run: aws sts get-caller-identity
- run: aws s3 sync ./dist s3://my-bucket --delete
id-token: write no concede acceso de escritura a su repositorio; solo permite solicitar el token OIDC. Al establecerlo también se eliminan los permisos por defecto que no haya enumerado, de ahí contents: read. Fije aws-actions/configure-aws-credentials a un SHA, como se explica en securing GitHub Actions.
aws sts get-caller-identity es la comprobación más rápida de que el rol se ha asumido y de que la cuenta y el ARN del rol son los esperados.
Personalizar la claim subject
Por defecto, sub tiene el formato indicado arriba. Los propietarios de organizaciones y repositorios pueden personalizar qué claims se incluyen en sub mediante la API de configuración de OIDC, por ejemplo para incluir repository_id o job_workflow_ref. Incluir job_workflow_ref permite exigir que solo un workflow reutilizable concreto pueda asumir el rol:
"StringLike": {
"token.actions.githubusercontent.com:job_workflow_ref": "my-org/platform-workflows/.github/workflows/deploy.yml@refs/heads/main"
}
AWS admite un conjunto limitado de claves de claims en las claves de condición de IAM para este proveedor; consulte la documentación de IAM de AWS para ver la lista de claves admitidas, como aud, sub y job_workflow_ref, antes de depender de una de ellas.
Errores habituales
| Error | Causa | Solución |
|---|---|---|
Not authorized to perform sts:AssumeRoleWithWebIdentity | sub no coincide con la política de confianza | Muestre las claims del token o compare exactamente el nombre de la rama, el entorno y el repositorio, incluidas las mayúsculas |
Credentials could not be loaded | Falta id-token: write | Añada el permiso a nivel de job o de workflow |
No OpenIDConnect provider found | Falta el proveedor en esta cuenta o la URL es incorrecta | Créelo con la URL indicada arriba |
Funciona en main, falla en un PR | Las ejecuciones de PR tienen un sub diferente | Añada un rol independiente de solo lectura para pull_request, o no conceda acceso a AWS a los PR |
| Falla con environment | El job no tiene environment:, así que sub tiene la forma ref | Defina environment: en el job |
| La sesión caducó durante el job | La duración predeterminada es de 1 hora | Use role-duration-seconds hasta el máximo del rol, o divida el job |
Pull requests y forks
Los PR desde forks no pueden solicitar un token OIDC para la identidad de su repositorio, que es lo que se busca. En los PR del mismo repositorio, evite darles acceso de escritura a AWS: un PR puede editar el archivo del workflow, así que cualquier rol que un PR pueda asumir debe ser seguro para cualquiera con acceso de escritura al repositorio. Conceda a los roles de PR permisos de solo lectura, o use acceso plan únicamente para las comprobaciones de infraestructura.
Más allá de AWS
El mismo patrón funciona con la federación de identidad de carga de trabajo de GCP, las credenciales federadas de Azure, HashiCorp Vault y los registros de paquetes que admiten publicación de confianza (PyPI, npm y RubyGems). Migrar todos ellos a OIDC elimina sus secretos de larga duración.
Preguntas frecuentes
¿Sigo necesitando rotar algo?
No hay claves de acceso que rotar. Siga revisando las políticas de confianza, ya que ahora son su control de acceso.
¿Puedo usar OIDC con runners autoalojados?
Sí. GitHub emite el token para el job, independientemente de dónde se ejecute. El runner sigue necesitando acceso de red a AWS STS. Para runners de terceros, confirme que OIDC es compatible.
¿Qué contiene el token?
Claims como iss, aud, sub, repository, ref, environment, workflow y run_id. La documentación de GitHub los enumera todos.
¿Es seguro poner el ARN del rol en el workflow?
Sí. Un ARN es un identificador, no un secreto. La política de confianza decide quién puede usarlo.
Relacionado
Para reforzar la seguridad general de los workflows, lea cómo proteger GitHub Actions. Calcule el coste de sus despliegues con la calculadora de costes de EC2 y la calculadora de costes de S3. Los runners de compiler.dev pueden solicitar tokens OIDC de GitHub como cualquier otro runner, así que una política de confianza que escriba hoy seguirá funcionando si cambia dónde se ejecutan los jobs.
Relacionado
- ¿Qué es OIDC en GitHub Actions?OIDC permite a los workflows de GitHub Actions obtener credenciales de nube de corta duración sin secretos almacenados. Vea cómo funciona.
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.