GitHub Actions OIDC: Como proteger suas implantações sem segredos de longa duração
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
- Um job autorizado do GitHub Actions solicita um token de identidade.
- GitHub emite um JWT assinado para esse job.
- O fluxo apresenta o token para o serviço de identidade nuvem.
- O provedor nuvem valida o token e avaliar as condições de confiança configuradas.
- Se a identidade for permitida, o provedor emite credenciais temporárias.
- 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/*"
}
]
}

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.

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.