AdministraciónAutenticación

Referencia de WIF

Variables de entorno, reglas de validación, configuración de perfiles y referencia de errores para Workload Identity Federation.

Esta página reúne las superficies de configuración, las restricciones de validación y las asignaciones de errores para Workload Identity Federation. Para 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 usando 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.

Campo	Requerido	Descripción
`grant_type`	Sí	Siempre `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Sí	El JWT OIDC emitido por tu proveedor de identidad.
`federation_rule_id`	Sí	ID etiquetado (`fdrl_...`) de la regla de federación a evaluar.
`organization_id`	Sí	UUID de tu organización de Anthropic.
`service_account_id`	Sí	ID etiquetado (`svac_...`) de la cuenta de servicio de destino.
`workspace_id`	Condicional	ID etiquetado (`wrkspc_...`) del workspace al que se limitará el token emitido, o el literal `default` para el workspace predeterminado de la organización. Requerido cuando la regla está habilitada para más de un workspace. Cuando se omite, el servidor selecciona el único workspace habilitado de la regla.

Respuesta de intercambio de tokens

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

Campo	Tipo	Descripción
`access_token`	string	El token de Anthropic de corta duración, con el prefijo `sk-ant-oat01-...`. Pásalo como `Authorization: Bearer <token>`.
`token_type`	string	Siempre `Bearer`.
`expires_in`	integer	Segundos hasta que el token expire.
`scope`	string	El alcance de OAuth otorgado por la regla coincidente.

Variables de entorno

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

Variable	Requerida	Descripción	Ejemplo
`ANTHROPIC_FEDERATION_RULE_ID`	Sí	ID etiquetado de la regla de federación a evaluar.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Sí	UUID de tu organización de Anthropic. Encuéntralo en la Claude Console en Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	Una de `_TOKEN_FILE` o `_TOKEN`	Ruta del sistema de archivos al JWT emitido por tu "identity provider" (proveedor de identidad), o IdP. El SDK vuelve a leer este archivo en cada intercambio para que los tokens proyectados que rotan en disco estén siempre actualizados.	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	Una de `_TOKEN_FILE` o `_TOKEN`	El JWT literal como cadena. Úsala cuando tu plataforma inyecta el token como una variable de entorno en lugar de un archivo.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Sí	ID etiquetado de la cuenta de servicio de Anthropic de destino como la cual actúa el token de acceso emitido.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Condicional	ID etiquetado del workspace al que se limitará el token emitido, o el literal `default`. Requerido cuando la regla de federación está habilitada para más de un workspace; opcional cuando la regla está vinculada a un solo workspace. El token emitido se limita a este workspace en el momento del intercambio, por lo que cambiar de workspace requiere un nuevo intercambio.	`wrkspc_...`
`ANTHROPIC_PROFILE`	No	Nombre de un perfil de configuración a cargar. Tiene precedencia sobre las variables de entorno de federación de esta tabla.	`staging-profile`

La ruta de federación directa por 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 establecidas. ANTHROPIC_WORKSPACE_ID se lee junto con ellas pero no condiciona la activación.

Una variable que está establecida en una cadena vacía aún ocupa su lugar en la cadena de precedencia de credenciales. Si se exporta ANTHROPIC_API_KEY="", el SDK selecciona la ruta de clave de API con una clave vacía en lugar de pasar a la federación. Elimina las variables de credenciales no utilizadas en lugar de dejarlas en blanco.

Precedencia de credenciales

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

Orden	Fuente	Notas
1	Argumento del constructor (`api_key=`, `auth_token=`, `credentials=`)	Siempre anula todo lo demás.
2	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN`	Eclipsa la federación por completo. Elimina estas variables al migrar desde claves de API.
3	`ANTHROPIC_PROFILE`	Carga `<config_dir>/configs/<name>.json`. Un perfil nombrado que falta es un error, no un paso al siguiente nivel.
4	Variables de entorno de federación	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	Perfil activo	Resuelto desde `<config_dir>/active_config`, recurriendo a un perfil llamado `default`.

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

Archivo de configuración de perfil

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

Directorio de configuración

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

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

Perfil activo

El nombre del perfil activo se resuelve en este orden:

$ANTHROPIC_PROFILE
El contenido de <config_dir>/active_config (un archivo de una línea escrito por ant profile activate <name>)
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

Ruta	Contenido	Sensibilidad
`<config_dir>/configs/<profile>.json`	`version`, el bloque `authentication`, `organization_id`, `workspace_id` y `base_url`.	No secreto. Seguro para confirmar en el repositorio o incluir en una imagen.
`<config_dir>/credentials/<profile>.json`	`version`, el `access_token` en caché, `expires_at` y (para inicio de sesión interactivo) `refresh_token`.	Secreto. Escrito por el SDK con modo `0600`.

Tanto el archivo de configuración como el archivo de credenciales llevan un campo de cadena de nivel superior version en formato major.minor (actualmente "1.0"). El SDK escribe este campo automáticamente para que las versiones futuras puedan detectar y migrar formatos más 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

configs/production.json

{
  "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 estableces en una regla de federación determina a qué endpoints de la Claude API puede llamar el token de acceso emitido.

Alcance	Otorga acceso a
`workspace:developer`	Todos los endpoints no administrativos de la Claude API en el workspace de la regla: Messages (incluyendo streaming y conteo de tokens), Models, Managed Agents y sus sesiones, Files y Skills. Esto coincide con el acceso que tiene una clave de API emitida para el mismo workspace.
`workspace:inference`	Los endpoints de inferencia en el workspace de la regla: Messages (incluyendo streaming y conteo de tokens), Models y el endpoint de chat compatible con OpenAI. Usa esto para cargas de trabajo que solo necesitan llamar a Claude y nunca necesitan administrar Files, Skills u otros recursos.
`workspace:manage_tunnels`	La API de túneles MCP: crear, listar y obtener túneles, registrar y archivar certificados de CA, revelar y rotar el token del túnel, y archivar túneles. La ventana modal de creación de túneles de la Console bloquea este alcance cuando creas una regla desde ella.
`org:admin`	Acceso completo a la Admin API (miembros de la organización, invitaciones, workspaces, claves de API y el resto). Un token OAuth `org:admin` solo puede crear o modificar reglas con alcance `workspace:developer` o `workspace:inference`, y no puede actualizar un emisor que respalde una regla con cualquier otro alcance; consulta las restricciones.

Una solicitud a un endpoint fuera del alcance del token devuelve HTTP 403. Los alcances más granulares (por recurso, o lectura frente a escritura) no están disponibles actualmente.

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é 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.

`oauth_scope` de la regla	`organization_role` de la cuenta de servicio	Permisos efectivos
`workspace:developer`	`admin`	Acceso a la Claude API solo en el workspace de la regla. El alcance limita el token por debajo del rol.
`org:admin`	`admin`	Acceso completo a la Admin API (miembros de la organización, invitaciones, workspaces, claves de API y el resto), menos las exclusiones para llamadores OAuth; consulta las restricciones.

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 detalles completos de parámetros y 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

Campo	Restricción
`name` del emisor, la regla y la cuenta de servicio	Debe coincidir con `^[a-z0-9-]+$`, longitud de 1 a 255 caracteres.
`workspace_id`	Requerido al crear a menos que `applies_to_all_workspaces` sea true. El workspace (`wrkspc_...`) cuya cuota, facturación y límites de velocidad se aplican a los tokens emitidos bajo esta regla. Debe ser un workspace en la misma organización, y la cuenta de servicio de destino debe ser miembro de ese workspace.
`applies_to_all_workspaces`	Booleano. Establécelo en `true` para habilitar la regla en todos los workspaces de la organización en lugar de nombrar uno; se requiere este campo o `workspace_id` al crear.
`token_lifetime_seconds`	Entero entre `60` y `86400` (1 minuto a 24 horas). Predeterminado `3600`. Los valores fuera de este rango se rechazan en el momento de la solicitud. Consulta Duración y renovación del token.

Campos de URL

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

Restricción	Detalle
Esquema	Debe ser `https`.
Puerto	Debe ser `443` (explícito o predeterminado).
Host	Debe ser un nombre de host DNS público para tu proveedor OIDC. Debe resolverse a direcciones IP públicas; no se aceptan literales de IP.

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).

Las restricciones de URL se aplican solo a las URL que Anthropic contacta. En los modos JWKS explicit_url e inline, y en el modo discovery cuando jwks.discovery_base está establecido, la issuer_url se compara con el claim iss del JWT como una cadena y nunca se consulta, por lo que puede hacer referencia a un nombre de host interno o a un puerto no estándar.

Verificación de JWT

Restricción	Detalle
Tamaño máximo	El JWT de `assertion` debe tener como máximo 16 KiB.
Algoritmo de firma	Solo se aceptan algoritmos asimétricos (familias RSA y ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) y `none` se rechazan.
ID de clave	El encabezado del JWT debe llevar un `kid` que coincida con una clave en el JWKS del emisor. Los tokens sin `kid` se rechazan.
Claims requeridos	`sub` debe estar presente. `iat` debe estar presente y no estar en el futuro. `exp` debe estar presente y estar en el futuro.
Duración máxima	La duración del token (`exp` menos `iat`) no debe exceder el máximo configurado del emisor (1 hora de forma predeterminada, configurable para cada emisor en la Claude Console).
Desfase de reloj	Se aplica un margen de 30 segundos a `exp`, `nbf` e `iat`.

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 poblados se evalúan con semántica AND: el JWT debe satisfacer cada comparador poblado. Al menos uno de subject_prefix, claims o condition debe estar establecido; un bloque match que contiene solo audience (o ningún comparador en absoluto) se rechaza. Esto protege contra reglas que aceptarían todos los tokens de un emisor.

Comparador	Tipo	Semántica
`subject_prefix`	string	Coincidencia exacta con el claim `sub` del JWT. Un `` al final lo convierte en una coincidencia de prefijo (el valor de `sub` debe comenzar con los caracteres anteriores al ``). Distingue mayúsculas y minúsculas.
`audience`	string	El claim `aud` del JWT debe contener esta cadena exacta. Cuando `aud` es un arreglo, cualquier elemento que coincida exactamente satisface la verificación.
`claims`	map<string, string>	Cada clave es un nombre de claim de nivel superior y cada valor es el valor de cadena exacto requerido. Para claims anidados, numéricos, booleanos o complejos como listas y mapas, usa `condition` con una expresión CEL en su lugar.
`condition`	string (CEL)	Una expresión CEL que debe evaluarse a `true`.

Entorno de evaluación CEL

La expresión condition tiene acceso a una sola variable:

Variable	Tipo	Contenido
`claims`	map	El conjunto completo de claims del JWT decodificado. Los objetos anidados son accesibles como mapas anidados.

Ejemplo:

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

Las condiciones CEL son límites de seguridad. Una expresión que se evalúa a true para más entradas de las previstas otorga un acceso más amplio del previsto. Prefiere los comparadores estáticos cuando expresen tu restricción.

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 el equivalente del lenguaje) que expone el estado HTTP, el cuerpo de la respuesta y el request_id.

Estado	Error	Causa	Resolución
400	`invalid_request`	`federation_rule_id` está mal formado o falta un campo requerido de la solicitud.	Verifica el ID `fdrl_` y que el cuerpo de la solicitud incluya todos los campos requeridos.
400	`invalid_request`	`workspace_id_required`: la regla de federación está habilitada para más de un workspace y la solicitud omite `workspace_id`.	Establece `ANTHROPIC_WORKSPACE_ID` (o el campo `workspace_id` del cuerpo en una solicitud sin procesar) al ID `wrkspc_...` al que quieres limitar el token. Consulta Solicitud de intercambio de tokens.
400	`invalid_grant`	El claim `iss` del JWT no es exactamente igual a la `issuer_url` registrada.	Compara byte por byte, incluyendo barras finales y esquema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	La obtención del JWKS falló, el JWKS está obsoleto o el JWT fue firmado con una clave que no está en el JWKS.	Para el modo `inline`, actualiza el emisor con las claves rotadas. Para `discovery` y `explicit_url`, confirma que el endpoint del JWKS sea accesible en el puerto 443; si el emisor rotó recientemente su clave de firma, consulta Rotación de claves y almacenamiento en caché.
400	`invalid_grant`	El claim `exp` del JWT está en el pasado (más allá de la ventana de desfase de 30 segundos).	Confirma que tu proveedor de identidad esté proyectando un token nuevo y que el SDK esté volviendo a leer el archivo del token.
400	`invalid_grant`	El JWT fue verificado pero sus claims no satisfacen el bloque `match` de la regla.	Decodifica el JWT y compara cada claim con la regla. `subject_prefix` distingue mayúsculas y minúsculas. `audience` requiere una coincidencia exacta de elemento.
400	`invalid_grant`	El `federation_rule_id` no existe, está archivado o el JWT no está autorizado para él (consolidado para prevenir la enumeración).	Confirma el ID de la regla en la Claude Console y que la regla no haya sido archivada.

Todos los fallos invalid_grant devuelven HTTP 400; la causa específica se registra solo del lado del servidor y no se expone en la respuesta.

Fallos comunes del lado del SDK

Síntoma	Causa	Resolución
El SDK informa "no credentials" en lugar de intercambiar	Una de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` o `ANTHROPIC_IDENTITY_TOKEN[_FILE]` no está establecida y no hay ningún perfil activo.	Establece las cuatro variables o configura un perfil.
El SDK se autentica con una clave de API en lugar de federar	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` está establecida y gana en precedencia.	Elimina la variable de clave o token.
`FileNotFoundError` en la primera solicitud	La ruta en `ANTHROPIC_IDENTITY_TOKEN_FILE` no existe. El SDK abre el archivo de forma diferida en el momento del intercambio.	Confirma que el volumen del token proyectado esté montado y que la ruta coincida.
El intercambio de tokens tiene éxito pero una solicitud a la Claude API devuelve 403	El alcance del token emitido no otorga acceso a ese endpoint.	Verifica el `oauth_scope` de la regla contra los alcances de OAuth.
La autenticación falla con una credencial vacía	Una variable de entorno de credencial está exportada pero establecida en una cadena vacía. Los valores vacíos aún ganan su lugar en la precedencia.	Elimina la variable con `unset VAR` en lugar de `VAR=""`.

Solucionar un intercambio fallido

Una respuesta 400 invalid_grant es intencionalmente opaca; la causa específica se registra solo del lado del servidor.

Comienza con la página de historial de autenticación en la Claude Console. Los intentos de intercambio recientes muestran el emisor y la regla que se evaluaron, los claims del JWT que se inspeccionaron y qué paso de validación falló, lo que generalmente evita tener que realizar las siguientes verificaciones.

Si aún necesitas depurar desde el propio JWT, realiza estas verificaciones en orden:

Decodifica el JWT
Decodifica la assertion que enviaste para poder comparar cada claim con la configuración de tu emisor y regla:
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
Verifica que iss coincida con el emisor
El claim iss decodificado debe ser igual a la issuer_url registrada byte por byte, incluyendo el esquema, el puerto y cualquier barra final. Una discrepancia en un solo carácter hace fallar la verificación.
Verifica que aud coincida con la regla
El claim aud decodificado debe contener el valor audience de la regla como una coincidencia exacta. Cuando aud es un arreglo, un elemento debe coincidir exactamente.
Verifica sub y cada entrada de claims
Compara sub con el subject_prefix de la regla (distingue mayúsculas y minúsculas; un * al final es una coincidencia de prefijo, cualquier otra cosa es exacta). Compara cada clave en el mapa claims de la regla con el claim de nivel superior del mismo nombre.
Verifica 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 que de otro modo sería válido se rechaza.
Verifica 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 e inmediatamente comenzó a firmar con ella, los intercambios pueden fallar hasta por un minuto mientras se actualiza la caché de JWKS de Anthropic. Consulta Rotación de claves y almacenamiento en 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 utilizadas para verificar las firmas de JWT de ese emisor. Es una unión discriminada con clave en type:

`jwks.type`	Forma de `jwks`	Comportamiento	Úsalo cuando
`discovery` (predeterminado)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` es opcional; establécelo cuando la URL de descubrimiento difiera de `issuer_url`)	Anthropic obtiene `<discovery_base or issuer_url>/.well-known/openid-configuration`, lee `jwks_uri` del documento de descubrimiento y obtiene el JWKS desde allí.	Tu IdP sirve un documento de descubrimiento OIDC estándar en la internet pública. La mayoría de los proveedores administrados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) admiten esto.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic obtiene el JWKS directamente desde `url`. La `issuer_url` se usa solo para la comparación de cadenas con el claim `iss` del JWT y nunca se contacta.	Tu IdP no sirve un documento de descubrimiento, o el descubrimiento es solo interno pero el JWKS es accesible públicamente.
`inline`	`{ "type": "inline", "keys": [...] }`	Proporcionas el arreglo de objetos JWK en línea (el arreglo `keys` del documento JWKS, no el objeto envolvente). Anthropic no realiza ninguna solicitud saliente. La `issuer_url` se usa solo para la comparación de `iss`.	Entornos aislados (air-gapped), clústeres de Kubernetes autogestionados con URL de emisor internas al clúster, o cuando quieres control explícito sobre la rotación de claves.

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 e inmediatamente comienza a firmar tokens con ella, los intercambios que presenten esos tokens pueden fallar con un error de firma hasta por 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 nuevas claves antes del primer uso.

En el modo inline no hay actualización automática de claves. Cuando tu proveedor de identidad rota sus claves de firma, debes actualizar la configuración del emisor con el nuevo JWKS o todos los intercambios de tokens fallarán en la verificación de firma.

Was this page helpful?

AdministraciónAutenticación

Referencia de WIF

Variables de entorno, reglas de validación, configuración de perfiles y referencia de errores para Workload Identity Federation.

Solicitud de intercambio de tokens

Campo	Requerido	Descripción
`grant_type`	Sí	Siempre `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Sí	El JWT OIDC emitido por tu proveedor de identidad.
`federation_rule_id`	Sí	ID etiquetado (`fdrl_...`) de la regla de federación a evaluar.
`organization_id`	Sí	UUID de tu organización de Anthropic.
`service_account_id`	Sí	ID etiquetado (`svac_...`) de la cuenta de servicio de destino.
`workspace_id`	Condicional	ID etiquetado (`wrkspc_...`) del workspace al que se limitará el token emitido, o el literal `default` para el workspace predeterminado de la organización. Requerido cuando la regla está habilitada para más de un workspace. Cuando se omite, el servidor selecciona el único workspace habilitado de la regla.

Respuesta de intercambio de tokens

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

Campo	Tipo	Descripción
`access_token`	string	El token de Anthropic de corta duración, con el prefijo `sk-ant-oat01-...`. Pásalo como `Authorization: Bearer <token>`.
`token_type`	string	Siempre `Bearer`.
`expires_in`	integer	Segundos hasta que el token expire.
`scope`	string	El alcance de OAuth otorgado por la regla coincidente.

Variables de entorno

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

Variable	Requerida	Descripción	Ejemplo
`ANTHROPIC_FEDERATION_RULE_ID`	Sí	ID etiquetado de la regla de federación a evaluar.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Sí	UUID de tu organización de Anthropic. Encuéntralo en la Claude Console en Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	Una de `_TOKEN_FILE` o `_TOKEN`	Ruta del sistema de archivos al JWT emitido por tu "identity provider" (proveedor de identidad), o IdP. El SDK vuelve a leer este archivo en cada intercambio para que los tokens proyectados que rotan en disco estén siempre actualizados.	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	Una de `_TOKEN_FILE` o `_TOKEN`	El JWT literal como cadena. Úsala cuando tu plataforma inyecta el token como una variable de entorno en lugar de un archivo.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Sí	ID etiquetado de la cuenta de servicio de Anthropic de destino como la cual actúa el token de acceso emitido.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Condicional	ID etiquetado del workspace al que se limitará el token emitido, o el literal `default`. Requerido cuando la regla de federación está habilitada para más de un workspace; opcional cuando la regla está vinculada a un solo workspace. El token emitido se limita a este workspace en el momento del intercambio, por lo que cambiar de workspace requiere un nuevo intercambio.	`wrkspc_...`
`ANTHROPIC_PROFILE`	No	Nombre de un perfil de configuración a cargar. Tiene precedencia sobre las variables de entorno de federación de esta tabla.	`staging-profile`

Precedencia de credenciales

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

Orden	Fuente	Notas
1	Argumento del constructor (`api_key=`, `auth_token=`, `credentials=`)	Siempre anula todo lo demás.
2	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN`	Eclipsa la federación por completo. Elimina estas variables al migrar desde claves de API.
3	`ANTHROPIC_PROFILE`	Carga `<config_dir>/configs/<name>.json`. Un perfil nombrado que falta es un error, no un paso al siguiente nivel.
4	Variables de entorno de federación	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	Perfil activo	Resuelto desde `<config_dir>/active_config`, recurriendo a un perfil llamado `default`.

Archivo de configuración de perfil

Directorio de configuración

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

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

Perfil activo

El nombre del perfil activo se resuelve en este orden:

$ANTHROPIC_PROFILE
El contenido de <config_dir>/active_config (un archivo de una línea escrito por ant profile activate <name>)
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

Ruta	Contenido	Sensibilidad
`<config_dir>/configs/<profile>.json`	`version`, el bloque `authentication`, `organization_id`, `workspace_id` y `base_url`.	No secreto. Seguro para confirmar en el repositorio o incluir en una imagen.
`<config_dir>/credentials/<profile>.json`	`version`, el `access_token` en caché, `expires_at` y (para inicio de sesión interactivo) `refresh_token`.	Secreto. Escrito por el SDK con modo `0600`.

Ejemplo de perfil de federación

configs/production.json

{
  "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 estableces en una regla de federación determina a qué endpoints de la Claude API puede llamar el token de acceso emitido.

Alcance	Otorga acceso a
`workspace:developer`	Todos los endpoints no administrativos de la Claude API en el workspace de la regla: Messages (incluyendo streaming y conteo de tokens), Models, Managed Agents y sus sesiones, Files y Skills. Esto coincide con el acceso que tiene una clave de API emitida para el mismo workspace.
`workspace:inference`	Los endpoints de inferencia en el workspace de la regla: Messages (incluyendo streaming y conteo de tokens), Models y el endpoint de chat compatible con OpenAI. Usa esto para cargas de trabajo que solo necesitan llamar a Claude y nunca necesitan administrar Files, Skills u otros recursos.
`workspace:manage_tunnels`	La API de túneles MCP: crear, listar y obtener túneles, registrar y archivar certificados de CA, revelar y rotar el token del túnel, y archivar túneles. La ventana modal de creación de túneles de la Console bloquea este alcance cuando creas una regla desde ella.
`org:admin`	Acceso completo a la Admin API (miembros de la organización, invitaciones, workspaces, claves de API y el resto). Un token OAuth `org:admin` solo puede crear o modificar reglas con alcance `workspace:developer` o `workspace:inference`, y no puede actualizar un emisor que respalde una regla con cualquier otro alcance; consulta las restricciones.

Una solicitud a un endpoint fuera del alcance del token devuelve HTTP 403. Los alcances más granulares (por recurso, o lectura frente a escritura) no están disponibles actualmente.

Límites de permisos

`oauth_scope` de la regla	`organization_role` de la cuenta de servicio	Permisos efectivos
`workspace:developer`	`admin`	Acceso a la Claude API solo en el workspace de la regla. El alcance limita el token por debajo del rol.
`org:admin`	`admin`	Acceso completo a la Admin API (miembros de la organización, invitaciones, workspaces, claves de API y el resto), menos las exclusiones para llamadores OAuth; consulta las restricciones.

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.

Campos de recursos

Campo	Restricción
`name` del emisor, la regla y la cuenta de servicio	Debe coincidir con `^[a-z0-9-]+$`, longitud de 1 a 255 caracteres.
`workspace_id`	Requerido al crear a menos que `applies_to_all_workspaces` sea true. El workspace (`wrkspc_...`) cuya cuota, facturación y límites de velocidad se aplican a los tokens emitidos bajo esta regla. Debe ser un workspace en la misma organización, y la cuenta de servicio de destino debe ser miembro de ese workspace.
`applies_to_all_workspaces`	Booleano. Establécelo en `true` para habilitar la regla en todos los workspaces de la organización en lugar de nombrar uno; se requiere este campo o `workspace_id` al crear.
`token_lifetime_seconds`	Entero entre `60` y `86400` (1 minuto a 24 horas). Predeterminado `3600`. Los valores fuera de este rango se rechazan en el momento de la solicitud. Consulta Duración y renovación del token.

Campos de URL

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

Restricción	Detalle
Esquema	Debe ser `https`.
Puerto	Debe ser `443` (explícito o predeterminado).
Host	Debe ser un nombre de host DNS público para tu proveedor OIDC. Debe resolverse a direcciones IP públicas; no se aceptan literales de IP.

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

Restricción	Detalle
Tamaño máximo	El JWT de `assertion` debe tener como máximo 16 KiB.
Algoritmo de firma	Solo se aceptan algoritmos asimétricos (familias RSA y ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) y `none` se rechazan.
ID de clave	El encabezado del JWT debe llevar un `kid` que coincida con una clave en el JWKS del emisor. Los tokens sin `kid` se rechazan.
Claims requeridos	`sub` debe estar presente. `iat` debe estar presente y no estar en el futuro. `exp` debe estar presente y estar en el futuro.
Duración máxima	La duración del token (`exp` menos `iat`) no debe exceder el máximo configurado del emisor (1 hora de forma predeterminada, configurable para cada emisor en la Claude Console).
Desfase de reloj	Se aplica un margen de 30 segundos a `exp`, `nbf` e `iat`.

Semántica de coincidencia de reglas

Comparador	Tipo	Semántica
`subject_prefix`	string	Coincidencia exacta con el claim `sub` del JWT. Un `` al final lo convierte en una coincidencia de prefijo (el valor de `sub` debe comenzar con los caracteres anteriores al ``). Distingue mayúsculas y minúsculas.
`audience`	string	El claim `aud` del JWT debe contener esta cadena exacta. Cuando `aud` es un arreglo, cualquier elemento que coincida exactamente satisface la verificación.
`claims`	map<string, string>	Cada clave es un nombre de claim de nivel superior y cada valor es el valor de cadena exacto requerido. Para claims anidados, numéricos, booleanos o complejos como listas y mapas, usa `condition` con una expresión CEL en su lugar.
`condition`	string (CEL)	Una expresión CEL que debe evaluarse a `true`.

Entorno de evaluación CEL

La expresión condition tiene acceso a una sola variable:

Variable	Tipo	Contenido
`claims`	map	El conjunto completo de claims del JWT decodificado. Los objetos anidados son accesibles como mapas anidados.

Ejemplo:

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

Errores

Errores de intercambio de tokens

Estado	Error	Causa	Resolución
400	`invalid_request`	`federation_rule_id` está mal formado o falta un campo requerido de la solicitud.	Verifica el ID `fdrl_` y que el cuerpo de la solicitud incluya todos los campos requeridos.
400	`invalid_request`	`workspace_id_required`: la regla de federación está habilitada para más de un workspace y la solicitud omite `workspace_id`.	Establece `ANTHROPIC_WORKSPACE_ID` (o el campo `workspace_id` del cuerpo en una solicitud sin procesar) al ID `wrkspc_...` al que quieres limitar el token. Consulta Solicitud de intercambio de tokens.
400	`invalid_grant`	El claim `iss` del JWT no es exactamente igual a la `issuer_url` registrada.	Compara byte por byte, incluyendo barras finales y esquema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	La obtención del JWKS falló, el JWKS está obsoleto o el JWT fue firmado con una clave que no está en el JWKS.	Para el modo `inline`, actualiza el emisor con las claves rotadas. Para `discovery` y `explicit_url`, confirma que el endpoint del JWKS sea accesible en el puerto 443; si el emisor rotó recientemente su clave de firma, consulta Rotación de claves y almacenamiento en caché.
400	`invalid_grant`	El claim `exp` del JWT está en el pasado (más allá de la ventana de desfase de 30 segundos).	Confirma que tu proveedor de identidad esté proyectando un token nuevo y que el SDK esté volviendo a leer el archivo del token.
400	`invalid_grant`	El JWT fue verificado pero sus claims no satisfacen el bloque `match` de la regla.	Decodifica el JWT y compara cada claim con la regla. `subject_prefix` distingue mayúsculas y minúsculas. `audience` requiere una coincidencia exacta de elemento.
400	`invalid_grant`	El `federation_rule_id` no existe, está archivado o el JWT no está autorizado para él (consolidado para prevenir la enumeración).	Confirma el ID de la regla en la Claude Console y que la regla no haya sido archivada.

Todos los fallos invalid_grant devuelven HTTP 400; la causa específica se registra solo del lado del servidor y no se expone en la respuesta.

Fallos comunes del lado del SDK

Síntoma	Causa	Resolución
El SDK informa "no credentials" en lugar de intercambiar	Una de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` o `ANTHROPIC_IDENTITY_TOKEN[_FILE]` no está establecida y no hay ningún perfil activo.	Establece las cuatro variables o configura un perfil.
El SDK se autentica con una clave de API en lugar de federar	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` está establecida y gana en precedencia.	Elimina la variable de clave o token.
`FileNotFoundError` en la primera solicitud	La ruta en `ANTHROPIC_IDENTITY_TOKEN_FILE` no existe. El SDK abre el archivo de forma diferida en el momento del intercambio.	Confirma que el volumen del token proyectado esté montado y que la ruta coincida.
El intercambio de tokens tiene éxito pero una solicitud a la Claude API devuelve 403	El alcance del token emitido no otorga acceso a ese endpoint.	Verifica el `oauth_scope` de la regla contra los alcances de OAuth.
La autenticación falla con una credencial vacía	Una variable de entorno de credencial está exportada pero establecida en una cadena vacía. Los valores vacíos aún ganan su lugar en la precedencia.	Elimina la variable con `unset VAR` en lugar de `VAR=""`.

Solucionar un intercambio fallido

Una respuesta 400 invalid_grant es intencionalmente opaca; la causa específica se registra solo del lado del servidor.

Si aún necesitas depurar desde el propio JWT, realiza estas verificaciones en orden:

Decodifica el JWT
Decodifica la assertion que enviaste para poder comparar cada claim con la configuración de tu emisor y regla:
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
Verifica que iss coincida con el emisor
El claim iss decodificado debe ser igual a la issuer_url registrada byte por byte, incluyendo el esquema, el puerto y cualquier barra final. Una discrepancia en un solo carácter hace fallar la verificación.
Verifica que aud coincida con la regla
El claim aud decodificado debe contener el valor audience de la regla como una coincidencia exacta. Cuando aud es un arreglo, un elemento debe coincidir exactamente.
Verifica sub y cada entrada de claims
Compara sub con el subject_prefix de la regla (distingue mayúsculas y minúsculas; un * al final es una coincidencia de prefijo, cualquier otra cosa es exacta). Compara cada clave en el mapa claims de la regla con el claim de nivel superior del mismo nombre.
Verifica 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 que de otro modo sería válido se rechaza.
Verifica 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 e inmediatamente comenzó a firmar con ella, los intercambios pueden fallar hasta por un minuto mientras se actualiza la caché de JWKS de Anthropic. Consulta Rotación de claves y almacenamiento en caché.

Modos de origen de JWKS

`jwks.type`	Forma de `jwks`	Comportamiento	Úsalo cuando
`discovery` (predeterminado)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` es opcional; establécelo cuando la URL de descubrimiento difiera de `issuer_url`)	Anthropic obtiene `<discovery_base or issuer_url>/.well-known/openid-configuration`, lee `jwks_uri` del documento de descubrimiento y obtiene el JWKS desde allí.	Tu IdP sirve un documento de descubrimiento OIDC estándar en la internet pública. La mayoría de los proveedores administrados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) admiten esto.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic obtiene el JWKS directamente desde `url`. La `issuer_url` se usa solo para la comparación de cadenas con el claim `iss` del JWT y nunca se contacta.	Tu IdP no sirve un documento de descubrimiento, o el descubrimiento es solo interno pero el JWKS es accesible públicamente.
`inline`	`{ "type": "inline", "keys": [...] }`	Proporcionas el arreglo de objetos JWK en línea (el arreglo `keys` del documento JWKS, no el objeto envolvente). Anthropic no realiza ninguna solicitud saliente. La `issuer_url` se usa solo para la comparación de `iss`.	Entornos aislados (air-gapped), clústeres de Kubernetes autogestionados con URL de emisor internas al clúster, o cuando quieres control explícito sobre la rotación de claves.

Rotación de claves y almacenamiento en caché

Was this page helpful?

Solicitud de intercambio de tokens

Respuesta de intercambio de tokens

Variables de entorno

Precedencia de credenciales

Archivo de configuración de perfil

Directorio de configuración

Perfil activo

Estructura de archivos

Ejemplo de perfil de federación

Alcances de OAuth

Límites de permisos

Reglas de validación

Campos de recursos

Campos de URL

Verificación de JWT

Semántica de coincidencia de reglas

Entorno de evaluación CEL

Errores

Errores de intercambio de tokens

Fallos comunes del lado del SDK

Solucionar un intercambio fallido

Modos de origen de JWKS

Rotación de claves y almacenamiento en caché

Solicitud de intercambio de tokens

Respuesta de intercambio de tokens

Variables de entorno

Precedencia de credenciales

Archivo de configuración de perfil

Directorio de configuración

Perfil activo

Estructura de archivos

Ejemplo de perfil de federación

Alcances de OAuth

Límites de permisos

Reglas de validación

Campos de recursos

Campos de URL

Verificación de JWT

Semántica de coincidencia de reglas

Entorno de evaluación CEL

Errores

Errores de intercambio de tokens

Fallos comunes del lado del SDK

Solucionar un intercambio fallido

Modos de origen de JWKS

Rotación de claves y almacenamiento en caché

Solicitud de intercambio de tokens

Respuesta de intercambio de tokens

Variables de entorno

Precedencia de credenciales

Archivo de configuración de perfil

Directorio de configuración

Perfil activo

Estructura de archivos

Ejemplo de perfil de federación

Alcances de OAuth

Límites de permisos

Reglas de validación

Campos de recursos

Campos de URL

Verificación de JWT

Semántica de coincidencia de reglas

Entorno de evaluación CEL

Errores

Errores de intercambio de tokens

Fallos comunes del lado del SDK

Solucionar un intercambio fallido

Modos de origen de JWKS

Rotación de claves y almacenamiento en caché

Solicitud de intercambio de tokens

Respuesta de intercambio de tokens

Variables de entorno

Precedencia de credenciales

Archivo de configuración de perfil

Directorio de configuración

Perfil activo

Estructura de archivos

Ejemplo de perfil de federación

Alcances de OAuth

Límites de permisos

Reglas de validación

Campos de recursos

Campos de URL

Verificación de JWT

Semántica de coincidencia de reglas

Entorno de evaluación CEL

Errores

Errores de intercambio de tokens

Fallos comunes del lado del SDK

Solucionar un intercambio fallido

Modos de origen de JWKS

Rotación de claves y almacenamiento en caché