Autenticación OIDC en GitHub Actions para Desplegar en AWS ECR sin Claves Estáticas

En este artículo quiero compartir cómo permitir que un workflow de GitHub Actions conecte con Amazon ECR para construir y publicar imágenes Docker sin usar credenciales estáticas. Emplearemos el mecanismo de federación OpenID Connect (OIDC), que ofrece tokens de corta duración firmados por GitHub. Así, los pipelines son más seguros y no tendrás que renovar Access Keys manualmente.

1. Registrar el proveedor OIDC en AWS

Para que AWS confíe en los tokens emitidos por GitHub, primero debes añadir el proveedor OpenID Connect:

1. Abre la consola de AWS IAM → Identity providers → Add provider.

2. Selecciona Provider type: OpenID Connect.

3. Rellena los campos de forma aproximada (usando valores ficticios):

   Provider URL:  https://token.actions.githubusercontent.com
   Audience:      sts.amazonaws.com
   GitHub Org:    <GITHUB_ORG>
   GitHub Repo:   <GITHUB_REPO>  (opcional)

4. Haz clic en Add provider.

¿Para qué sirve esto? AWS guardará que confía en ese emisor (token.actions.githubusercontent.com) y solo aceptará tokens cuyo público objetivo (aud) sea sts.amazonaws.com.

2. Crear un IAM Role que GitHub pueda asumir

Este role define quién y bajo qué condiciones puede obtener credenciales temporales para tu cuenta de AWS.

1. En IAM → Roles → Create role.

2. Elige Web identity y, en el desplegable, selecciona el proveedor que acabas de crear. El audience debe aparecer como sts.amazonaws.com.

3. Haz clic en Next: Permissions y adjunta una política que dé acceso a ECR, p. ej. un inline policy similar a:

   {
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage",
        "ecr:DescribeRepositories",
        "ecr:ListImages",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    }]
   }

4. Pulsa Next: Tags (puedes omitir) y luego Create role, por ejemplo con nombre GitHubActionsECRRole.

5. Selecciona el nuevo role y ves a la pestaña Trust relationships → Edit trust policy, y pega un documento como este, reemplazando los valores ficticios:

   {
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": [
            "repo:<GITHUB_ORG>/<GITHUB_REPO>:ref:refs/heads/dev",
            "repo:<GITHUB_ORG>/<GITHUB_REPO>:ref:refs/heads/release",
            "repo:<GITHUB_ORG>/<GITHUB_REPO>:ref:refs/heads/master",
            "repo:<GITHUB_ORG>/<GITHUB_REPO>:ref:refs/tags/*"
          ]
        }
      }
    }]
   }

¿Qué hace esta policy?

• Principal autoriza únicamente al OIDC provider de GitHub.
• Condition.StringEquals exige que el token apunte a AWS STS.
• Condition.StringLike.sub restringe el uso a las ramas dev, release, master y a cualquier tag.

3. Configurar el workflow de GitHub Actions

Ahora, en tu archivo por ej. .github/workflows/build.yml, cambia la sección de permisos y el paso de credenciales:

name: Build and Push to AWS ECR

on:
  push:
    branches:
      - dev
      - release
      - master
    tags:
      - 'v*'

jobs:
  build:
    # 1. Habilitar OIDC en este job
    permissions:
      id-token: write         # permite solicitar el token OIDC
      contents: read          # necesario para checkout

    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Configure AWS via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<AWS_ACCOUNT_ID>:role/GitHubActionsECRRole
          aws-region:    eu-west-1

      - name: Login to Amazon ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and Push Docker image
        run: |
          docker build -t my-app:${GITHUB_REF#refs/tags/v} .
          docker tag my-app:${GITHUB_REF#refs/tags/v} 123456789012.dkr.ecr.eu-west-1.amazonaws.com/my-app:${GITHUB_REF#refs/tags/v}
          docker push 123456789012.dkr.ecr.eu-west-1.amazonaws.com/my-app:${GITHUB_REF#refs/tags/v}

Puntos clave

• permissions.id-token: write permite al runner pedir el JWT a GitHub.
• No necesitas aws-access-key-id ni aws-secret-access-key.
• El rol se asume solo en tus ramas y tags definidos.

Pros y Contras

Conclusión

Usar OIDC para autenticar GitHub Actions frente a AWS ECR elimina la carga de gestionar Access Keys, refuerza la seguridad y da control granular sobre quién y cuándo tu pipeline puede publicar imágenes. Aunque la configuración inicial en IAM implica varios pasos, a medio plazo simplifica el mantenimiento y mejora la trazabilidad de accesos.

Happy coding! :D

Photo by Ian Taylor on Unsplash

Written with StackEdit.