Cómo autenticar tu agente Claude sin API keys estáticas: guía paso a paso de Workload Identity Federation

Workload Identity Federation transforma la autenticación de workloads: en lugar de que tu pipeline almacene una credencial de Anthropic, tu workload presenta al endpoint /v1/oauth/token un JWT firmado por el proveedor de identidad que ya opera en tu infraestructura —GitHub Actions, AWS IAM, Google Cloud, Azure, Kubernetes, SPIFFE u Okta— y recibe a cambio un token de acceso Anthropic de corta duración.

El flujo en tres pasos

1. Tu IdP emite un JWT al workload. En GitHub Actions, el runner lo solicita al endpoint ACTIONS_ID_TOKEN_REQUEST_URL. En AWS ECS o Lambda, la llamada a sts.GetWebIdentityToken devuelve el token. En Kubernetes, el token se proyecta directamente al sistema de archivos del pod.
2. El SDK intercambia el JWT por un token Anthropic. El SDK envía el JWT a POST /v1/oauth/token usando el grant type RFC 7523 jwt-bearer. Anthropic verifica la firma contra las JWKS del issuer registrado, evalúa las condiciones de la federation rule configurada, y devuelve un token sk-ant-oat01-... de corta duración.
3. El SDK rota el token automáticamente. Tu código no cambia. El SDK re-lee el archivo de identidad antes de cada expiración y renueva el token sin intervención del desarrollador.

Qué se configura en Claude Console

Antes de que tu workload pueda federarse, configuras tres recursos en Settings → Workload identity con el wizard Connect workload:

• Service account (svac_...): identidad no-humana dentro de tu organización Anthropic. Reemplaza el concepto de API key asociada a un usuario. El service account tiene su propio audit trail.
• Federation issuer (fdis_...): registro del IdP con su issuer_url y la fuente de JWKS (discovery para proveedores públicos, URL explícita o inline para clusters sin acceso público a internet).
• Federation rule (fdrl_...): la regla que conecta el issuer con el service account. Define qué claims del JWT deben coincidir, qué service account recibe el token, y cuánto tiempo vive ese token (token_lifetime_seconds, entre 60 y 86400 segundos; el default es 3600).

El wizard Connect workload crea los tres recursos en un único flujo guiado y verifica el intercambio en tiempo real. También puedes crear y gestionar los tres recursos mediante la Admin API de Anthropic, lo que habilita infrastructure as code con Terraform o herramientas similares.

Paso 1: Registrar el issuer y la federation rule en Claude Console

En el Claude Console, abre Settings → Workload identity → Connect workload y selecciona el tile GitHub Actions. El wizard precargará la issuer URL con https://token.actions.githubusercontent.com, que es el valor exacto del claim iss en todos los tokens de GitHub Actions.

Para la federation rule, define el subject_prefix con el formato que GitHub usa en el claim sub. El trailing segment varía según el evento que disparó el workflow:

• Push a rama: repo:owner/repo:ref:refs/heads/main
• Pull request: repo:owner/repo:pull_request
• Environment gated: repo:owner/repo:environment:production

Aplica el principio de mínimo privilegio: nunca uses repo:owner/* sin acotar el ref o el environment. Un prefijo demasiado amplio permite que cualquier workflow de la organización obtenga un token Anthropic. Anota los IDs fdrl_..., svac_... y el ID de tu organización.

Paso 2: El workflow de GitHub Actions

GitHub solo emite el token OIDC a jobs que lo solicitan explícitamente con el permiso id-token: write. Este es el workflow mínimo funcional:

name: Call Claude via WIF
on: push

permissions:
  id-token: write
  contents: read

jobs:
  call-claude:
    runs-on: ubuntu-latest
    env:
      ANTHROPIC_FEDERATION_RULE_ID: fdrl_REEMPLAZA_CON_TU_ID
      ANTHROPIC_ORGANIZATION_ID: 00000000-0000-0000-0000-REEMPLAZA
      ANTHROPIC_SERVICE_ACCOUNT_ID: svac_REEMPLAZA_CON_TU_ID
      ANTHROPIC_WORKSPACE_ID: wrkspc_REEMPLAZA_CON_TU_ID
      ANTHROPIC_IDENTITY_TOKEN_FILE: /tmp/gha-jwt
    steps:
      - uses: actions/checkout@v4
      - name: Obtener token OIDC de GitHub
        run: |
          curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.anthropic.com" \
            | jq -r .value > "$ANTHROPIC_IDENTITY_TOKEN_FILE"
      - name: Instalar SDK
        run: pip install anthropic
      - name: Llamar a Claude
        run: python mi_script.py

Paso 3: El script Python

El script que llama a Claude es tan simple como esto. No hay ninguna credencial estática:

import anthropic

# El SDK lee ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID y
# ANTHROPIC_IDENTITY_TOKEN_FILE del entorno del job automaticamente.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hola Claude desde GHA sin API key"}],
)
print(message.content[0].text)

El token OIDC que emite GitHub expira aproximadamente 5 minutos después de su emisión. El endpoint ACTIONS_ID_TOKEN_REQUEST_URL permanece válido durante todo el job, por lo que puedes volver a solicitar el token si el job dura más que eso.

Paso 4: Verificar el intercambio

Un intercambio exitoso devuelve un access_token que comienza con sk-ant-oat01- y un campo expires_in en segundos. Si recibes 400 invalid_grant, el error más común en GitHub Actions es que el valor del claim sub no coincide con el subject_prefix de la rule: el trailing segment varía entre ref:..., environment:... y pull_request. Decodifica el JWT en jwt.io y compara el valor real del sub con lo que configuraste en la rule.

Para equipos que trabajan en Node.js o TypeScript, el patrón es análogo. En GitHub Actions, el SDK también lee las variables de entorno automáticamente cuando se construye sin argumentos:

import Anthropic from "@anthropic-ai/sdk";

// El SDK lee ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
// ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID y
// ANTHROPIC_IDENTITY_TOKEN_FILE automaticamente del entorno.
const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hola desde GHA con WIF en TypeScript" }]
});
for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Para AWS con token STS explícito en TypeScript, el patron usa oidcFederationProvider y el cliente de STS del AWS SDK:

import Anthropic from "@anthropic-ai/sdk";
import { oidcFederationProvider } from "@anthropic-ai/sdk/lib/credentials/oidc-federation";
import { STSClient, GetWebIdentityTokenCommand } from "@aws-sdk/client-sts";

const sts = new STSClient({ region: "us-east-1" });

async function getStsToken(): Promise<string> {
  const out = await sts.send(
    new GetWebIdentityTokenCommand({
      Audience: ["https://api.anthropic.com"],
      SigningAlgorithm: "RS256",
      DurationSeconds: 900
    })
  );
  return out.WebIdentityToken!;
}

const client = new Anthropic({
  credentials: oidcFederationProvider({
    identityTokenProvider: getStsToken,
    federationRuleId: process.env.ANTHROPIC_FEDERATION_RULE_ID!,
    organizationId: process.env.ANTHROPIC_ORGANIZATION_ID!,
    serviceAccountId: process.env.ANTHROPIC_SERVICE_ACCOUNT_ID,
    workspaceId: process.env.ANTHROPIC_WORKSPACE_ID,
    baseURL: "https://api.anthropic.com",
    fetch
  })
});

Checklist de implementación

• ANTHROPIC_API_KEY está completamente ausente del entorno del workload federado; su presencia silencia la federación sin advertencia.
• El subject_prefix de la federation rule apunta al recurso exacto: repo + branch para GHA, ARN completo del role para AWS.
• El audience en el JWT coincide exactamente con https://api.anthropic.com.
• Los IDs ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID y ANTHROPIC_WORKSPACE_ID están como variables de entorno ordinarias, no como secretos.
• El service account está agregado como miembro del workspace correcto en Claude Console.
• token_lifetime_seconds está configurado según la duración real del job; 600 segundos es el default del wizard.

Errores frecuentes y su solución