Referencia de WIF

Esta página reúne las superficies de configuración, las restricciones de validación y las correspondencias de errores para Workload Identity Federation. Para ver guías paso a paso de configuración, consulta las guías de proveedores.

Solicitud de intercambio de tokens

POST /v1/oauth/token acepta un cuerpo JSON que usa el grant jwt-bearer de RFC 7523. Los SDK construyen esta solicitud por ti a partir de las variables de entorno; los ejemplos de cURL en cada guía de proveedor muestran el cuerpo sin procesar.

Respuesta de intercambio de tokens

POST /v1/oauth/token devuelve una respuesta de token estándar de OAuth 2.0 (RFC 6749 §5.1):

Variables de entorno

El SDK lee estas variables para realizar un intercambio de tokens federado sin argumentos de constructor.

La ruta de federación directa mediante variables de entorno se activa solo cuando ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID y una de ANTHROPIC_IDENTITY_TOKEN_FILE o ANTHROPIC_IDENTITY_TOKEN están todas definidas. ANTHROPIC_WORKSPACE_ID se lee junto con ellas, pero no condiciona la activación.

Precedencia de credenciales

El SDK resuelve las credenciales en este orden. La primera fuente que produce una credencial gana.

Cuando se carga un perfil, las variables de entorno completan los campos que el perfil omite, pero nunca anulan los campos que el perfil define explícitamente. Por ejemplo, ANTHROPIC_WORKSPACE_ID completa workspace_id solo cuando el perfil activo no lo define.

Archivo de configuración de perfil

Un perfil es un archivo de configuración con nombre que leen tanto el SDK como la CLI ant. Los perfiles te permiten incluir los parámetros de federación en tu imagen de contenedor o cambiar entre entornos sin modificar el código.

Directorio de configuración

El SDK localiza el directorio de configuración en este orden:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic en Linux y macOS
3. %APPDATA%\Anthropic en Windows

Perfil activo

El nombre del perfil activo se resuelve en este orden:

1. $ANTHROPIC_PROFILE
2. El contenido de <config_dir>/active_config (un archivo de una línea escrito por ant profile activate <name>)
3. El nombre literal default

Claude Code y el Claude Agent SDK respetan este mismo orden de resolución, por lo que un perfil de federación configurado aquí también autentica esas herramientas sin configuración adicional.

Estructura de archivos

Tanto el archivo de configuración como el archivo de credenciales llevan un campo de cadena version de nivel superior en formato major.minor (actualmente "1.0"). El SDK escribe este campo automáticamente para que las versiones futuras puedan detectar y migrar formatos antiguos; omítelo al crear una configuración a mano y el SDK tratará el archivo como la versión actual.

Ejemplo de perfil de federación

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Si se omite authentication.identity_token, el SDK recurre a ANTHROPIC_IDENTITY_TOKEN_FILE o ANTHROPIC_IDENTITY_TOKEN del entorno.

Scopes de OAuth

El oauth_scope que defines en una regla de federación determina qué endpoints de la Claude API puede llamar el token de acceso emitido.

Una solicitud a un endpoint fuera del scope del token devuelve HTTP 403. Actualmente no hay disponibles scopes más granulares (por recurso, o de lectura frente a escritura).

Límites de permisos

El oauth_scope de una regla de federación es un techo: el token emitido nunca puede excederlo. El organization_role de la cuenta de servicio de destino (developer o admin) determina qué scopes se pueden otorgar, por lo que una regla que otorga org:admin debe apuntar a una cuenta de servicio con organization_role=admin. Los permisos efectivos son la intersección del scope de la regla y el rol de la cuenta de servicio.

Reglas de validación

Anthropic aplica estas restricciones cuando creas o actualizas emisores y reglas, y al verificar un JWT entrante en el momento del intercambio.

Para ver los detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de cuentas de servicio, la referencia de la API de emisores de federación y la referencia de la API de reglas de federación.

Campos de recursos

Campos de URL

Los campos issuer_url, jwks.discovery_base y jwks.url se validan:

Los fallos de validación de URL devuelven 400 invalid_request_error con el nombre del campo como prefijo en el mensaje de error (por ejemplo, issuer_url: url must use https scheme).

Verificación de JWT

Semántica de coincidencia de reglas

El bloque match de una regla de federación determina si se acepta un JWT entrante. Todos los campos completados se evalúan con semántica AND: el JWT debe satisfacer cada matcher completado. Al menos uno de subject_prefix, claims o condition debe estar definido; un bloque match que contiene solo audience (o ningún matcher) se rechaza. Esto protege contra reglas que aceptarían todos los tokens de un emisor.

Entorno de evaluación de CEL

La expresión condition tiene acceso a una única variable:

Ejemplo:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Errores

Errores de intercambio de tokens

POST /v1/oauth/token devuelve errores en la forma de error estándar de la API. El SDK envuelve los fallos de intercambio en un FederationExchangeError tipado (o su equivalente en cada lenguaje) que expone el estado HTTP, el cuerpo de la respuesta y el request_id.

Cada denegación de assertion devuelve el mismo 401 authentication_error opaco con el mensaje fijo Authentication failed, independientemente de qué comprobación falló; un error distinguible permitiría a un llamador sondear la configuración de la regla. El motivo de la denegación se registra en la entrada del intento en el historial de autenticación, por ejemplo match_subject_prefix cuando el claim sub no cumple el subject_prefix de la regla, o workspace_id_required cuando la regla abarca varios workspaces y la solicitud no nombra ninguno. Las solicitudes rechazadas antes de que se corrobore la organización de la regla (la familia 400 invalid_request_error anterior) no dejan entrada en el historial; sus mensajes de respuesta indican el problema directamente. Un 401 sin entrada correspondiente en el historial normalmente significa que el propio federation_rule_id no fue reconocido.

Fallos comunes del lado del SDK

Solucionar un intercambio fallido

Una respuesta 401 authentication_error es intencionalmente opaca y su mensaje es siempre Authentication failed; el motivo de la denegación se registra en el historial de autenticación, no en la respuesta.

Un fallo opaco común es una assertion repetida: una assertion que lleva un claim jti solo puede intercambiarse una vez, por lo que una carga de trabajo que reenvía el mismo JWT (un bucle de reintentos, o una renovación que vuelve a leer un token no rotado) se rechaza en el segundo intercambio. La página del historial de autenticación muestra estos intentos con el motivo jti_reused; la solución es emitir una assertion nueva para cada intercambio.

Si aún necesitas depurar a partir del propio JWT, realiza estas comprobaciones en orden:

1. 1

   Decodifica el JWT

   Decodifica la assertion que enviaste para poder comparar cada claim con la configuración de tu emisor y tu regla:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Comprueba que iss coincida con el emisor

   El claim iss decodificado debe ser igual al issuer_url registrado byte por byte, incluidos el esquema, el puerto y cualquier barra final. Una discrepancia en un solo carácter hace fallar la verificación.

3. 3

   Comprueba que aud coincida con la regla

   El claim aud decodificado debe contener el valor audience de la regla como coincidencia exacta. Cuando aud es un arreglo, un elemento debe coincidir exactamente.

4. 4

   Comprueba sub y cada entrada de claims

   Compara sub con el subject_prefix de la regla (distingue mayúsculas y minúsculas; un * final es una coincidencia de prefijo, cualquier otra cosa es exacta). Compara cada clave del mapa claims de la regla con el claim de nivel superior del mismo nombre.

5. 5

   Comprueba exp, nbf e iat

   exp debe estar en el futuro y nbf/iat deben estar en el pasado, dentro de la ventana de desfase de 30 segundos. Si el reloj del host de la carga de trabajo se ha desviado, un token por lo demás válido se rechaza.

6. 6

   Comprueba la accesibilidad del JWKS

   Para el modo discovery, obtén <jwks.discovery_base or issuer_url>/.well-known/openid-configuration a través de HTTPS público en el puerto 443 y confirma que jwks_uri se resuelva. Para explicit_url, obtén la URL del JWKS directamente. Para inline, confirma que la clave de firma del emisor no haya rotado desde que registraste las claves.

   Si el emisor rotó su clave de firma y comenzó a firmar con ella de inmediato, los intercambios pueden fallar durante hasta un minuto mientras se actualiza la caché de JWKS de Anthropic. Consulta Rotación de claves y caché.

Modos de origen de JWKS

Cuando registras un emisor de federación, el campo jwks controla cómo Anthropic obtiene las claves públicas usadas para verificar las firmas de los JWT de ese emisor. Es una unión discriminada con clave en type:

La unión discriminada hace que los campos complementarios sean mutuamente excluyentes por construcción. Tanto discovery como explicit_url también aceptan una cadena opcional ca_cert_pem para emisores que sirven TLS desde una CA privada.

Rotación de claves y caché

En los modos discovery y explicit_url, Anthropic almacena en caché el JWKS obtenido. Si tu proveedor de identidad publica una nueva clave de firma y comienza a firmar tokens con ella de inmediato, los intercambios que presenten esos tokens pueden fallar con un error de firma durante hasta 1 minuto mientras se actualiza la caché.

Para evitar esta ventana, publica una nueva clave de firma en el JWKS al menos 15 minutos antes de que tu proveedor de identidad comience a firmar tokens con ella, y mantén la clave reemplazada en el JWKS hasta que los tokens que firmó hayan expirado. Los proveedores de identidad administrados normalmente siguen esta disciplina por sí mismos. Si operas tu propio emisor (un clúster de Kubernetes autogestionado, un proveedor de descubrimiento OIDC de SPIRE o un servidor de autorización personalizado de Okta con una cadencia de rotación configurada), confirma que tu política de rotación publique las claves nuevas antes de su primer uso.