Configurando o OpenID Connect no Amazon Web Services

Use o OpenID Connect dentro de seus fluxos de trabalho para efetuar a autenticação com Amazon Web Services.

Neste artigo

Visão geral

O OpenID Connect (OIDC) permite que seus fluxos de trabalho de GitHub Actions acessem os recursos na Amazon Web Services (AWS), sem precisar armazenar as credenciais AWS como segredos de GitHub de longa duração.

Este guia explica como configurar a AWS para confiar no OIDC do GitHub como uma identidade federada e inclui um exemplo de fluxo de trabalho para o aws-actions/configure-aws-credentials que usa tokens para autenticação na AWS e acesso aos recursos.

Observação

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

Pré-requisitos

  • Para saber os conceitos básicos de como o GitHub usa o OIDC (OpenID Connect), além da arquitetura e dos benefícios, confira 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 OpenID Connect.

Adicionando o provedor de identidade ao AWS

Para adicionar o provedor OIDC do GitHub ao IAM, confira a documentação da AWS.

  • Para a URL do provedor: use https://token.actions.githubusercontent.com
  • Em "Público-alvo": use sts.amazonaws.com se você estiver usando a ação oficial.

Configurando a função e a política de confiança

Para configurar a função e a política de confiança no IAM, consulte a documentação da AWS Configurar credenciais da AWS para ações do GitHub e Configurando uma função para o provedor de identidade OIDC do GitHub.

Observação

O Gerenciamento de Identidades e Acesso (IAM) do AWS recomenda que os usuários avaliem a chave de condição do IAM, token.actions.githubusercontent.com:sub, na política de confiança de qualquer função que confie no provedor de identidade (IdP) OIDC do GitHub. A avaliação dessa chave de condição na política de confiança de função limita as ações do GitHub que podem assumir a função.

Edite a política de confiança, adicionando o campo sub às condições de validação. Por exemplo:

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"
  }
}

Se você usar um fluxo de trabalho com um ambiente, o campo sub deverá fazer referência ao nome do ambiente: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME. Para saber mais, confira Referência do 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 Gerenciar ambientes para implantação.

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

No exemplo a seguir, StringLike é usado com um operador curinga (*) para permitir que qualquer branch, branch de mesclagem de solicitação de pull ou ambiente da organização octo-org/octo-repo e do repositório assuma uma função na 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"
                }
            }
        }
    ]
}

Atualizar o seu fluxo de trabalho de GitHub Actions

Para atualizar seus fluxos de trabalho para o OIDC, você deverá fazer duas alterações no seu YAML:

  1. Adicionar configurações de permissões para o token.
  2. Use a ação aws-actions/configure-aws-credentials para trocar o token OIDC (JWT) por um token de acesso à nuvem.

Adicionando configurações de permissões

A execução do trabalho ou do fluxo de trabalho requer uma configuração permissions com id-token: write para permitir que o provedor OIDC do GitHub crie um JSON Web Token para cada execução.

Observação

A configuração de id-token: write nas permissões do fluxo de trabalho não dá ao fluxo de trabalho permissão para modificar ou gravar em nenhum recurso. Em vez disso, só permite que o fluxo de trabalho solicite (busque) e use (defina) um token OIDC para uma ação ou etapa. Esse token é usado para autenticar com serviços externos usando um token de acesso de curta duração.

Para obter informações detalhadas sobre permissões necessárias, exemplos de configuração e cenários avançados, confira Referência do OpenID Connect.

Solicitando o token de acesso

A ação aws-actions/configure-aws-credentials recebe um JWT do provedor OIDC do GitHub e solicita um token de acesso da sua instância da AWS. Para obter mais informações, confira a documentação da AWS.

  • BUCKET-NAME: substitua pelo nome do bucket de S3.
  • AWS-REGION: substitua pelo nome da sua região da AWS.
  • ROLE-TO-ASSUME: substitua isso por sua função da AWS. Por exemplo, 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@v5
      - 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 }}/

Leitura adicional