Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.
Información general
OpenID Connect (OIDC) permite que tus flujos de trabajo de GitHub Actions accedan a los recursos de Amazon Web Services (AWS) sin necesidad de almacenar las credenciales de AWS como secretos de GitHub de larga duración.
En esta guía se explica cómo configurar AWS para que confíe en el OIDC de GitHub como una entidad federada y se incluye un ejemplo de flujo de trabajo para aws-actions/configure-aws-credentials
en el que se usan tokens para autenticarse en AWS y acceder a los recursos.
Nota: La compatibilidad con notificaciones personalizadas para OIDC no está disponible en AWS.
Requisitos previos
-
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 obtener más información, vea «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: Puedes restringir el acceso a los puntos de conexión de OIDC al permitir solo intervalos de direcciones IP de AWS.
Nota: GitHub no admite de forma nativa etiquetas de sesión de AWS.
Agregar el proveedor de identidad a AWS
Para agregar el proveedor de OIDC de GitHub a IAM, vea la documentación de AWS.
- Para la dirección URL del proveedor: usa
https://HOSTNAME/_services/token
- Para "Público": utilice
sts.amazonaws.com
si usa la acción oficial.
Configurar el rol y política de confianza
Para configurar el rol y la confianza en IAM, consulte la documentación de AWS "Configuración de credenciales de AWS para Acciones de GitHub" y "Configuración de un rol para el proveedor de identidades de OIDC de GitHub".
Nota: AWS Identity and Access Management (IAM) recomienda que los usuarios evalúen la clave de condición de IAM, token.actions.githubusercontent.com:sub
, en la directiva de confianza de cualquier rol que confíe en el proveedor de identidades (IdP) OIDC GitHub. Evaluar esta clave de condición en los límites de la directiva de confianza de rol que las acciones de GitHub pueden asumir el rol.
Edita la directiva de confianza para agregar el campo sub
a las condiciones de validación. Por ejemplo:
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
}
}
Si usas un flujo de trabajo con un ambiente, el campo sub
debe hacer referencia al nombre del ambiente: repo:OWNER/REPOSITORY:environment:NAME
. Para obtener más información, vea «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 obtener más información, vea «Utilizar ambientes para el despliegue».
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod"
}
}
En el ejemplo siguiente, StringLike
se usa con un operador comodín (*
) para permitir que cualquier rama, rama de combinación de solicitudes de incorporación de cambios o entorno del repositorio y la organización octo-org/octo-repo
asuman un rol en AWS.
{ "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" } } } ] }
{
"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"
}
}
}
]
}
Actualizar tu flujo de trabajo de GitHub Actions
Para actualizar tus flujos de trabajo para ODIC, necesitarás hacer dos cambios a tu YAML:
- Agregar ajustes de permisos para el token.
- Use la acción
aws-actions/configure-aws-credentials
para intercambiar el token de OIDC (JWT) por un token de acceso a la nube.
Agregar ajustes de permisos
La ejecución del trabajo o del flujo de trabajo necesita una configuración permissions
con id-token: write
. No podrá solicitar el token de identificador JWT de OIDC si el valor permissions
de id-token
está establecido en read
o none
.
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
yACTIONS_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:
permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout
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 solo job, entonces este permiso puede configurarse dentro de dicho job. Por ejemplo:
permissions: id-token: write # This is required for requesting the JWT
permissions:
id-token: write # This is required for requesting the JWT
Solicitar el token de acceso
La acción aws-actions/configure-aws-credentials
recibe un JWT del proveedor de OIDC de GitHub y luego solicita un token de acceso a AWS. Para más información, vea la documentación de AWS.
<example-bucket-name>
: agregue aquí el nombre del cubo de S3.<role-to-assume>
: reemplace el ejemplo por el rol de AWS.<example-aws-region>
: agregue aquí el nombre de la región de AWS.
# 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 : "<example-bucket-name>" AWS_REGION : "<example-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@v3 with: role-to-assume: arn:aws:iam::1234567890:role/example-role 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 }}/
# 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 : "<example-bucket-name>"
AWS_REGION : "<example-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@v3
with:
role-to-assume: arn:aws:iam::1234567890:role/example-role
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 }}/