Web e Desenvolvimento

GitHub Actions OIDC: Como proteger suas implantações sem segredos de longa duração

GitHub Actions OIDC: How to Secure Your Deployments Without Long-Lived Secrets

Aprenda a fortalecer a segurança de implantação do GitHub Actions com OIDC. Substitua credenciais de nuvem de longa duração por tokens de curta duração, restrinja o acesso usando políticas de confiança IAM e proteja seus pipelines CI/CD.

GitHub Actions OIDC: Como Segurar suas Implantações Sem Segredos de Longa Duração

Implantar uma aplicação a partir do GitHub Actions geralmente requer acesso a infraestrutura externa. Um fluxo de trabalho pode fazer upload de arquivos para o Amazon S3, publicar contêineres ou atualizar recursos em nuvem. Tradicionalmente, as equipes armazenam uma chave de acesso à nuvem em Segredos do GitHub. Isso funciona, mas uma credencial de longa duração permanece útil para um atacante se um fluxo, dependência ou log expuser.

OpenID Connect (OIDC) ajuda a fortalecer a segurança CI/CD substituindo credenciais nuvem de longa duração por acesso temporário concedido apenas a identidades de fluxo autorizadas. Isso reduz a exposição de credenciais, limita acesso não autorizado e suporta implantações de produção mais controladas.

Este tutorial explica os benefícios de segurança, mostra uma configuração prática do AWS e identifica as proteções que ainda são necessárias. OIDC não é um interruptor mágico de segurança: a política de confiança, permissões de papel e controles de fluxo importam tanto quanto o troca de token.

Por que a segurança de implantação é importante

Os pipelines CI/CD são automação privilegiada. Eles podem substituir código de produção, fazer upload de ativos, ler configurações de implantação ou modificar infraestrutura. Um pipeline comprometido pode ter um impacto maior do que um workstation de desenvolvedor comprometido.

Três riscos comuns merecem atenção particular:

  • Exposição de credencial: uma estática de acesso nuvem roubada de um ambiente de build pode permanecer válida até que alguém a revogue.
  • Privilegios excessivos: uma credencial de implantação com permissões de administrador pode afetar serviços não relacionados.
  • Implantação não autorizada: um branch ou fluxo não confiável pode ganhar acesso à produção se as verificações de identidade forem muito amplas.

OIDC aborda parte desse problema amarrando a autenticação a uma identidade de fluxo curta e verificável. Ele não substitui a IAM de menor privilégio, revisão de código ou proteção de ambiente.

O que é OIDC no GitHub Actions?

OpenID Connect é uma camada de identidade construída sobre OAuth 2.0. O GitHub Actions pode solicitar um token JSON Web (JWT) assinado do provedor OIDC do GitHub:

https://token.actions.githubusercontent.com

O token contém alegações descrevendo a identidade do job e o contexto de execução. Um serviço de identidade nuvem valida a assinatura, emissor, audiência e alegações relevantes, então decide se emite credenciais temporárias.

O serviço externo deve confiar explicitamente na identidade de fluxo do GitHub pretendida. Habilitar OIDC em um arquivo YAML não concede acesso.

Veja a documentação OIDC do GitHub.

Comparação de segurança: credenciais estáticas vs OIDC

Consideração de segurança Chave de acesso de longa duração Federação OIDC
Credencial nuvem permanente no GitHub Comumente necessária Não é necessária para provedores suportados
Vida útil da credencial Até expiração ou revogação Sessão temporária
Responsabilidade de rotação Equipe deve gerenciar ciclo de vida da chave Provedor nuvem emite credenciais de curta duração
Restrições de identidade Depende do armazenamento de credencial e IAM Política de confiança pode restringir identidade de fluxo
Autorização Permissões IAM Permissões IAM ainda são necessárias
Risco restante Roubo e reuso de estática estática Fluxo autorizado comprometido ou confiança ampla

OIDC reduz o risco e impacto do roubo de credencial; ele não elimina todo segredo. Aplicações ainda podem precisar de senhas de banco, chaves de assinatura ou tokens de API de terceiros.

Como funciona o fluxo de autenticação OIDC

  1. Um job autorizado do GitHub Actions solicita um token de identidade.
  2. GitHub emite um JWT assinado para esse job.
  3. O fluxo apresenta o token para o serviço de identidade nuvem.
  4. O provedor nuvem valida o token e avaliar as condições de confiança configuradas.
  5. Se a identidade for permitida, o provedor emite credenciais temporárias.
  6. O fluxo usa essas credenciais dentro do escopo permitido do papel.

O provedor nuvem deve rejeitar um token cujo sujeito, audiência ou outras condições necessárias não correspondem. Essa validação é a fronteira entre uma implantação segura e uma que confia demais.

Passo 1: Configurar o provedor OIDC do GitHub no AWS

AWS IAM suporta provedores de identidade OpenID Connect. Crie um provedor de identidade usando:

Configuração Valor
URL do provedor https://token.actions.githubusercontent.com
Audiência sts.amazonaws.com
Tipo de provedor OpenID Connect

A audiência identifica o destinatário pretendido do token. A ação de credenciais AWS normalmente usa sts.amazonaws.com.

Veja a configuração de papel OIDC do AWS IAM.

Passo 2: Restringir quem pode assumir o papel de implantação

Crie um papel IAM cuja política de confiança permita sts:AssumeRoleWithWebIdentity apenas do provedor de identidade GitHub e da identidade de fluxo pretendida.

O exemplo a seguir usa o formato tradicional de sujeito baseado em branch do GitHub:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012: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:example-org/example-app:ref:refs/heads/main"
        }
      }
    }
  ]
}

Substitua o número da conta AWS, organização e repositório.

Não copie a condição de sujeito cegamente. GitHub introduziu um formato de sujeito padrão imutável para repositórios criados após 15 de julho de 2026. Verifique o formato de sujeito real usado pelo seu repositório e configure o AWS para correspondê-lo. Fluxos baseados em ambiente também podem usar uma forma de sujeito diferente. Consulte a referência de token OIDC do GitHub.

Uma política de confiança restrita é uma das formas mais importantes de impedir que fluxos não autorizados obtenham credenciais de produção. Evite sujeitos wildcards que acidentalmente autorizem repositórios ou contextos não relacionados.

Passo 3: Limitar o que o papel pode fazer

A confiança determina quem pode assumir um papel. As permissões IAM determinam o que o papel pode fazer após a autenticação.

Para uma implantação que apenas faz upload de arquivos para um único bucket S3, uma política simplificada é:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::example-deploy-bucket/*"
    }
  ]
}
Illustration of the article's main concept

Este exemplo permite upload de objetos, não administração de conta ou exclusão de bucket. Se sua implantação também remove arquivos obsoletos ou lista o conteúdo do bucket, conceda apenas as operações adicionais necessárias, como s3:DeleteObject ou s3:ListBucket escopos.

Nunca conceda AdministratorAccess apenas para fazer uma implantação funcionar. Credenciais temporárias com privilégios excessivos ainda podem causar danos sérios.

Passo 4: Solicitar credenciais temporárias de um fluxo

Um job de implantação deve ser permitido para solicitar um token OIDC. O exemplo a seguir faz upload de um diretório dist/ pré-construído para S3:

name: Deploy website

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy-role
          aws-region: eu-west-1

      - name: Deploy website
        run: |
          aws s3 cp ./dist/ s3://example-deploy-bucket/ --recursive

O exemplo usa referências de ação de versão major para legibilidade. Em produção, revise as versões suportadas atualmente e preferencialmente fixe ações de terceiros em SHAs de commit completos. O exemplo assume que o site já foi construído em dist/.

Note o que está faltando: nenhuma permanentes de acesso AWS ou segredo de acesso é armazenado no fluxo.

A ação oficial de credenciais AWS troca o token OIDC por credenciais temporárias do AWS.

Passo 5: Entender id-token: write

Esta permissão:

permissions:
  id-token: write

permite um job solicitar um token de identidade GitHub OIDC. Ele não por si só dá ao job permissão para escrever em repositórios GitHub ou acessar AWS.

O provedor nuvem ainda decide se confia a identidade, e o papel IAM ainda controla quais operações são permitidas.

Conceda id-token: write apenas para jobs que realmente se autenticam na nuvem. Jobs de build, lint e teste geralmente não precisam disso.

Passo 6: Proteger ambientes de produção

OIDC não pode compensar um fluxo autorizado executando código malicioso. Se um atacante pode alterar um fluxo de implantação confiado ou executar código não revisado nesse contexto, eles podem obter credenciais temporárias.

Ambientes do GitHub podem adicionar controles como restrições de branch de implantação e revisores obrigatórios, sujeitos a configurações de repositório e disponibilidade de plano.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    permissions:
      contents: read
      id-token: write

Quando o fluxo usa um ambiente, o sujeito OIDC pode identificar esse ambiente em vez de um branch. Atualize a política de confiança do AWS para corresponder às alegações reais e proteja o ambiente em si.

Para produção, combine identidades restritas com proteção de branch, revisão de código, permissões de fluxo limitadas e regras de aprovação de ambiente onde apropriado. É assim que OIDC se torna parte de uma postura de segurança de implantação mais forte, e não apenas um substituto de credencial.

Passo 7: Verificar a identidade assumida e testar negações

Após configurar a autenticação AWS, adicione um passo de diagnóstico:

- name: Verify AWS identity
  run: aws sts get-caller-identity

Verifique que a resposta identifica a conta AWS e o papel de implantação pretendidos. O comando não revela o segredo de acesso.

Também teste que um branch, repositório ou ambiente não autorizado não pode assumir o papel de produção. Uma implantação não autorizada fracassada é um teste de segurança bem-sucedido.

Não registre tokens OIDC brutos ou credenciais temporárias durante a depuração.

Erros comuns de segurança e configuração OIDC

id-token: write ausente

O job não pode solicitar um token OIDC a menos que tenha a permissão. Permissões de nível de job podem sobrescrever permissões de nível de fluxo.

Technical workflow illustration

AWS retorna AccessDenied para a assume do papel

Verifique o provedor de identidade, audiência, ARN do papel e condição de sujeito. Em particular, verifique o formato de sujeito real do GitHub em vez de assumir que todo repositório usa o mesmo padrão.

Autenticação succeed, mas upload falha

A relação de confiança pode estar correta enquanto o papel não tem as permissões S3 necessárias. Corrija as permissões IAM de escopo estreito em vez de ampliar a confiança de identidade.

Acesso à produção é permitido de muitos contextos

Um sujeito wildcard ou restrições de ambiente insuficientes podem tornar credenciais de produção disponíveis para fluxos que nunca deveriam recebê-los. Restrinja a política de confiança e testes casos não autorizados.

Um pull request não pode implantar

Pull requests podem ter alegações diferentes e código não confiável. Não weakened condições de confiança de produção apenas para permitir que um pull request assuma o papel de implantação. Execute validação separadamente da implantação de produção.

Você pode usar OIDC com Azure ou Google Cloud?

Sim. O mecanismo de federação é similar, mas a configuração de identidade difere.

Nuvem Mecanismo de federação Ação GitHub
AWS Provedor de identidade OIDC e papel aws-actions/configure-aws-credentials
Microsoft Azure Credenciais de identidade federada azure/login
Google Cloud Workload Identity Federation google-github-actions/auth

Azure normalmente associa uma credencial federada a uma aplicação ou identidade gerenciada. Google Cloud usa um pool de identidade de workload e provedor, com acesso direto a recursos ou impersonação de conta de serviço dependendo da configuração.

Cada plataforma tem sua própria audiência, correspondência de sujeito e regras de autorização. Revisão a documentação oficial atual do provedor antes de copiar um exemplo.

E sobre sites PHP em hospedagem tradicional?

Nem todo host aceita identidades GitHub OIDC. Hospedagem compartilhada e hospedagem gerenciada de PHP ainda podem usar chaves SSH, credenciais SFTP, webhooks de implantação ou tokens de API de provedor.

Habilitar OIDC no GitHub Actions não substitui automaticamente uma chave SSH se o servidor de destino não tiver um mecanismo de federação.

Onde OIDC não está disponível, use uma conta de implantação dedicada, permissões de escopo estreito, segredos protegidos e rotação de credenciais. Restrinja o acesso a filesystem e comando onde possível.

O objetivo de segurança é menor privilégio e exposição limitada de credencial, independentemente de OIDC ser suportado.

Lista de segurança de implantação

Antes de implantar para produção, verifique que:

  • O emissor e audiência OIDC estão configurados corretamente.
  • A política de confiança corresponde apenas ao repositório e contexto de implantação pretendido.
  • A condição de sujeito reflete o formato real de token do GitHub do seu repositório.
  • O papel IAM tem apenas as permissões necessárias para a implantação.
  • Apenas jobs de implantação recebem id-token: write.
  • Branches de produção e ambientes têm proteção apropriada.
  • Ações de terceiros são revisadas e preferencialmente fixadas em SHAs de commit imutáveis.
  • Pull requests não confiáveis não podem assumir papéis de produção.
  • Branches e repositórios não autorizados falham na autenticação.
  • Tokens e credenciais temporárias nunca são registradas ou armazenadas desnecessariamente.

Perguntas frequentes

OIDC é mais seguro que chaves de acesso AWS estáticas?

Ele reduz a exposição ao roubo de credencial de longa duração. Fortes políticas de confiança, permissões limitadas e fluxos protegidos ainda são essenciais.

OIDC elimina Segredos do GitHub?

Ele substitui algumas credenciais de autenticação nuvem, não todo segredo de aplicação ou API key.

O que id-token: write concede?

Permite um fluxo solicitar um token de identidade. As permissões nuvem são determinadas separadamente pelo provedor.

Pull requests não confiáveis podem usar credenciais OIDC de produção?

Eles não deveriam. Configure condições de confiança restritas e mantenha implantações de produção separadas de código não confiável.

OIDC funciona com qualquer provedor de hospedagem?

Não. O serviço de destino ou um broker de identidade deve suportar e confiar em tokens OIDC do GitHub.

Conclusão: fortalecer a segurança, não apenas a autenticação

GitHub Actions OIDC é uma forma eficaz de aumentar a segurança de implantação para serviços nuvem suportados. Ele remove a necessidade de manter chaves nuvem permanentes no GitHub, permite acesso de curta duração e permite que políticas de confiança nuvem restrinjam quais fluxos podem implantar.

Mas o design mais forte combina OIDC com IAM de menor privilégio, ambientes protegidos, código de fluxo revisado e testes explícitos que identidades não autorizadas são rejeitadas.

O objetivo não é simplesmente substituir um segredo. É garantir que apenas o fluxo certo pode acessar os recursos certos, com as menores permissões e pelo menor tempo prático.