GitHub Actions com OIDC: como fazer deploy sem guardar chave permanente nos secrets

O OIDC no GitHub Actions permite fazer deploy sem manter uma chave de acesso permanente da nuvem em secrets. Em vez de recuperar uma credencial estática, o job solicita ao GitHub um token OIDC assinado, o provedor de nuvem valida a identidade e as condições daquele token e, se a política permitir, entrega uma credencial de curta duração. O ganho principal é reduzir a exposição de chaves de longa vida, mas a segurança depende de como a relação de confiança é limitada.

O fluxo recomendado tem quatro controles que trabalham juntos: limitar quem pode obter o token OIDC, restringir quais identidades do GitHub o provedor aceita, conceder ao papel de nuvem apenas as permissões necessárias e proteger o caminho de implantação no próprio repositório. A documentação do GitHub destaca que o provedor deve aplicar condições para evitar que repositórios não confiáveis obtenham acesso aos recursos da nuvem. Veja o guia oficial de OIDC em provedores de nuvem.

O que muda quando você troca uma chave permanente por OIDC

Com uma chave estática, o workflow costuma ler um par de credenciais de um secret e apresentá-lo diretamente ao provedor. O valor continua válido até expirar ou ser revogado, mesmo fora da execução que originalmente precisava dele. Com OIDC, o GitHub emite um JWT ligado ao contexto da execução. Esse JWT contém claims como emissor, audiência, subject, repositório, referência Git e, em alguns casos, ambiente e outros atributos.

O provedor não deve confiar apenas no fato de o token ter sido emitido pelo GitHub. Ele precisa comparar claims com uma política de confiança. Se a política aceitar apenas o repositório, a branch, o ambiente ou outro contexto esperado, o token poderá ser trocado por uma credencial temporária. Se os valores não coincidirem, a troca deve falhar. É essa checagem que transforma OIDC em uma fronteira de autorização útil.

1. Configure a confiança no provedor antes de alterar o workflow

O emissor do GitHub Actions é https://token.actions.githubusercontent.com. A configuração seguinte depende do provedor, mas a ideia é sempre a mesma: registrar o GitHub como provedor OIDC e criar uma política que aceite somente identidades previstas.

Os dois claims mais comuns para essa decisão são aud e sub. A audiência varia conforme o provedor e a ação de login usada. O subject representa o contexto do workflow e pode incluir repositório, branch, tag ou environment. Um formato tradicional de exemplo para uma branch é repo:ORG/REPO:ref:refs/heads/main. Quando o job usa um environment, o subject pode refletir o nome desse ambiente. A referência oficial também lista claims adicionais, como repository_id, repository_visibility, workflow_ref e job_workflow_ref, que podem ajudar em políticas mais granulares quando o provedor oferece suporte. Consulte a referência de claims OIDC.

Há uma mudança importante para configurações feitas em 2026. Repositórios criados depois de 15 de julho de 2026 usam por padrão um subject imutável que inclui IDs do proprietário e do repositório. Renomes e transferências depois dessa data também migram para esse formato. Repositórios anteriores mantêm o formato anterior, salvo adesão ao formato imutável. Antes de copiar uma condição de sub, confira o claim real do seu repositório e ajuste a política do provedor para o formato efetivamente emitido.

Restrinja a confiança ao menor contexto que represente o deploy

• Prefira um repositório específico, não toda a organização, quando o papel só atende um projeto.
• Para produção, use um environment dedicado e faça a política de nuvem exigir o contexto de produção sempre que o provedor permitir.
• Se o deploy só sai da main, não deixe a mesma função disponível para qualquer branch.
• Quando a arquitetura usa workflow reutilizável central para deploy, avalie condições associadas ao workflow de chamada ou ao job_workflow_ref, conforme o suporte do provedor.
• Evite curingas amplos no subject. Um padrão conveniente demais pode transformar um único repositório comprometido em caminho para recursos que deveriam estar isolados.

2. Dê id-token: write somente ao job que precisa autenticar

No GitHub Actions, id-token: write é a permissão necessária para solicitar o JWT OIDC. Ela não concede, por si só, permissão de escrita em recursos da nuvem nem no repositório. O efeito é permitir que o job obtenha o token que depois será apresentado ao provedor externo. A documentação também mostra contents: read quando o workflow usa checkout do repositório.

Quando possível, configure a permissão no nível do job de deploy, em vez de concedê-la a todos os jobs do workflow. Isso reduz a quantidade de etapas que podem solicitar um token OIDC.

O trecho acima é um molde, não um workflow pronto para copiar. Substitua a ação e as entradas pelos valores documentados pelo seu provedor. Para ações de terceiros, o GitHub recomenda fixar a referência em um SHA completo de commit quando você precisa de uma versão imutável. Veja a referência de uso seguro do GitHub Actions.

3. Troque o JWT por uma credencial temporária usando a integração do provedor

O workflow não usa o JWT do GitHub diretamente para administrar a nuvem. A etapa de autenticação o apresenta ao serviço de identidade do provedor, que verifica assinatura, emissor, audiência, subject e demais condições. Se tudo corresponder, o provedor entrega uma credencial temporária associada ao papel ou identidade permitida.

Os detalhes não são idênticos entre nuvens. Por exemplo, o guia do GitHub para AWS informa que claims OIDC personalizadas não são suportadas nesse caminho, enquanto outros provedores podem oferecer formas diferentes de mapear ou filtrar atributos. Por isso, use a documentação específica do provedor em vez de transpor uma trust policy de uma nuvem para outra. Consulte os guias oficiais para AWS, Azure e Google Cloud.

4. OIDC não substitui privilégio mínimo no papel de nuvem

Eliminar a chave permanente resolve apenas uma parte do problema. Se a função temporária puder administrar toda a conta, um workflow comprometido ainda terá um impacto grande durante o período em que a credencial estiver válida. A identidade federada deve assumir um papel desenhado para aquele deploy, com ações e recursos restritos.

Para um pipeline que publica um artefato e atualiza um serviço, a função não precisa receber permissões de administração global. Restrinja o acesso aos buckets, registries, serviços, projetos, subscriptions ou resource groups efetivamente usados. Quando o provedor permitir, ajuste também a duração da sessão e separe papéis de produção e homologação.

Esse desenho cria duas barreiras independentes: a trust policy decide quem pode assumir a identidade; a política de autorização decide o que essa identidade pode fazer. As duas precisam ser mínimas.

5. Use environments para proteger o caminho de produção

Se a política OIDC considera um environment, proteja esse environment no GitHub. As regras de proteção podem exigir revisão, restringir branches e tags ou aplicar outras condições antes de o job prosseguir. O GitHub recomenda regras de proteção adicionais quando environments participam de workflows ou políticas OIDC. Veja a documentação de deployments e environments.

Uma configuração comum para produção é permitir deploy apenas a partir de branches selecionadas, exigir revisão quando o risco justificar e impedir que um job de outra branch use o mesmo caminho de produção. Isso complementa a trust policy: o provedor verifica a identidade recebida, enquanto o GitHub controla quais execuções conseguem chegar ao job protegido.

6. Faça testes de negação, não apenas um deploy que funciona

Um teste positivo prova que a configuração consegue autenticar. Ele não prova que a política rejeita contextos indevidos. Depois de obter o primeiro deploy com sucesso, execute cenários que deveriam falhar e confirme em qual etapa a negação acontece.

• Remova temporariamente id-token: write em uma branch de teste e confirme que o job não consegue solicitar o JWT.
• Tente autenticar a partir de uma branch que não deveria assumir o papel.
• Se produção exige environment, tente o mesmo fluxo sem o environment ou com outro nome.
• Se a política restringe repositório ou workflow, valide que um contexto diferente não recebe credencial.
• Confirme que a credencial obtida não autoriza uma operação fora do escopo necessário ao deploy.

O GitHub também disponibiliza mecanismos para inspecionar os claims OIDC antes de concluir a integração. Isso é útil para descobrir o sub real, conferir aud e evitar escrever a trust policy a partir de suposições.

Erros comuns que enfraquecem o desenho

• Confiar em todo o owner ou organização: facilita a implantação, mas aumenta o conjunto de repositórios capazes de alcançar a função de nuvem.
• Dar id-token: write globalmente sem necessidade: aumenta o número de jobs aptos a solicitar um token.
• Usar um papel amplo porque a credencial é temporária: curta duração reduz a janela, não reduz o poder da sessão.
• Copiar um subject antigo: em 2026, repositórios novos podem usar o formato imutável com IDs, então a trust policy precisa corresponder ao claim real.
• Deixar ações críticas em tags móveis sem avaliação: a identidade federada não protege contra código de ação alterado. Fixar ações em SHA completo reduz esse risco.
• Proteger a nuvem e esquecer o environment: se qualquer branch puder chegar ao job de produção, a política pode ficar mais permissiva do que o desenho pretendia.

Checklist para um deploy OIDC com acesso estreito

• Registrar https://token.actions.githubusercontent.com como emissor no provedor, conforme a documentação da nuvem.
• Definir condições explícitas de confiança para repositório e contexto de deploy.
• Conferir o sub real, principalmente em repositórios criados, renomeados ou transferidos depois de 15 de julho de 2026.
• Conceder id-token: write apenas ao job que autentica na nuvem.
• Manter GITHUB_TOKEN e demais permissões no mínimo necessário.
• Usar a ação oficial de autenticação do provedor ou uma implementação equivalente documentada.
• Restringir a função de nuvem a ações, recursos e duração compatíveis com o deploy.
• Proteger o environment de produção com as regras disponíveis e adequadas ao risco.
• Fixar ações críticas em SHA completo quando a imutabilidade for necessária.
• Executar testes de negação para branch, environment, repositório e escopo de autorização.

Quando essas camadas estão alinhadas, OIDC elimina a necessidade de guardar uma chave de nuvem de longa duração no GitHub e transforma cada execução em uma autenticação contextual. O objetivo não é apenas trocar um secret por um token, mas garantir que somente o workflow certo, no contexto certo e pelo tempo necessário consiga assumir uma identidade com privilégio mínimo.