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 correspondencias de errores para Workload Identity Federation. Para ver tutoriales de configuración, consulta las guías de proveedores.

Solicitud de intercambio de token

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.

Campo	Obligatorio	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 espacio de trabajo al que se limitará el token emitido, o el literal `default` para el espacio de trabajo predeterminado de la organización. Obligatorio cuando la regla está habilitada para más de un espacio de trabajo. Cuando se omite, el servidor selecciona el único espacio de trabajo habilitado de la regla.

Respuesta de intercambio de token

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 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 scope de OAuth otorgado por la regla coincidente.

Variables de entorno

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

Variable	Obligatoria	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 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 proveedor de identidad (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. Úsalo cuando tu plataforma inyecta el token como variable de entorno en lugar de como archivo.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Sí	ID etiquetado de la cuenta de servicio de Anthropic de destino en cuyo nombre actúa el token de acceso emitido.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Condicional	ID etiquetado del espacio de trabajo al que se limitará el token emitido, o el literal `default`. Obligatorio cuando la regla de federación está habilitada para más de un espacio de trabajo; opcional cuando la regla está vinculada a un solo espacio de trabajo. El token emitido se limita a este espacio de trabajo en el momento del intercambio, por lo que cambiar de espacio de trabajo requiere un nuevo intercambio.	`wrkspc_...`
`ANTHROPIC_PROFILE`	No	Nombre de un perfil de configuración a cargar. Tiene prioridad 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 definidas. ANTHROPIC_WORKSPACE_ID se lee junto con ellas pero no condiciona la activación.

Una variable que está definida como cadena vacía sigue ocupando 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 no existe 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 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 tanto el SDK como la CLI ant leen. Los perfiles te permiten incluir 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:

$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 hacer commit 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 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

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.

Scopes de OAuth

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

Scope	Otorga acceso a
`workspace:developer`	Todos los endpoints no administrativos de la API de Claude en el espacio de trabajo de la regla: Messages (incluido 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 espacio de trabajo.
`org:manage_tunnels`	La API de túneles MCP: listar y obtener túneles, registrar y archivar certificados de CA, revelar y rotar el token del túnel, y archivar túneles. El modal de creación de túnel de la Consola fija este scope cuando creas una regla desde él.

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

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` de emisor, regla y cuenta de servicio	Debe coincidir con `^[a-z0-9-]+$`, longitud de 1 a 255 caracteres.
`workspace_id`	Opcional. El espacio de trabajo (`wrkspc_...`) cuya cuota, facturación y límites de velocidad se aplican a los tokens emitidos bajo esta regla. Debe ser un espacio de trabajo de la misma organización, y la cuenta de servicio de destino debe ser miembro de ese espacio de trabajo. Puede omitirse para reglas configuradas para un solo espacio de trabajo.
`token_lifetime_seconds`	Entero entre `60` y `86400` (de 1 minuto a 24 horas). Valor predeterminado `3600`. Los valores fuera de este rango se rechazan en el momento de la solicitud. Consulta Duración y actualizació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 de 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 a las que Anthropic se conecta. En los modos JWKS explicit_url e inline, y en el modo discovery cuando jwks.discovery_base está definido, el issuer_url se compara con el claim iss del JWT como 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 obligatorios	`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 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 completados se evalúan con semántica AND: el JWT debe satisfacer todos los matchers completados. 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.

Matcher	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 de 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 como `true`.

Entorno de evaluación de 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 como true para más entradas de las previstas otorga un acceso más amplio del previsto. Prefiere los matchers estáticos cuando expresen tu restricción.

Errores

Errores de intercambio de token

POST /v1/oauth/token devuelve errores en la forma de error de API estándar. El SDK envuelve los fallos de intercambio en un FederationExchangeError tipado (o equivalente según el 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 obligatorio de la solicitud.	Verifica el ID `fdrl_` y que el cuerpo de la solicitud incluya todos los campos obligatorios.
400	`invalid_request`	`workspace_id_required`: la regla de federación está habilitada para más de un espacio de trabajo y la solicitud omite `workspace_id`.	Define `ANTHROPIC_WORKSPACE_ID` (o el campo `workspace_id` del cuerpo en una solicitud sin procesar) con el ID `wrkspc_...` al que quieres limitar el token. Consulta Solicitud de intercambio de token.
400	`invalid_grant`	El claim `iss` del JWT no es exactamente igual al `issuer_url` registrado.	Compara byte por byte, incluidas las barras finales y el 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 se firmó 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 JWKS es 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 se verificó 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 de 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 evitar enumeración).	Confirma el ID de la regla en 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 realizar el intercambio	Una de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` o `ANTHROPIC_IDENTITY_TOKEN[_FILE]` no está definida y no hay ningún perfil activo.	Define 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á definida y gana la 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 de token proyectado está montado y que la ruta coincide.
El intercambio de token tiene éxito pero una solicitud a la API de Claude devuelve 403	El scope del token emitido no otorga acceso a ese endpoint.	Verifica el `oauth_scope` de la regla contra Scopes de OAuth.
La autenticación falla con credencial vacía	Una variable de entorno de credencial está exportada pero definida como cadena vacía. Los valores vacíos aún ganan su lugar de precedencia.	Elimina la variable con `unset VAR` en lugar de `VAR=""`.

Solucionar problemas de 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 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 aserción 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 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.
Verifica 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.
Verifica sub y cada entrada de claims
Compara sub con el subject_prefix de la regla (distingue mayúsculas de minúsculas; un * al 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.
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 por lo demás 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 resuelve. Para explicit_url, obtén la URL del JWKS directamente. Para inline, confirma que la clave de firma del emisor no ha 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 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 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	Usar cuando
`discovery` (predeterminado)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` es opcional; defínelo 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 gestionados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) admiten esto.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic obtiene el JWKS directamente desde `url`. El `issuer_url` se usa solo para comparación de cadenas con el claim `iss` del JWT y nunca se consulta.	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 contenedor). Anthropic no realiza ninguna solicitud saliente. El `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 durante hasta un 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 gestionados suelen seguir 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 publica las nuevas claves antes de su 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 token fallarán 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 token

Campo	Obligatorio	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 espacio de trabajo al que se limitará el token emitido, o el literal `default` para el espacio de trabajo predeterminado de la organización. Obligatorio cuando la regla está habilitada para más de un espacio de trabajo. Cuando se omite, el servidor selecciona el único espacio de trabajo habilitado de la regla.

Respuesta de intercambio de token

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 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 scope de OAuth otorgado por la regla coincidente.

Variables de entorno

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

Variable	Obligatoria	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 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 proveedor de identidad (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. Úsalo cuando tu plataforma inyecta el token como variable de entorno en lugar de como archivo.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Sí	ID etiquetado de la cuenta de servicio de Anthropic de destino en cuyo nombre actúa el token de acceso emitido.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Condicional	ID etiquetado del espacio de trabajo al que se limitará el token emitido, o el literal `default`. Obligatorio cuando la regla de federación está habilitada para más de un espacio de trabajo; opcional cuando la regla está vinculada a un solo espacio de trabajo. El token emitido se limita a este espacio de trabajo en el momento del intercambio, por lo que cambiar de espacio de trabajo requiere un nuevo intercambio.	`wrkspc_...`
`ANTHROPIC_PROFILE`	No	Nombre de un perfil de configuración a cargar. Tiene prioridad 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 no existe 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 hacer commit 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.

Scopes de OAuth

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

Scope	Otorga acceso a
`workspace:developer`	Todos los endpoints no administrativos de la API de Claude en el espacio de trabajo de la regla: Messages (incluido 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 espacio de trabajo.
`org:manage_tunnels`	La API de túneles MCP: listar y obtener túneles, registrar y archivar certificados de CA, revelar y rotar el token del túnel, y archivar túneles. El modal de creación de túnel de la Consola fija este scope cuando creas una regla desde él.

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

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` de emisor, regla y cuenta de servicio	Debe coincidir con `^[a-z0-9-]+$`, longitud de 1 a 255 caracteres.
`workspace_id`	Opcional. El espacio de trabajo (`wrkspc_...`) cuya cuota, facturación y límites de velocidad se aplican a los tokens emitidos bajo esta regla. Debe ser un espacio de trabajo de la misma organización, y la cuenta de servicio de destino debe ser miembro de ese espacio de trabajo. Puede omitirse para reglas configuradas para un solo espacio de trabajo.
`token_lifetime_seconds`	Entero entre `60` y `86400` (de 1 minuto a 24 horas). Valor predeterminado `3600`. Los valores fuera de este rango se rechazan en el momento de la solicitud. Consulta Duración y actualizació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 de 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 obligatorios	`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 Claude Console).
Desfase de reloj	Se aplica un margen de 30 segundos a `exp`, `nbf` e `iat`.

Semántica de coincidencia de reglas

Matcher	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 de 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 como `true`.

Entorno de evaluación de 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 token

Estado	Error	Causa	Resolución
400	`invalid_request`	`federation_rule_id` está mal formado o falta un campo obligatorio de la solicitud.	Verifica el ID `fdrl_` y que el cuerpo de la solicitud incluya todos los campos obligatorios.
400	`invalid_request`	`workspace_id_required`: la regla de federación está habilitada para más de un espacio de trabajo y la solicitud omite `workspace_id`.	Define `ANTHROPIC_WORKSPACE_ID` (o el campo `workspace_id` del cuerpo en una solicitud sin procesar) con el ID `wrkspc_...` al que quieres limitar el token. Consulta Solicitud de intercambio de token.
400	`invalid_grant`	El claim `iss` del JWT no es exactamente igual al `issuer_url` registrado.	Compara byte por byte, incluidas las barras finales y el 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 se firmó 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 JWKS es 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 se verificó 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 de 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 evitar enumeración).	Confirma el ID de la regla en 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 realizar el intercambio	Una de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` o `ANTHROPIC_IDENTITY_TOKEN[_FILE]` no está definida y no hay ningún perfil activo.	Define 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á definida y gana la 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 de token proyectado está montado y que la ruta coincide.
El intercambio de token tiene éxito pero una solicitud a la API de Claude devuelve 403	El scope del token emitido no otorga acceso a ese endpoint.	Verifica el `oauth_scope` de la regla contra Scopes de OAuth.
La autenticación falla con credencial vacía	Una variable de entorno de credencial está exportada pero definida como cadena vacía. Los valores vacíos aún ganan su lugar de precedencia.	Elimina la variable con `unset VAR` en lugar de `VAR=""`.

Solucionar problemas de 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 aserción 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 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.
Verifica 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.
Verifica sub y cada entrada de claims
Compara sub con el subject_prefix de la regla (distingue mayúsculas de minúsculas; un * al 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.
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 por lo demás 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 resuelve. Para explicit_url, obtén la URL del JWKS directamente. Para inline, confirma que la clave de firma del emisor no ha 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 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 de JWKS

`jwks.type`	Forma de `jwks`	Comportamiento	Usar cuando
`discovery` (predeterminado)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` es opcional; defínelo 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 gestionados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) admiten esto.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic obtiene el JWKS directamente desde `url`. El `issuer_url` se usa solo para comparación de cadenas con el claim `iss` del JWT y nunca se consulta.	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 contenedor). Anthropic no realiza ninguna solicitud saliente. El `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?