Configuring OpenID Connect in Amazon Web Services

Use OpenID Connect within your workflows to authenticate with Amazon Web Services.

En este artículo

Nota:

Actualmente los ejecutores hospedados por GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in Amazon Web Services (AWS), without needing to store the AWS credentials as long-lived GitHub secrets.

This guide explains how to configure AWS to trust GitHub's OIDC as a federated identity, and includes a workflow example for the aws-actions/configure-aws-credentials that uses tokens to authenticate to AWS and access resources.

Nota:

La compatibilidad con notificaciones personalizadas para OIDC no está disponible en AWS.

Prerequisites

  • Para conocer los conceptos básicos de cómo GitHub usa OpenID Connect (OIDC) y su arquitectura y ventajas, consulta Acerca del fortalecimiento de seguridad con OpenID Connect.

  • Antes de proceder, debes planear tu estrategia de seguridad para garantizar que los tokens de acceso solo se asignen de forma predecible. Para controlar la forma en que el proveedor de servicios en la nube emite tokens de acceso, tendrá que definir al menos una condición, para que los repositorios no confiables no puedan solicitar tokens de acceso para los recursos en la nube. Para más información, consulta Acerca del fortalecimiento de seguridad con OpenID Connect.

  • Debes asegurarte de que el proveedor de nube puede acceder a los siguientes puntos de conexión OIDC:

    • https://HOSTNAME/_services/token/.well-known/openid-configuration
    • https://HOSTNAME/_services/token/.well-known/jwks

    Nota:

    You can restrict access to the OIDC endpoints by allowing only AWS IP address ranges.

    Nota:

    GitHub does not natively support AWS session tags.

Adding the identity provider to AWS

To add the GitHub OIDC provider to IAM, see the AWS documentation.

  • For the provider URL: Use https://HOSTNAME/_services/token
  • For the "Audience": Use sts.amazonaws.com if you are using the official action.

Configuring the role and trust policy

To configure the role and trust in IAM, see the AWS documentation Configure AWS Credentials for GitHub Actions and Configuring a role for GitHub OIDC identity provider.

Nota:

AWS Identity and Access Management (IAM) recommends that users evaluate the IAM condition key, token.actions.githubusercontent.com:sub, in the trust policy of any role that trusts GitHub’s OIDC identity provider (IdP). Evaluating this condition key in the role trust policy limits which GitHub actions are able to assume the role.

Edit the trust policy, adding the sub field to the validation conditions. For example:

JSON
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

If you use a workflow with an environment, the sub field must reference the environment name: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME. For more information, see Acerca del fortalecimiento de seguridad con OpenID Connect.

Nota:

Cuando los entornos se usan en flujos de trabajo o en directivas de OIDC, se recomienda agregar reglas de protección al entorno para mayor seguridad. Por ejemplo, puedes configurar reglas de implementación en un entorno para restringir qué ramas y etiquetas se pueden implementar en el entorno o acceder a secretos del entorno. Para más información, consulta Managing environments for deployment.

JSON
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

In the following example, StringLike is used with a wildcard operator (*) to allow any branch, pull request merge branch, or environment from the octo-org/octo-repo organization and repository to assume a role in AWS.

JSON
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

  1. Add permissions settings for the token.
  2. Use the aws-actions/configure-aws-credentials action to exchange the OIDC token (JWT) for a cloud access token.

Adding permissions settings

La ejecución de trabajo o flujo de trabajo requiere una configuración de permissions con id-token: write para permitir que el proveedor OIDC de GitHub pueda crear un token web JSON para cada ejecución. No podrás solicitar el token de identificador JWT de OIDC si el valor de permissions para id-token no está establecido en write, pero este valor no implica conceder acceso de escritura a ningún recurso, solo poder capturar y establecer el token de OIDC para una acción o paso para habilitar la autenticación con un token de acceso de corta duración. Cualquier configuración de confianza real se define mediante notificaciones de OIDC. Para obtener más información, consulte Acerca del fortalecimiento de seguridad con OpenID Connect.

El valor id-token: write permite solicitar JWT desde el proveedor OIDC de GitHub mediante uno de estos enfoques:

  • Con variables de entorno en el ejecutor (ACTIONS_ID_TOKEN_REQUEST_URL y ACTIONS_ID_TOKEN_REQUEST_TOKEN).
  • Con getIDToken() del kit de herramientas de Acciones.

Si necesita capturar un token de OIDC para un flujo de trabajo, el permiso se puede establecer en el nivel de flujo de trabajo. Por ejemplo:

YAML
permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

Si solo necesitas recuperar un token de OIDC para un trabajo único, entonces este permiso puede configurarse dentro de dicho job. Por ejemplo:

YAML
permissions:
  id-token: write # This is required for requesting the JWT

Puede que necesites especificar permisos adicionales aquí, dependiendo de los requisitos de tu flujo de trabajo.

Para flujos de trabajo reutilizables que son propiedad del mismo usuario, organización o empresa que el flujo de trabajo del autor de la llamada, se puede acceder al token de OIDC generado en el flujo de trabajo reutilizable desde el contexto del autor de la llamada. Para los flujos de trabajo reutilizables fuera de la empresa u organización, la configuración de permissions para id-token debe fijarse explícitamente en write en el nivel del flujo de trabajo del autor de la llamada o en el trabajo específico que llama al flujo de trabajo reutilizable. Esto garantiza que el token de OIDC generado en el flujo de trabajo reutilizable solo se pueda consumir en los flujos de trabajo de la persona que llama cuando está previsto.

Para más información, consulta Reusing workflows.

Requesting the access token

The aws-actions/configure-aws-credentials action receives a JWT from the GitHub OIDC provider, and then requests an access token from AWS. For more information, see the AWS documentation.

  • BUCKET-NAME: Replace this with the name of your S3 bucket.
  • AWS-REGION: Replace this with the name of your AWS region.
  • ROLE-TO-ASSUME: Replace this with your AWS role. For example, arn:aws:iam::1234567890:role/example-role
YAML
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "BUCKET-NAME"
  AWS_REGION : "AWS-REGION"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
        with:
          role-to-assume: ROLE-TO-ASSUME
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name: Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/

Further reading