Referencia de WIF

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

Solicitud de intercambio de tokens

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

Respuesta del 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 en el 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. Gana la primera fuente que proporcione una credencial.

En la CLI ant, la configuración de Claude Models on Google Cloud (Anthropic managed) tiene prioridad después de las variables de entorno de federación y antes del perfil activo. La configuración consiste en el proyecto, el ID del espacio de trabajo y la ubicación. La estableces con las marcas --google-cloud-* o con las variables ANTHROPIC_GOOGLE_CLOUD_*. La CLI usa esta configuración cuando cualquiera de estos valores está establecido. Con esta configuración, la CLI obtiene su credencial de Google Application Default Credentials.

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 incluyen 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 anteriores; omítelo al escribir 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.

Alcances 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 alcance del token devuelve HTTP 403. Actualmente no hay alcances más detallados (por recurso, o de lectura frente a escritura).

Límites de permisos

El oauth_scope de una regla de federación es un límite máximo: el token emitido nunca puede superarlo. El organization_role de la cuenta de servicio de destino (developer o admin) determina qué alcances 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 alcance 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 errores 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 comparador completado. Se debe definir al menos uno de subject_prefix, claims o condition; se rechaza un bloque match que contenga solo audience (o ningún comparador). 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 sola variable:

Ejemplo:

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

Errores

Errores del intercambio de tokens

POST /v1/oauth/token devuelve errores con la forma de error estándar de la API. El SDK informa un fallo de intercambio como WorkloadIdentityError, que proporciona el estado HTTP y los detalles del error del cuerpo de la respuesta. El ID de solicitud está en el error en Python, TypeScript y Ruby, y en los encabezados de respuesta de la excepción en Java. En Go solo está en el mensaje del error, porque el tipo del error está en un paquete interno; los errores de C# y PHP no lo incluyen.

Cada denegación de aserción devuelve el mismo 401 authentication_error opaco con el mensaje fijo Authentication failed, independientemente de qué comprobación haya fallado; 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 de la Claude Console, por ejemplo match_subject_prefix cuando la claim sub no cumple el subject_prefix de la regla, o workspace_id_required cuando la regla abarca varios espacios de trabajo 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 ninguna entrada en el historial; sus mensajes de respuesta indican el problema directamente. Un 401 sin una entrada coincidente en el historial suele significar que no se reconoció el propio federation_rule_id.

Fallos comunes del lado del SDK

Solucionar un intercambio fallido

Una respuesta 401 authentication_error es intencionalmente opaca y su mensaje siempre es 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 aserción reproducida: una aserción que incluye una claim jti solo se puede intercambiar una vez, por lo que una carga de trabajo que vuelve a enviar el mismo JWT (un bucle de reintentos, o una actualizació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 aserción 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 aserción 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

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

3. 3

   Comprueba que aud coincida con la regla

   La claim aud decodificada 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 de minúsculas; un * final es una coincidencia de prefijo, cualquier otra cosa es exacta). Compara cada clave del mapa claims de la regla con la 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, se rechaza un token que de otro modo sería válido.

6. 6

   Comprueba la accesibilidad del JWKS

   Para el modo discovery, obtén <jwks.discovery_base or issuer_url>/.well-known/openid-configuration mediante 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 almacenamiento en caché.

Modos de origen del JWKS

Cuando registras un emisor de federación, el campo jwks controla cómo obtiene Anthropic las claves públicas que se usan 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 almacenamiento en 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 este intervalo, 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 suelen seguir esta práctica por su cuenta. Si operas tu propio emisor (un clúster de Kubernetes autoadministrado, 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 nuevas claves antes de su primer uso.