Configuring OpenID Connect in Amazon Web Services

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

Neste artigo

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.

Observação

O suporte para declarações personalizadas de OIDC não está disponível na AWS.

Prerequisites

  • Para saber os conceitos básicos de como o GitHub usa o OIDC (OpenID Connect), além da arquitetura e dos benefícios, confira Sobre o enrijecimento de segurança com o OpenID Connect.

  • Antes de prosseguir, você deve planejar sua estratégia de segurança para garantir que os tokens de acesso sejam atribuídos apenas de forma previsível. Para controlar como o provedor de nuvem emite os tokens de acesso, você precisa definir, pelo menos, uma condição, para que os repositórios não confiáveis não possam solicitar tokens de acesso aos seus recursos de nuvem. Para saber mais, confira Sobre o enrijecimento de segurança com o OpenID Connect.

  • Se você estiver seguindo este guia sobre o GHE.com, entenda que você precisa substituir alguns valores na documentação a seguir. Confira Sobre o enrijecimento de segurança com o OpenID Connect.

Adding the identity provider to AWS

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

  • For the provider URL: Use http://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 Configure AWS Credentials for GitHub Actions and Configuring a role for GitHub OIDC identity provider.

Observação

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": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com: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 Sobre o enrijecimento de segurança com o OpenID Connect.

Observação

Quando os ambientes são usados em fluxos de trabalho ou em políticas OIDC, recomendamos adicionar regras de proteção ao ambiente para segurança adicional. Por exemplo, você pode configurar regras de implantação em um ambiente para restringir quais ramificações e tags podem ser implantadas no ambiente ou acessar segredos de ambiente. Para saber mais, confira Managing environments for deployment.

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com: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

A execução do trabalho ou do fluxo de trabalho requer uma permissions configuração para id-token: write permitir que o provedor OIDC do GitHub crie um JSON Web Token para cada execução. Você não poderá solicitar o token de ID JWT do OIDC se as permissions para id-token não estiverem definidas como write; no entanto, esse valor não implica a concessão de acesso para gravação a nenhum recurso, apenas a possibilidade de buscar e definir o token OIDC para uma ação ou etapa para habilitar a autenticação com um token de acesso de curta duração. Qualquer configuração de confiança real é definida usando declarações OIDC; para obter mais informações, confira Sobre o enrijecimento de segurança com o OpenID Connect.

A configuração id-token: writepermite que o JWT seja solicitado do provedor OIDC do GitHub usando uma destas abordagens:

  • Usando variáveis de ambiente no executor (ACTIONS_ID_TOKEN_REQUEST_URL e ACTIONS_ID_TOKEN_REQUEST_TOKEN).
  • Usando getIDToken() por meio do kit de ferramentas do Actions.

Se você precisar buscar um token OIDC para um fluxo de trabalho, a permissão poderá ser definida no nível do fluxo de trabalho. Por exemplo:

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

Se você só precisa obter um token OIDC para um único trabalho, essa permissão poderá ser definida dentro desse trabalho. Por exemplo:

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

Você pode precisar especificar permissões adicionais aqui, dependendo das necessidades do seu fluxo de trabalho.

Para fluxos de trabalho reutilizáveis pertencentes ao mesmo usuário, organização ou empresa que o fluxo de trabalho do chamador, o token OIDC gerado no fluxo de trabalho reutilizável pode ser acessado no contexto do chamador. Para fluxos de trabalho reutilizáveis fora de sua empresa ou organização, a configuração permissions para id-token deve ser explicitamente definida como write no nível do fluxo de trabalho do chamador ou no trabalho específico que chama o fluxo de trabalho reutilizável. Isso garante que o token OIDC gerado no fluxo de trabalho reutilizável só tenha permissão para ser consumido nos fluxos de trabalho do chamador quando pretendido.

Para saber mais, confira 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