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.
Prerequisites
-
Para aprender los conceptos básicos de cómo GitHub utiliza OpenID Connect (OIDC) y su arquitectura y beneficios, consulta la sección "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 la que tu proveedor de servicios en la nube emite tokens de acceso, debes define por lo menos una condición para que los repositorios no confiables no puedan solicitar tokens de acceso para tus recursos en la nube. Para obtener más información, consulta la sección "Configurar la relación de confianza de OIDC con la nube".
Adding the identity provider to AWS
To add the GitHub OIDC provider to IAM, see the AWS documentation.
- For the provider URL: Use
https://token.actions.githubusercontent.com
- 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 for "Assuming a Role" and "Creating a role for web identity or OpenID connect federation".
Edit the trust relationship to add the sub
field to the validation conditions. For example:
"Condition": {
"ForAllValues:StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
}
}
Updating your GitHub Actions workflow
To update your workflows for OIDC, you will need to make two changes to your YAML:
- Add permissions settings for the token.
- Use the
aws-actions/configure-aws-credentials
action to exchange the OIDC token (JWT) for a cloud access token.
Adding permissions settings
The job or workflow run requires a permissions
setting with id-token: write
. You won't be able to request the OIDC JWT ID token if the permissions
setting for id-token
is set to read
or none
.
The id-token: write
setting allows the JWT to be requested from GitHub's OIDC provider using one of these approaches:
- Using environment variables on the runner (
ACTIONS_ID_TOKEN_REQUEST_URL
andACTIONS_ID_TOKEN_REQUEST_TOKEN
). - Using
getIDToken()
from the Actions toolkit.
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
Puede que necesites especificar permisos adicionales aquí, dependiendo de los requisitos de tu flujo de trabajo.
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.
<example-bucket-name>
: Add the name of your S3 bucket here.<role-to-assume>
: Replace the example with your AWS role.<example-aws-region>
: Add the name of your AWS region here.
# 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
contents: read # This is required for actions/checkout
jobs:
S3PackageUpload:
runs-on: ubuntu-latest
steps:
- name: Git clone the repository
uses: actions/checkout@v3
- name: configure aws credentials
uses: aws-actions/configure-aws-credentials@v1
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 }}/