Usar WIF com GitHub Actions

Cada execução de workflow do GitHub Actions pode solicitar um token de identidade assinado do emissor hospedado do GitHub em https://token.actions.githubusercontent.com. Com "Workload Identity Federation" (federação de identidade de carga de trabalho), ou WIF, seu workflow troca esse token por um token de acesso da Anthropic de curta duração, para que seus jobs de CI possam chamar a Claude API sem um segredo ANTHROPIC_API_KEY armazenado no seu repositório.

A claim sub do token codifica o repositório e o contexto do gatilho. Para um push em uma branch, ela tem a forma repo:<owner>/<repo>:ref:refs/heads/<branch>. Execuções de pull request usam repo:<owner>/<repo>:pull_request, e implantações controladas por ambiente usam repo:<owner>/<repo>:environment:<name>. Sua regra de federação faz a correspondência com essa claim (e outras, como repository_owner e ref) para decidir quais execuções de workflow têm permissão para se autenticar.

Pré-requisitos

• Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
• Um repositório GitHub onde você possa editar arquivos de workflow e conceder a permissão id-token: write.
• Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização Anthropic.
• O ID da sua organização Anthropic. Você pode encontrá-lo no Claude Console em Settings → Organization.

Configure seu workflow

O GitHub só emite um token de identidade para jobs que o solicitam explicitamente. Adicione a permissão id-token: write no nível do workflow ou do job:

permissions:
  id-token: write
  contents: read

Dentro do job, o runner expõe duas variáveis de ambiente: ACTIONS_ID_TOKEN_REQUEST_URL e ACTIONS_ID_TOKEN_REQUEST_TOKEN. Chame a URL de solicitação com o token de solicitação como credencial bearer e o audience escolhido como parâmetro de consulta, e então grave o "JSON Web Token" (token web JSON), ou JWT, retornado em um arquivo:

- name: Fetch GitHub OIDC token
  run: |
    curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.anthropic.com" \
      | jq -r .value > /tmp/gha-jwt

Se você preferir JavaScript, actions/github-script expõe a mesma capacidade por meio de core.getIDToken(audience):

- name: Fetch GitHub OIDC token
  uses: actions/github-script@v8
  with:
    script: |
      const fs = require('fs');
      const token = await core.getIDToken('https://api.anthropic.com');
      fs.writeFileSync('/tmp/gha-jwt', token);

O token decodificado carrega claims que descrevem a execução do workflow. Sua regra de federação faz a correspondência com elas:

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:your-org/your-repo:ref:refs/heads/main",
  "aud": "https://api.anthropic.com",
  "repository": "your-org/your-repo",
  "repository_owner": "your-org",
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "workflow": "CI",
  "actor": "octocat",
  "event_name": "push"
}

Consulte a referência de claims de subject OIDC do GitHub para a lista completa de formatos de sub.

Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco GitHub Actions. O assistente orienta você no registro do emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: O GitHub publica seu documento de descoberta OIDC e seu JWKS publicamente, portanto use o modo de descoberta. A Anthropic atualiza as chaves automaticamente quando o GitHub as rotaciona.

{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks": { "type": "discovery" }
}

Regra de federação: Faça a correspondência apenas com as execuções de workflow em que você pretende confiar. Consulte Restrinja quais workflows podem se autenticar para saber como delimitar essas claims com segurança.

{
  "name": "gha-main",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "repo:your-org/your-repo:ref:refs/heads/main",
    "audience": "https://api.anthropic.com",
    "claims": {
      "repository_owner": "your-org"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Seja tão específico quanto a carga de trabalho permitir. Afrouxe subject_prefix para repo:your-org/your-repo:* (combinado com uma restrição claims.ref) somente se a regra precisar corresponder a vários tipos de evento do mesmo repositório, porque o segmento final de sub varia entre eventos ref:..., environment:... e pull_request.

Obtenha e use um token

Defina as variáveis de ambiente de federação no job e chame o SDK normalmente. Anthropic() lê ANTHROPIC_IDENTITY_TOKEN_FILE, troca o JWT na primeira requisição e atualiza o token de acesso automaticamente antes que ele expire.

import anthropic

# Lê ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID e ANTHROPIC_IDENTITY_TOKEN_FILE
# do ambiente do job.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Cada token de identidade emitido pelo GitHub expira aproximadamente cinco minutos após a emissão. O endpoint de solicitação de token (ACTIONS_ID_TOKEN_REQUEST_URL) permanece válido durante todo o job, portanto você pode obter um token novo a qualquer momento. O SDK troca o token no primeiro uso e armazena em cache o token de acesso da Anthropic resultante. Para jobs que executam por mais tempo do que a vida útil do token da Anthropic, o SDK relê ANTHROPIC_IDENTITY_TOKEN_FILE a cada atualização, então execute novamente a etapa de obtenção periodicamente (ou envolva-a em um loop em segundo plano) para manter o arquivo atualizado. Como alternativa, passe ao SDK um callback provedor de token que chame ACTIONS_ID_TOKEN_REQUEST_URL diretamente em vez de usar o caminho do arquivo.

Verifique a configuração

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Uma troca negada retorna um 401 authentication_error opaco com a mensagem fixa Authentication failed, independentemente de qual verificação falhou; na maioria dos casos, o motivo da negação é registrado na entrada da tentativa na página de histórico de autenticação, e Solucionar problemas de uma troca com falha percorre as verificações em ordem. A causa mais comum do lado do GitHub Actions é o formato da claim sub não corresponder (seu segmento final varia entre eventos ref:..., environment:... e pull_request); a entrada do histórico mostra o motivo match_subject_prefix.

Restrinja quais workflows podem se autenticar

Restrinja o bloco match da regra ao escopo mais estreito que atenda ao seu caso de uso:

• Fixe em um único repositório: Use subject_prefix: "repo:your-org/your-repo:*" para que outros repositórios da organização não correspondam.
• Fixe em uma branch protegida: Adicione "ref": "refs/heads/main" (ou sua branch de release) em claims para que execuções de pull request e branches de feature não correspondam.
• Fixe o proprietário explicitamente: Adicione "repository_owner": "your-org" em claims como uma verificação de defesa em profundidade contra casos extremos de análise de sub.
• Fixe em um ambiente de implantação: Para jobs de deploy, faça a correspondência com subject_prefix: "repo:your-org/your-repo:environment:production" e controle esse ambiente com revisores obrigatórios no GitHub.

Próximos passos

• Workload Identity Federation: passo a passo completo de configuração, variáveis de ambiente e precedência de credenciais.
• Autenticação: como a federação se compara às chaves de API.