GitHub Actions na AWS: OIDC elimina chaves longas, não o menor privilégio

Para autenticar o GitHub Actions na AWS sem guardar chaves de acesso permanentes, cadastre o provedor OIDC do GitHub no IAM, crie uma função com confiança restrita e use a ação configure-aws-credentials em um job com id-token: write. A ação apresenta o token do job ao AWS STS e recebe credenciais temporárias para a função.

A política de confiança da função decide quais origens podem assumi-la; a política de permissões decide o que as credenciais poderão fazer. A condição sobre repositório e branch autoriza qualquer job que produza o subject correspondente, não apenas um arquivo de workflow específico. Por isso, retirar as chaves dos segredos do GitHub não dispensa o menor privilégio no IAM.

Cadastre o provedor na conta AWS

Em IAM, abra Provedores de identidade e adicione um provedor OpenID Connect com a URL https://token.actions.githubusercontent.com e a audiência sts.amazonaws.com. Crie a função na mesma conta, escolhendo esse provedor como principal federado. Para essa configuração usual, a ação solicita a audiência sts.amazonaws.com por padrão; se você definir outra audiência no workflow, o cadastro e a política de confiança também terão de corresponder a ela.

Separe desde já as duas políticas da função. A relação de confiança permitirá a chamada sts:AssumeRoleWithWebIdentity apenas ao subject escolhido. A política de permissões deve conter somente as ações AWS e os recursos exigidos pela implantação: enviar objetos a um destino específico no S3, por exemplo, não justifica acesso administrativo à conta. Você pode começar pela verificação da identidade assumida e acrescentar as permissões de implantação depois.

Restrinja a relação de confiança

Este exemplo hipotético autoriza uma execução do repositório MEU_REPO, da organização MINHA_ORG, na branch main, sem GitHub Environment. Substitua ACCOUNT_ID pelo ID da conta AWS e ID_ORG e ID_REPO pelos IDs numéricos reais do proprietário e do repositório. Ajuste o subject ao formato efetivamente emitido pelo seu repositório antes de salvar a política:

{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Federated":"arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"},"Action":"sts:AssumeRoleWithWebIdentity","Condition":{"StringEquals":{"token.actions.githubusercontent.com:aud":"sts.amazonaws.com","token.actions.githubusercontent.com:sub":"repo:MINHA_ORG@ID_ORG/MEU_REPO@ID_REPO:ref:refs/heads/main"}}}]}

Principal.Federated identifica o provedor cadastrado na conta. A condição aud exige que o token seja destinado ao STS, enquanto sub combina o repositório autorizado com o contexto da execução. Com StringEquals, outro repositório ou outra branch não corresponde ao valor completo. Evite trocar essa comparação por um padrão que aceite mais origens do que a implantação exige.

Essa confiança não identifica o nome nem o caminho do arquivo de workflow. Se outro job do mesmo repositório puder solicitar um token na branch main, ele poderá satisfazer a condição acima. Para limitar também o workflow, inclua essa identidade em uma configuração apropriada do subject e adapte a condição do IAM ao valor resultante.

Ajuste o subject para branch ou ambiente

O formato padrão do sub muda com o contexto. A referência OIDC do GitHub mostra que um job sem environment executado na branch usa o sufixo :ref:refs/heads/main; com environment, usa :environment:NOME; e um evento pull_request sem environment usa :pull_request. Repositórios criados depois de 15 de julho de 2026 usam, por padrão, IDs imutáveis junto aos nomes do proprietário e do repositório. Repositórios anteriores podem manter o formato sem esses IDs, salvo quando aderem à mudança ou passam por uma alteração que a ativa.

Se o job declarar environment: producao, a política de exemplo para a branch main deixará de corresponder ao token. Para autorizar esse ambiente, substitua o valor de sub por repo:MINHA_ORG@ID_ORG/MEU_REPO@ID_REPO:environment:producao, preservando ou retirando os IDs conforme o formato real do repositório. Proteja o ambiente no GitHub e restrinja quais branches podem implantá-lo: o subject padrão baseado em environment não contém a branch no mesmo valor.

Se sua exigência combina ambiente, branch e identidade do workflow, planeje a personalização do subject antes de ampliar a confiança no IAM. Uma condição baseada apenas em :environment:producao aceita qualquer job daquele repositório que consiga usar esse ambiente. Os nomes e IDs devem ser copiados da configuração real do GitHub, pois uma diferença no subject faz a assunção falhar.

Execute um workflow mínimo

Salve o exemplo hipotético abaixo em .github/workflows/oidc.yml. Ele usa sintaxe JSON válida em YAML, dispara por push em main e executa a versão v6.3.0 da ação. Substitua ACCOUNT_ID e NOME_DA_FUNCAO; a região sa-east-1 é apenas um exemplo para a conta de destino.

{"name":"Validar OIDC AWS","on":{"push":{"branches":["main"]}},"jobs":{"validar":{"runs-on":"ubuntu-latest","permissions":{"id-token":"write"},"steps":[{"uses":"aws-actions/[email protected]","with":{"role-to-assume":"arn:aws:iam::ACCOUNT_ID:role/NOME_DA_FUNCAO","aws-region":"sa-east-1"}},{"run":"aws sts get-caller-identity"}]}}}

A permissão id-token: write permite ao job pedir um token OIDC; ela não concede, sozinha, ações sobre recursos AWS. O primeiro passo troca o token pelas credenciais da função, e o segundo retorna a conta e o ARN da identidade assumida. Nenhuma access key permanente aparece no arquivo. Se você acrescentar checkout ou outros passos que usem GITHUB_TOKEN, conceda a eles apenas as permissões necessárias.

Teste o acesso permitido e as recusas

Execute primeiro o job autorizado em main, sem environment, e confira se get-caller-identity retorna a conta e a sessão da função esperadas. Esse sucesso verifica a combinação de provedor, audiência, subject e ARN, mas ainda não demonstra que as outras origens são recusadas. Faça então tentativas controladas com o mesmo ARN de função:

1. Em outra branch do mesmo repositório, execute uma cópia do workflow com disparo habilitado para essa branch. A etapa configure-aws-credentials deve falhar antes de get-caller-identity.
2. Em outro repositório sob seu controle, execute o job apontando para a mesma função. A diferença no subject deve impedir sts:AssumeRoleWithWebIdentity.
3. Com a política ainda limitada à branch, adicione environment: producao ao job autorizado. A mudança do formato do subject deve causar recusa. Se a política passar a autorizar producao, repita o teste com outro ambiente ao qual o job possa chegar.

Confira nos logs que cada recusa ocorreu na obtenção das credenciais, e não por erro de sintaxe ou por um job que nem chegou a executar. Para auditar a assunção autorizada, o histórico de eventos do CloudTrail permite procurar sts.amazonaws.com e examinar AssumeRoleWithWebIdentity e GetCallerIdentity. Depois de validar a fronteira de entrada, mantenha na função apenas as permissões AWS exigidas pelos comandos reais do workflow.

Leia também:

• GitHub Actions troca o total exato por “2.500+” — ajuste suas consultas
• Segredo no Docker não pertence ao ENV — monte o arquivo só onde ele é usado
• Agente de IA ganhou uma VM própria — isole rede, segredos e estado na AWS