PTEN

Federação de identidade na AWS: deixe seu CI assumir IAM roles sem access key, com OIDC e Terraform

OIDC na AWS sem access key: seu CI prova quem é com um token assinado e assume uma IAM role temporária. Com Terraform pronto para GitHub Actions.

Autor
Will Peixoto
Publicado
12 nov 2026
Leitura
12 min
Idioma
PT

🇺🇸 Also available in English: AWS OIDC for GitHub Actions: assume IAM roles without access keys, with Terraform

Toda empresa tem uma access key fantasma. Alguém precisou que um job de CI fizesse deploy na AWS, gerou uma chave, colou nos secrets do pipeline, funcionou, e a vida seguiu. Seis meses depois ninguém lembra que ela existe, nunca rotacionou, e tem permissão de sobra “porque na época era mais rápido assim”. Quem nunca?

Este post é sobre matar esse padrão de vez com OIDC. A ideia é simples: o seu CI deixa de carregar qualquer credencial permanente para falar com a AWS. Ele prova quem é com um token assinado, e a AWS entrega uma credencial temporária na hora.

O assunto nasceu de um pedaço que eu cortei do material de Claude Code no Bedrock, porque ele é maior que Claude: vale para qualquer coisa que rode na AWS a partir de um pipeline. E fecha o gancho do post sobre os MCP servers da AWS, onde o agente usa as suas credenciais sem access key. Lá tinha um humano no loop. Aqui não tem.

O problema que o OIDC resolve

Para qualquer coisa chamar a AWS, ela precisa provar quem é, e existem dois jeitos de fazer isso.

O primeiro é uma access key permanente: um par de chaves que funciona como uma senha que nunca expira. Para um humano isso já é ruim. Para um robô é pior, porque a chave fica parada num secret esperando vazar. Se vaza, quem achou tem acesso até alguém perceber e revogar, o que costuma demorar.

O segundo é a credencial temporária: você se autentica de algum jeito e a AWS te devolve uma credencial que vale poucas horas e depois morre sozinha. Para o dev na máquina, isso é o SSO (você loga no navegador e pronto). Mas e quando não tem ninguém para logar? Um job de CI rodando de madrugada não abre navegador nem digita senha.

É aí que entra o OIDC (OpenID Connect). O sistema de CI emite um token assinado que diz, em essência, “sou o job de build do repositório X, da branch main”. A AWS, configurada de antemão para confiar naquele emissor, valida a assinatura, confere as condições e entrega uma credencial temporária. Nenhuma chave fixa fica guardada esperando vazar, e ninguém precisa lembrar de rotacionar nada.

A analogia do crachá descartável

Se a sigla assustou, pensa assim: o OIDC é um crachá descartável para robô.

O porteiro é a AWS. O crachá é o token que o seu CI emite. Você combinou antes com o porteiro quais emissores de crachá são confiáveis (esse é o OIDC provider). Quando o robô chega na portaria, o porteiro olha o crachá, confere quem emitiu, confere se ele vale para aquela porta específica (a condição da trust policy) e libera a entrada só naquela sala (a role de permissão mínima). Acabou a visita, o crachá perde a validade. Ninguém saiu andando com uma chave-mestra no bolso.

Guarda essa imagem, porque o Terraform mais para frente é isso escrito em HCL: um cadastro de emissor confiável e uma porta com fechadura específica.

Esse desenho tem nome, para quem gosta do termo certo: é o pattern de Federated Identity, trocando credencial estática por short-lived credentials emitidas sob demanda. E bate com o que o pilar de Security do Well-Architected pede no SEC02-BP02: workloads usando credenciais temporárias via IAM role no lugar de chaves de longa duração. (O pilar de Reliability eu destrinchei no post sobre o custo da alta disponibilidade; aqui o assunto é Security.)

Quando usar, quando não

Antes do código, o filtro honesto, porque OIDC não serve para todo caso.

Use OIDC quando não tem humano no loop: pipeline de CI/CD (GitHub Actions, GitLab CI, Bitbucket Pipelines), jobs agendados, qualquer automação que roda sozinha e precisa falar com a AWS. Também serve para workload fora da AWS que já recebe token de um IdP compatível com OIDC (Okta, Microsoft Entra ID, Auth0) e precisa chamar a AWS sem access key.

Não use OIDC para o dev no terminal. Se a pessoa está sentada na máquina, o SSO com aws sso login é mais simples e já entrega credencial temporária. Montar OIDC para esse caso é dar murro em ponta de faca. E não use isso como desculpa para dar permissão larga “porque é só o CI”: o ganho de segurança do OIDC se perde inteiro se a role no fim do caminho puder fazer tudo.

O fluxo, num diagrama

Este é o caminho completo de uma execução, do job pedindo o token até a chamada na AWS. Repara que em nenhum momento existe uma access key armazenada.

mermaid
sequenceDiagram
    participant Job as Job de CI (GitHub Actions)
    participant CIP as Emissor OIDC do CI
    participant STS as AWS STS
    participant Role as IAM role (least-privilege)
    participant AWS as Servico AWS (ex Bedrock)

    Job->>CIP: pede um token OIDC para esta execucao
    CIP-->>Job: token assinado (repo, branch, environment)
    Job->>STS: AssumeRoleWithWebIdentity (apresenta o token)
    STS->>STS: valida assinatura + trust policy + condicoes
    STS-->>Job: credencial temporaria (expira em ~1h)
    Job->>Role: usa a credencial
    Role->>AWS: chamada permitida pela policy
    Note over Job,AWS: nenhuma access key foi armazenada em lugar nenhum

Mão na massa: o Terraform completo

Agora o código. Este template faz as duas coisas do diagrama: cadastra o emissor de tokens confiável (o OIDC provider) e cria a role com trust policy condicionada, mais a permissão mínima. O exemplo libera invocar modelos Claude no Bedrock, mas a permission policy é o pedaço que você troca para qualquer outro serviço.

Um detalhe que mudou e muito tutorial ainda não acompanhou: você não precisa mais calcular thumbprint. Para o GitHub (e também GitLab, Google e Auth0), a AWS valida o certificado TLS do emissor com a própria biblioteca de CAs confiáveis e ignora qualquer thumbprint configurado. No Terraform AWS provider, o thumbprint_list virou opcional na versão 5.81.0, então aquele bloco data "tls_certificate" que aparece em todo exemplo antigo pode sair.

hcl
# versions.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.81.0" # a partir daqui thumbprint_list e opcional
    }
  }
}

# variables.tf
variable "oidc_provider_url" {
  description = "URL do issuer do seu emissor de OIDC (ex: https://token.actions.githubusercontent.com)"
  type        = string
}

variable "oidc_audience" {
  description = "Audience esperada no token (sts.amazonaws.com no GitHub Actions)"
  type        = string
  default     = "sts.amazonaws.com"
}

variable "github_repo" {
  description = "Repo autorizado, no formato do sub: org/repo (repo antigo) ou org@ORG_ID/repo@REPO_ID (repo criado depois de 15/07/2026)"
  type        = string
}

variable "bedrock_region" {
  description = "Regiao de onde o CI chama o Bedrock"
  type        = string
  default     = "us-east-1"
}

variable "bedrock_destination_regions" {
  description = "Regioes para onde o inference profile us. roteia (confira no model card do modelo)"
  type        = list(string)
  default     = ["us-east-1", "us-east-2", "us-west-2"]
}

# main.tf
data "aws_caller_identity" "current" {}

locals {
  oidc_host             = replace(var.oidc_provider_url, "https://", "")
  inference_profile_arn = "arn:aws:bedrock:${var.bedrock_region}:${data.aws_caller_identity.current.account_id}:inference-profile/us.anthropic.claude-*"
}

# 1) Cadastra o emissor de tokens confiavel.
# Sem thumbprint_list: no GitHub a AWS valida o TLS pela propria lista de CAs.
resource "aws_iam_openid_connect_provider" "ci" {
  url            = var.oidc_provider_url
  client_id_list = [var.oidc_audience]
}

# 2) Trust policy: so assume quem trouxer token valido E do repo certo
data "aws_iam_policy_document" "trust" {
  statement {
    effect  = "Allow"
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.ci.arn]
    }

    # Audience tem que bater
    condition {
      test     = "StringEquals"
      variable = "${local.oidc_host}:aud"
      values   = [var.oidc_audience]
    }

    # E o token tem que vir do SEU repo (senao qualquer repo do GitHub assumiria)
    condition {
      test     = "StringLike"
      variable = "${local.oidc_host}:sub"
      values   = ["repo:${var.github_repo}:*"]
    }
  }
}

resource "aws_iam_role" "ci_bedrock" {
  name               = "ci-bedrock-invoke"
  assume_role_policy = data.aws_iam_policy_document.trust.json
}

# 3) Permissao minima: so InvokeModel, so Claude, so via inference profile
data "aws_iam_policy_document" "bedrock_invoke" {
  statement {
    sid    = "InvokeViaInferenceProfile"
    effect = "Allow"
    actions = [
      "bedrock:InvokeModel",
      "bedrock:InvokeModelWithResponseStream"
    ]
    resources = [local.inference_profile_arn]
  }

  # O profile us. roteia a chamada para outras regioes, entao o foundation model
  # precisa estar liberado em cada uma delas, mas so quando vier pelo profile
  statement {
    sid    = "FoundationModelBehindProfile"
    effect = "Allow"
    actions = [
      "bedrock:InvokeModel",
      "bedrock:InvokeModelWithResponseStream"
    ]
    resources = [
      for r in var.bedrock_destination_regions :
      "arn:aws:bedrock:${r}::foundation-model/anthropic.claude-*"
    ]

    condition {
      test     = "StringLike"
      variable = "bedrock:InferenceProfileArn"
      values   = [local.inference_profile_arn]
    }
  }
}

resource "aws_iam_role_policy" "bedrock_invoke" {
  name   = "bedrock-invoke-claude"
  role   = aws_iam_role.ci_bedrock.id
  policy = data.aws_iam_policy_document.bedrock_invoke.json
}

output "role_arn" {
  value = aws_iam_role.ci_bedrock.arn
}

Aplica do jeito de sempre, apontando para o emissor do GitHub Actions e para o seu repo:

bash
terraform init
terraform apply \
  -var="oidc_provider_url=https://token.actions.githubusercontent.com" \
  -var="github_repo=aws-ug-sp/meu-repo"

Se a sua conta já tem o provider do GitHub cadastrado (alguém fez pelo console antes), o apply falha, porque a AWS só aceita um OIDC provider por URL na conta. Nesse caso, importa o existente para o state ou troca o resource por um data "aws_iam_openid_connect_provider" apontando para a mesma URL.

Dois detalhes separam um setup seguro de um furado. O primeiro é a condição de sub. Sem ela, a trust policy aceitaria token de qualquer repositório do GitHub, e a própria AWS já barra isso: o IAM recusa criar ou atualizar uma trust policy com o provider do GitHub se a condição token.actions.githubusercontent.com:sub não existir ou for só um curinga. Com repo:org/repo:*, só o seu repo entra. Dá para apertar mais, travando por branch (repo:org/repo:ref:refs/heads/main) ou por environment (repo:org/repo:environment:producao). Só fica esperto com uma pegadinha: quando o job referencia um environment, o sub passa a ter o formato de environment, e uma condição travada por branch deixa de casar.

E tem a mudança mais recente. Repositórios criados no GitHub depois de 15 de julho de 2026 (e repos renomeados ou transferidos depois dessa data) recebem o sub em formato imutável, com o ID do dono e do repo: repo:minha-org@123456/meu-repo@456789:ref:refs/heads/main. Repo antigo continua no formato com nome até alguém ativar a opção. Se o seu repo é novo, passa o github_repo no formato org@ORG_ID/repo@REPO_ID, senão a condição não casa e o AssumeRoleWithWebIdentity volta negado. A doc de OIDC do GitHub mostra os dois formatos.

O segundo detalhe é a permission policy. Ela está presa a bedrock:InvokeModel nos modelos anthropic.claude-*, chamados pelo inference profile us., e nada além. O statement do foundation model existe porque o Claude Sonnet 4.6 não aceita chamada pelo model ID puro em us-east-1, só pelo profile, e o profile pode rotear para us-east-1, us-east-2 ou us-west-2. Se você liberar o foundation model só na sua região, a chamada pode falhar dependendo de para onde o Bedrock mandou o pedido. A role não cria nada nem lê S3. Pensa no pipeline como lugar onde roda código que você não controla 100% (actions de terceiros, dependências do build), a mesma lógica de desconfiança que eu usei no post de Lambda MicroVMs para código não confiável. Least-privilege de verdade, não aquele "Resource": "*" que a gente jura que arruma depois.

Plugando no GitHub Actions

Do lado do pipeline, o trabalho é pedir o token e trocar pela credencial. A action oficial da AWS faz a troca; você só precisa dar a permissão id-token: write para o job poder pedir o token OIDC. Ela só controla o pedido do token; o acesso ao repo segue o que você declarar nas outras linhas.

yaml
# .github/workflows/exemplo.yml
permissions:
  id-token: write   # libera o job a pedir o token OIDC
  contents: read

jobs:
  rodar:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ci-bedrock-invoke
          aws-region: us-east-1
          # sem aws-access-key-id nem aws-secret-access-key aqui. Esse e o ponto.

      - name: Chama o Bedrock
        run: aws bedrock-runtime invoke-model --model-id us.anthropic.claude-sonnet-4-6 ...

Nesse YAML não tem access key nenhuma. O configure-aws-credentials pega o token OIDC que o GitHub emitiu para essa execução, faz o AssumeRoleWithWebIdentity contra a role que você criou no Terraform e injeta a credencial temporária no resto dos steps (por padrão ela vale 1 hora). Quando o job termina, a credencial morre.

Se você ainda está na @v4, a v6 é a major atual. A mudança que quebra é o runtime Node 24, que exige runner na versão 2.327.1 ou mais nova. Em runner hospedado pelo GitHub isso já está resolvido; em self-hosted, confere antes de subir a versão.

Conferindo que funcionou

Depois de rodar uma vez, dá para confirmar no CloudTrail que a role foi assumida via web identity:

bash
aws cloudtrail lookup-events \
  --region us-east-1 \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
  --query "Events[].{Hora:EventTime,Role:Resources[0].ResourceName}" \
  --output table

Apareceu o evento com a sua role? Então está fechado. Se não apareceu, confere a região: o CloudTrail registra a chamada na região do endpoint do STS que atendeu o pedido, então use a mesma do aws-region do workflow.

O que você leva

OIDC troca “chave permanente largada num secret” por “crachá descartável validado na hora”. Você cadastra o emissor de tokens uma vez, cria uma role com trust policy bem condicionada (audience mais repo, no mínimo, no formato de sub que o seu repo usa) e permissão mínima, e o seu CI passa a assumir essa role sem carregar segredo nenhum. Vale para Bedrock, para deploy, para qualquer chamada AWS a partir de um pipeline.

E aquela access key fantasma do começo? Depois que o pipeline rodar via OIDC, desativa ela no IAM, espera um ciclo de deploy para garantir que nada quebrou e apaga. O seguro morreu de velho.

Se este guia te ajudou, manda aquele joinha, comenta como ficou o seu setup de OIDC e compartilha para fortalecer a comunidade. E se quiser trocar ideia ao vivo, aparece no próximo meetup do AWS UG SP. Valeu demais! BUILD. SCALE. REPEAT. =D

Will Peixoto

Will Peixoto é Staff Engineer na Serverless Guru e escreve sobre serverless, arquitetura e agentes de IA na AWS: o que ele escolheria, por quê e quanto custa.

Continue lendo

Post novo direto no seu email

Um tema de serverless, arquitetura ou agentes de IA na AWS por edição: o que eu escolheria, por quê e quanto custa. Zero spam.

Abre a página de inscrição numa nova aba.