O blog da AWS

Como utilizar IAM Roles para conectar o GitHub Actions na AWS

Por David, Arquiteto de Soluções Senior na AWS.

22 de maio de 2023: atualizamos a publicação para refletir a distinção entre maiúsculas e minúsculas no IDP inserido: https://token.actions.githubusercontent.com. O IDP criado nesta postagem deve ser inserido em letras minúsculas na postagem.

12 de dezembro de 2024: atualizamos o blog post para refletir que não é mais necessário especificar um thumbprint ao criar um provedor OIDC: A AWS faz uma conexão segura com provedores de identidade (IdPs) do OIDC utilizando a biblioteca de root certificate authorities (CAs).

Esse Blog Post foi escrito por David Rowe, Senior Solutions Architect at AWS e atualizado por Eduardo Inoue e Liz Menichetti.

Você já quis fazer uma change em uma conta da Amazon Web Services (AWS) depois de atualizar um repositório do GitHub ou implantar atualizações em uma aplicação na AWS após fazer commit num repositório sem o uso de access keys de um usuário do AWS Identity and Access Management (IAM)? Se você configurar um provedor de identidade (IdP) do OpenID Connect (OIDC) dentro de uma conta da AWS, poderá utilizar roles do IAM e credenciais de curto prazo, o que elimina a necessidade de access keys do usuário do IAM.

Nesse blog post vamos compartilhar as etapas necessárias para configurar um repositório específico do GitHub para assumir uma role específica em uma conta AWS para realizar changes. Você vai aprender como criar uma conexão confiável do OIDC que tenha como escopo um repositório específico do GitHub e também como mapear o repositório para uma role do IAM na sua conta. Você vai criar uma conexão OIDC, uma role do IAM e a relação de confiança de duas maneiras: com o Console da AWS e com o AWS Command Line Interface (AWS CLI).

Esse blog foca na criação de um provedor de identidade OIDC no IAM para o GitHub e demonstra como autorizar o acesso a uma conta da AWS a partir de uma branch e repositório específicos. Você pode utilizar provedores de identidade OIDC para workflows compatíveis com o padrão OpenID Connect.

Pré-requisitos

Para acompanhar esse blog você deve ter os seguintes pré-requisitos:

  • Permissão de criar um novo arquivo de workflow do GitHub Actions no diretório .github/workflows/ em uma branch de um repositório do GitHub.
  • Uma conta AWS
  • Acesso às seguintes permissões do IAM na conta:
    • Criar um OpenID Connect IdP
    • Criar um IAM role e atachar uma política IAM

Visão geral da solução

O GitHub é um provedor externo independente da AWS. Para usar o GitHub como um IdP do OIDC, você precisará concluir quatro etapas para acessar os recursos da AWS a partir do seu repositório do GitHub. Em seguida, na quinta e última etapa, você utilizará o AWS CloudTrail para auditar a role que você criou e usou nas etapas 1 a 4.

  1. Crie um provedor OIDC na sua conta da AWS. Essa é uma relação de confiança que permite que o GitHub se autentique e seja autorizado a realizar ações na sua conta.
  2. Crie um IAM role em sua conta. Em seguida, você definirá a relação de confiança do role com as partes específicas da sua organização como repositório e branch para que o GitHub assuma e execute ações específicas.
  3. Atribua um nível mínimo de permissões da role.
  4. Crie um arquivo de workflow do GitHub Actions no seu repositório que possa invocar ações na sua conta.
  5. Audite o uso da role com os logs do Amazon CloudTrail.

Etapa 1: Crie um provedor OIDC em sua conta

A primeira etapa desse processo é criar um provedor OIDC que você utilizará na trust policy para a role IAM usada nesta ação.

Para criar um provedor OIDC para o GitHub (console):

  1. Abra o console do IAM.
  2. No menu de navegação à esquerda, escolha Identity Provider.
  3. No painel Identity Provider, escolha Add provider.
  4. Em Provider Type escolha OpenID Connect.
  5. (Até o momento da publicação desse blogpost) Em Provider URL, insira a URL do IdP do GitHub OIDC para esta solução: https://token.actions.githubusercontent.com
  6. Em Audience, insira sts.amazonaws.com. Isso permitirá que a API do AWS Security Token Service (AWS STS) seja chamada por esse IdP.
  7. (Opcional) Para Adicionar tags, você pode adicionar pares de chave-valor para ajudá-lo a identificar e organizar seus IdPs. Para saber mais sobre a Tags de IDPs do IAM OIDC, consulte Tagging OpenID Connect (OIDC) IdPs.
  8. Verifique as informações que você inseriu. Seu console deve corresponder à captura de tela na Figura 1. Após a verificação, escolha Add provider.Nota: cada provider possui um relacionamento um-para-um com um IdP externo. Se quiser adicionar mais IdPs à sua conta, você pode repetir esse processo.

  9. Figura 1: Etapas para configurar o provedor de identidade

  10. Depois de voltar na página Identity providers, você vai ver seu novo IdP conforme mostrado na Figura 2. Selecione seu provedor para ver suas propriedades e anote o Amazon Resource Name (ARN). Você usará o ARN posteriormente neste blog. O ARN terá uma aparência semelhante à seguinte:

arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com

Figura 2: Listando provedor de identidade

Para criar um provedor OIDC para o GitHub (AWS CLI):

Você pode adicionar o GitHub como um IdP na sua conta com um único comando da AWS CLI. O código a seguir pode executar as etapas anteriores descritas para o console, com os mesmos resultados.

aws iam create-open-id-connect-provider --url "https://token.actions.githubusercontent.com" --client-id-list 'sts.amazonaws.com'

Ambos os métodos anteriores vão adicionar um IdP à sua conta. Você pode ver o provedor na página Identity Provider no console do IAM.

Etapa 2: criar uma role do IAM e definir o escopo da trust policy

Você pode criar uma role do IAM com o console do IAM ou com o AWS CLI. Se você optar por criar através do AWS CLI, você precisa definir o escopo da Trust Relationship Policy antes de criar a role.

O procedimento para criar a role do IAM e definir o escopo da Trust Policy pode ser encontrado no Guia do usuário do AWS Identity and Access Management. Para obter instruções detalhadas sobre como configurar uma role consulte a documentação Como configurar uma role para o provedor de identidade OIDC do GitHub.

Para criar uma IAM role (console do IAM):

  1. No console do IAM, na tela Identity Provider, escolha o botão Assign role para o IdP recém-criado.

    Figura 3: Atribuir uma role ao ao provedor de identidade

  2. Na caixa Assign role escolha Criar uma nova role, em seguida, escolha Avançar, conforme mostrado na figura a seguir.

    Figura 4: Crie uma role na página do provedor de identidade

  3. A página Criar role apresenta algumas opções. A identidade da Web já está selecionada como entidade confiável e o campo Identity Provider está preenchido com seu IdP. No campo Audiência, selecione sts.amazonaws.com, no campo GitHub Organization preencha com o nome da sua organização do GitHub e, em seguida, selecione Avançar.
  4. Na página Permissões, selecione Avançar. Para esta demonstração, você não vai adicionar permissões à sua IAM role.
  5. Na página Name, review, and create, adicione um nome para a nova IAM role. Para esta demo digite GitHubAction-AssumeRoleWithAction. Opcionalmente, adicione uma descrição.
  6. (Opcional) Na seção de Tags, adicione uma tag.
  7. Para criar a role, clique no botão Create role.

Em seguida, você definirá o escopo da IAM role trust policy para uma única organização, repositório e branch do GitHub.

Definição do escopo da trust policy (console do IAM)

  1. No console do IAM, abra a role que você acabou de criar e clique em Edit trust policy.
  2. Na página Edit trust policy, modifique a trust policy para permitir que sua organização, repositório e ramificação exclusivos do GitHub assumam a role <ExampleBranch>. Este exemplo confia na organização do GitHub <aws-samples>, no repositório <EXAMPLEREPO> e no branch <ExampleBranch>. Atualize o ARN federado com o ARN do IdP do GitHub que você copiou anteriormente.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "<arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:sub": "repo: <aws-samples/EXAMPLEREPO>:ref:refs/heads/<ExampleBranch>",
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Criar uma role (AWS CLI)

No AWS CLI, use o exemplo de trust policy mostrado acima para o console. Essa política foi criada para limitar o acesso a uma organização, repositório e branch definidos do GitHub.

  1. Crie e salve um arquivo JSON com a política de exemplo em seu computador local com o nome de arquivo trustPolicyForGitHuboIDC.json.
  2. Execute o comando a seguir para criar a role.

aws iam create-role --role-name githubaction-assumeRoleWithAction --assume-role-policy-document file://C:\policies\trustpolicyforGitHubOIDC.json

Para obter mais detalhes sobre como criar uma role do OIDC com a AWS CLI, consulte Criação de uma role para acesso federado (AWS CLI).

Etapa 3: atribuir um nível mínimo de permissões à role

Neste exemplo, você não vai adicionar permissões à role do IAM e sim assumir a role e chamar STS getCallerIdentity para demonstrar uma ação do GitHub que assume a role da AWS.

Se estiver interessado em realizar ações adicionais na sua conta, você pode adicionar permissões à role que você criou, GitHubAction-AssumeRoleWithAction. As ações comuns para workflows incluem chamar funções do AWS Lambda ou enviar arquivos para um bucket do Amazon Simple Storage Service (Amazon S3). Para obter mais informações sobre como utilizar o IAM para aplicar permissões, consulte a documentação da AWS: Políticas e permissões no IAM.

Etapa 4: criar uma ação do GitHub para executar AWS CLI

As ações do GitHub são definidas como métodos que você pode usar para automatizar, personalizar e executar seus workflows de desenvolvimento de software no GitHub. A ação do GitHub que você vai criar será autenticada na sua conta como a role que você criou na Etapa 2: Criar uma role do IAM e definir o escopo da trust policy.

Para criar uma ação do GitHub para executar a AWS CLI:

  1. Crie um arquivo de workflow básico, como main.yml, no diretório .github/workflows do seu repositório. Este exemplo de workflow vai assumir o role GitHubAction-AssumeRoleWithAction para executar a ação aws sts get-caller-identity. Seu repositório pode ter vários workflows, cada um executando conjuntos distintos de tarefas. Depois que o GitHub for autenticado na role com o workflow, você poderá utilizar os comandos da AWS CLI em sua conta.
  2. Copie e cole o exemplo de workflow a seguir no arquivo.
# Esse é um workflow básico para ajudar você a começar a usar o Actions
name:Connect to an AWS role from a GitHub repository

# Controla quando a ação será executada. Invoca o workflow em eventos push, mas somente para o branch principal
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

env:
  
  AWS_REGION : <"us-east-1"> #Altere para refletir sua região

# A permissão pode ser adicionada no nível do job ou do workflow  
permissions:
      id-token: write   # Isso é necessário para solicitar o JWT
      contents: read    # Isso é necessário para ações/checkout
jobs:
  AssumeRoleAndCallIdentity:
    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.7.0
        with:
          role-to-assume: <arn:aws:iam::111122223333:role/GitHubAction-AssumeRoleWithAction> #altere para refletir a ARN da sua IAM role
            role-session-name: GitHub_to_AWS_via_FederatedOIDC
          aws-region: ${{ env.AWS_REGION }}
      # Olá da AWS: WhoAmI
      - name: Sts GetCallerIdentity
        run: |
          aws sts get-caller-identity
 3. Modifique o workflow para refletir as informações da sua conta AWS:
  • AWS_REGION: insira a região da AWS para seus recursos AWS.
  • role-to-assume: substitua o ARN pelo ARN da role AWS GitHubAction que você criou anteriormente.

No workflow de exemplo, se houver um push ou pull na branch “principal” do repositório, a ação que você acabou de criar será executada.

A Figura 5 mostra as etapas do workflow nas quais o GitHub faz o seguinte:

  • Autentica a role do IAM com o IdP do OIDC na região que foi definida no arquivo de workflow na etapa configure aws credentials.
  • aws sts get-caller-identity na etapa Olá da AWS: WhoAmI. Execute GetCallerIdentity da AWS CLI.

Figura 5: Resultados da ação do GitHub

Etapa 5: auditar o uso da role: consultar os registros do CloudTrail

A etapa final consiste em visualizar os logs do AWS CloudTrail em sua conta para auditar o uso dessa role.

Para ver os logs de eventos da ação do GitHub:

  1. No Console da AWS, abra o CloudTrail e escolha Event History.
  2. Na lista de Lookup attributes, escolha Event source.
  3. Na barra de pesquisa, digite sts.amazonaws.com

    Figura 6: Encontre o histórico de eventos no CloudTrail

  4. Você vai encontrar os eventos GetCallerIdentity e AssumeRoleWithWebIdentity conforme mostrado na Figura 6. O evento GetCallerIdentity é a etapa Olá da AWS no arquivo de workflow do GitHub. Esse evento mostra o workflow conforme ele chama aws sts get-caller-identity. O evento AssumeRoleWithWebIdentity mostra o GitHub autenticando e assumindo o role do IAM GitHubAction-AssumeRoleWithAction.

Opcionalmente você também pode ver um evento por vez.

Para visualizar o evento da API GetCallerIdentity:

  1. Na lista de Lookup attributes, escolha User name.
  2. Na barra de pesquisa, insira o role-session-name, definido no arquivo do workflow em seu repositório. Esse não é o nome do role do IAM, porque esse role-session-name está definido na linha 29 do exemplo do workflow. No exemplo do workflow deste blog, o role-session-name é GitHub_to_AWS_via_FederatedOIDC.
  3. Agora você pode visualizar o primeiro evento no histórico do CloudTrail.

Figura 7: Visualize no CloudTrail a chamada de API get caller identity.

Para visualizar o evento AssumeRoleWithWebIdentity

  1. Na lista de Lookup attributes, escolha User name.
  2. Na barra de pesquisa, insira a organização do GitHub, o repositório e a branch que estão definidos na trust policy da role do IAM. No exemplo descrito anteriormente, o nome do usuário é repo:aws-samples/EXAMPLE:ref:refs/heads/main.
  3. Agora você pode ver o evento individual no histórico do CloudTrail.

Figura 8: Visualize a chamada de API assume role no CloudTrail.

Conclusão

Ao utilizar roles do IAM com provedores de identidade do OIDC, você tem uma forma confiável de fornecer acesso aos seus recursos da AWS. O GitHub e outros provedores do OIDC podem gerar credenciais de segurança temporárias para atualizar recursos e infraestrutura dentro de suas contas.

Neste blog post, você aprendeu a utilizar o acesso federado para assumir uma role dentro da AWS diretamente de um arquivo de ação de workflow em um repositório do GitHub. Com esse novo IdP implementado você pode começar a excluir as chaves de acesso (access keys) da AWS dos seus usuários do IAM e utilizar credenciais de curto prazo.

Depois de ler este blog, recomendamos que você siga a diretiva IAM do pilar de segurança do AWS Well Architected para utilizar o acesso programático aos serviços da AWS através de credenciais temporárias e com privilégios limitados. Ao implementar roles federadas do IAM ao invés de chaves de acesso de usuário da AWS, você de acordo com essa diretriz e emite tokens pelo AWS Security Token Service.

Este artigo foi traduzido do Blog da AWS em Inglês.

Tradutores

Eduardo Inoue atua como Technical Account Manager na AWS empoderando clientes em sua jornada de nuvem. Possui mais de 14 anos de experiência em tecnologias como infraestrutura, como computação, rede e armazenamento. Apaixonado por tecnologia está sempre em busca de aprender novas soluções.
Liz Menichetti é Technical Account Manager na AWS. Desde 2019 auxilia os clientes da AWS com arquitetura e projetos de destaque nas mais variadas verticais da indústria, não só dando suporte aos clientes, mas também trazendo valor ao negócio com boas práticas de segurança, escalabilidade, resiliência, performance e excelência operacional.