Saltar al contenido

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

  1. El workflow solicita un token de ID a GitHub. El token indica qué repositorio, rama y entorno ejecutan el job.
  2. El job presenta el token a AWS STS con AssumeRoleWithWebIdentity.
  3. 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

ErrorCausaSolución
Not authorized to perform sts:AssumeRoleWithWebIdentitysub no coincide con la política de confianzaMuestre 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 loadedFalta id-token: writeAñada el permiso a nivel de job o de workflow
No OpenIDConnect provider foundFalta el proveedor en esta cuenta o la URL es incorrectaCréelo con la URL indicada arriba
Funciona en main, falla en un PRLas ejecuciones de PR tienen un sub diferenteAñada un rol independiente de solo lectura para pull_request, o no conceda acceso a AWS a los PR
Falla con environmentEl job no tiene environment:, así que sub tiene la forma refDefina environment: en el job
La sesión caducó durante el jobLa duración predeterminada es de 1 horaUse 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.

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.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis