--- title: Referencia de WIF url: https://platform.claude.com/docs/es/manage-claude/wif-reference description: Variables de entorno, reglas de validación, configuración de perfiles y referencia de errores para Workload Identity Federation. --- Esta página recopila las superficies de configuración, las restricciones de validación y las asignaciones de errores para [Workload Identity Federation](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation). Para tutoriales de configuración, consulta las [guías de proveedores](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation#identity-providers). ## Solicitud de intercambio de tokens `POST /v1/oauth/token` acepta un cuerpo JSON que usa la concesión `jwt-bearer` de [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523). El SDK construye esta solicitud por ti a partir de las [variables de entorno](https://platform.claude.com/docs/es/manage-claude/wif-reference#environment-variables); los ejemplos de cURL de 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 de OIDC emitido por tu proveedor de identidad. | | `federation_rule_id` | Sí | ID etiquetado (`fdrl_...`) de la regla de federación que se 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 generado. Es 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. El literal `default` también funciona para el Default Workspace de la organización, pero está obsoleto; usa el ID `wrkspc_...` de ese espacio de trabajo. | ## Respuesta de intercambio de tokens `POST /v1/oauth/token` devuelve una respuesta de token OAuth 2.0 estándar ([RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-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_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 | Obligatoria | Descripción | Ejemplo | | ------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `ANTHROPIC_FEDERATION_RULE_ID` | Sí | ID etiquetado de la regla de federación que se evaluará. | `fdrl_...` | | `ANTHROPIC_ORGANIZATION_ID` | Sí | UUID de tu organización de Anthropic. Encuéntralo en la página [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) en la Claude Console. | `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 inyecte 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 generado. Es obligatoria cuando la regla de federación está habilitada para más de un espacio de trabajo; es opcional cuando la regla está vinculada a un solo espacio de trabajo. El token generado se limita a este espacio de trabajo en el momento del intercambio, por lo que cambiar de espacio de trabajo requiere un nuevo intercambio. El literal `default` también funciona para el Default Workspace, pero está obsoleto; usa su ID `wrkspc_...`. | `wrkspc_...` | | `ANTHROPIC_PROFILE` | No | Nombre de un [perfil de configuración](https://platform.claude.com/docs/es/manage-claude/wif-reference#profile-configuration-file) que se 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 configuradas. `ANTHROPIC_WORKSPACE_ID` se lee junto con ellas, pero no condiciona la activación. Una variable configurada con una 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. Desconfigura 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 de constructor (`api_key=`, `auth_token=`, `credentials=`) | Siempre anula todo lo demás. | | 2 | `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` | Oculta la federación por completo. Desconfigura estas al migrar desde claves de API. | | 3 | `ANTHROPIC_PROFILE` | Carga `/configs/.json`. Un perfil nombrado faltante es un error, no un paso al siguiente. | | 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 `/active_config`, recurriendo a un perfil llamado `default`. | Cuando se carga un perfil, las variables de entorno completan cualquier campo que el perfil omita, pero nunca anulan los campos que el perfil establece explícitamente. Por ejemplo, `ANTHROPIC_WORKSPACE_ID` completa `workspace_id` solo cuando el perfil activo no lo establece. ## Archivo de configuración de perfil Un perfil es un archivo de configuración nombrado que tanto el SDK como la CLI `ant` leen. Los perfiles te permiten enviar parámetros de federación con 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 `/active_config` (un archivo de una línea escrito por `ant profile activate `) 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. ### Diseño de archivos | Ruta | Contenido | Sensibilidad | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `/configs/.json` | `version`, el bloque `authentication`, `organization_id`, `workspace_id` y `base_url`. | No secreto. Seguro para confirmar o incluir en una imagen. | | `/credentials/.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 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 ```json 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 API de Claude puede llamar el token de acceso generado. | Alcance | Otorga acceso a | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Todos los endpoints no administrativos de la API de Claude en el espacio de trabajo de la regla: [Messages](https://platform.claude.com/docs/es/api/messages) (incluyendo streaming y conteo de tokens), [Models](https://platform.claude.com/docs/es/api/models/list), [Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview) y sus sesiones, [Files](https://platform.claude.com/docs/es/build-with-claude/files) y [Skills](https://platform.claude.com/docs/es/build-with-claude/skills-guide). Esto coincide con el acceso que tiene una clave de API de espacio de trabajo en el mismo espacio de trabajo. | | `workspace:inference` | Los endpoints de inferencia en el espacio de trabajo de la regla: [Messages](https://platform.claude.com/docs/es/api/messages) (incluyendo streaming y conteo de tokens), [Models](https://platform.claude.com/docs/es/api/models/list) y el [endpoint de chat compatible con OpenAI](https://platform.claude.com/docs/es/cli-sdks-libraries/libraries/openai-sdk). Úsalo para cargas de trabajo que solo necesitan llamar a Claude y nunca necesitan gestionar Files, Skills u otros recursos. | | `workspace:manage_tunnels` | La [API de túneles MCP](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/reference#tunnels-api): crear, listar y obtener túneles, registrar y archivar certificados 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](https://platform.claude.com/docs/es/manage-claude/admin-api) (miembros de la organización, invitaciones, espacios de trabajo, 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 respalda una regla con cualquier otro alcance; consulta las [restricciones](https://platform.claude.com/docs/es/manage-claude/wif-admin-api#permissions-and-constraints). | Una solicitud a un endpoint fuera del alcance del token devuelve HTTP 403. Los alcances más granulares (por recurso, o lectura versus escritura) no están disponibles actualmente. ### Límites de permisos El `oauth_scope` de una regla de federación es un techo: el token generado 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 API de Claude solo en el espacio de trabajo 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, espacios de trabajo, claves de API y el resto), menos las exclusiones del llamador OAuth; consulta las [restricciones](https://platform.claude.com/docs/es/manage-claude/wif-admin-api#permissions-and-constraints). | ## Reglas de validación Anthropic aplica estas restricciones cuando creas o actualizas emisores y reglas, y cuando verifica 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](https://platform.claude.com/docs/es/api/organization/service_accounts), la [referencia de la API de emisores de federación](https://platform.claude.com/docs/es/api/organization/federation/issuers) y la [referencia de la API de reglas de federación](https://platform.claude.com/docs/es/api/organization/federation/rules). ### 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` | Requerido al crear a menos que `applies_to_all_workspaces` sea verdadero. El espacio de trabajo (`wrkspc_...`) cuya cuota, facturación y límites de velocidad se aplican a los tokens generados bajo esta regla. Debe ser un espacio de trabajo en la misma organización, y la cuenta de servicio de destino debe ser miembro de ese espacio de trabajo. | | `applies_to_all_workspaces` | Booleano. Establece `true` para habilitar la regla en cada espacio de trabajo de la organización en lugar de nombrar uno; se requiere esto 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 de tokens](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation#token-lifetime-and-refresh). | ### 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 marca. En los modos JWKS `explicit_url` e `inline`, y en el modo `discovery` cuando `jwks.discovery_base` está configurado, el `issuer_url` se compara con la reclamación `iss` del JWT como una cadena y nunca se obtiene, por lo que puede hacer referencia a un nombre de host interno o 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). Se rechazan HMAC (`HS256`, `HS384`, `HS512`) y `none`. | | ID de clave | El encabezado del JWT debe incluir un `kid` que coincida con una clave del JWKS del emisor. Se rechazan los tokens sin `kid`. | | Reclamaciones obligatorias | `sub` debe estar presente. `iat` debe estar presente y no estar en el futuro. `exp` debe estar presente y estar en el futuro. | | Uso único | Una aserción que incluye una reclamación `jti` solo se puede intercambiar una vez por emisor: repetir un intercambio con el mismo `jti` se rechaza como repetición. El campo `check_jti` del emisor (habilitado de forma predeterminada) controla esta comprobación; las aserciones sin una reclamación `jti` no están sujetas a ella. Consulta la [referencia de la API de emisores de federación](https://platform.claude.com/docs/es/api/organization/federation/issuers). | | Duración máxima | La duración del token (`exp` menos `iat`) no debe superar 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 configurado; un bloque `match` que contiene solo `audience` (o ningún comparador en absoluto) se rechaza. Esto protege contra reglas que aceptarían cada token de un emisor. | Comparador | Tipo | Semántica | | ---------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject_prefix` | string | Coincidencia exacta con la reclamación `sub` del JWT. Un `*` al final lo convierte en una coincidencia de prefijo (el valor `sub` debe comenzar con los caracteres antes del `*`). Distingue mayúsculas y minúsculas. | | `audience` | string | La reclamación `aud` del JWT debe contener esta cadena exacta. Cuando `aud` es un arreglo, cualquier elemento que coincida exactamente satisface la verificación. | | `claims` | map\ | Cada clave es un nombre de reclamación de nivel superior y cada valor es el valor de cadena exacto requerido. Para reclamaciones anidadas, numéricas, booleanas o complejas como listas y mapas, usa `condition` con una expresión CEL en su lugar. | | `condition` | string (CEL) | Una expresión [CEL](https://cel.dev/) que debe evaluarse como `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 reclamaciones JWT decodificadas. Los objetos anidados son accesibles como mapas anidados. | Ejemplo: ```text wrap 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 comparadores estáticos cuando expresen tu restricción. ## Errores ### Errores de intercambio de tokens `POST /v1/oauth/token` devuelve errores con la [forma de error de la API](https://platform.claude.com/docs/es/api/errors) estándar. El SDK informa un fallo de intercambio como `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`), 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. | Estado | Error | Causa | Resolución | | ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | `federation_rule_id` está mal formado o falta un campo de solicitud requerido. | Verifica el ID `fdrl_` y que el cuerpo de la solicitud incluya todos los campos requeridos. | | 400 | `invalid_request_error` | `workspace_id` está presente pero no es un ID `wrkspc_...` bien formado ni el literal `default`. | Corrige el valor de `workspace_id`; el mensaje de respuesta nombra el formato esperado. | | 401 | `authentication_error` | La reclamación `iss` del JWT no es exactamente igual al `issuer_url` registrado. | Compara byte por byte, incluyendo barras finales y esquema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`. | | 401 | `authentication_error` | La obtención de 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 sea accesible en el puerto 443; si el emisor rotó recientemente su clave de firma, consulta [Rotación y almacenamiento en caché de claves](https://platform.claude.com/docs/es/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | La reclamación `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 de token. | | 401 | `authentication_error` | El JWT se verificó pero sus reclamaciones no satisfacen el bloque `match` de la regla. | Decodifica el JWT y compara cada reclamación con la regla. `subject_prefix` distingue mayúsculas y minúsculas. `audience` requiere una coincidencia exacta de elemento. | | 401 | `authentication_error` | 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. | | 401 | `authentication_error` | La regla de federación está habilitada para más de un espacio de trabajo y la solicitud omite `workspace_id`. La entrada del historial de autenticación muestra la razón `workspace_id_required`. | Establece `ANTHROPIC_WORKSPACE_ID` (o el campo de cuerpo `workspace_id` en una solicitud sin procesar) al ID `wrkspc_...` al que quieres limitar el token. Consulta [Solicitud de intercambio de tokens](https://platform.claude.com/docs/es/manage-claude/wif-reference#token-exchange-request). | Cada denegación de aserción devuelve el mismo `401` `authentication_error` opaco con el mensaje fijo `Authentication failed`, independientemente de qué verificación falló; un error distinguible permitiría a un llamador sondear la configuración de la regla. La razón de denegación se registra en la entrada del intento en el [historial de autenticación](https://platform.claude.com/settings/workload-identity-federation?tab=history) de la Claude Console, por ejemplo `match_subject_prefix` cuando la reclamación `sub` falla el `subject_prefix` de la regla, o `workspace_id_required` cuando la regla abarca múltiples 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 entrada en el historial; sus mensajes de respuesta nombran el problema directamente. Un `401` sin entrada de historial coincidente generalmente significa que el `federation_rule_id` en sí no fue reconocido. ### 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á configurada y no hay ningún perfil activo. | Configura 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á configurada y gana la precedencia. | Desconfigura 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 coincida. | | El intercambio de tokens tiene éxito pero una solicitud a la API de Claude devuelve 403 | El alcance del token generado no otorga acceso a ese endpoint. | Verifica el `oauth_scope` de la regla contra [Alcances de OAuth](https://platform.claude.com/docs/es/manage-claude/wif-reference#oauth-scopes). | | La autenticación falla con credencial vacía | Una variable de entorno de credencial se exporta pero se establece en una cadena vacía. Los valores vacíos aún ganan su lugar de precedencia. | Desconfigura la variable con `unset VAR` en lugar de `VAR=""`. | ## Solucionar un intercambio fallido Una respuesta `401` `authentication_error` es intencionalmente opaca y su mensaje es siempre `Authentication failed`; la razón de denegación se registra en el historial de autenticación, no en la respuesta. Comienza con la [página de historial de autenticación](https://platform.claude.com/settings/workload-identity-federation?tab=history) en la Claude Console. Los intentos de intercambio recientes muestran el emisor y la regla que se evaluaron, las reclamaciones JWT que se inspeccionaron y qué paso de validación falló, lo que generalmente acorta las siguientes verificaciones. Un fallo opaco común es una aserción repetida: una aserción que lleva una reclamación `jti` puede [intercambiarse solo una vez](https://platform.claude.com/docs/es/manage-claude/wif-reference#jwt-verification), por lo que una carga de trabajo que reenvía el mismo JWT (un bucle de reintento, o una renovación que vuelve a leer un token no rotado) se rechaza en el segundo intercambio. La página de historial de autenticación muestra estos intentos con la razón `jti_reused`; la solución es generar una aserción nueva para cada intercambio. Si aún necesitas depurar desde el JWT en sí, trabaja a través de estas verificaciones en orden: Decodifica la aserción que enviaste para poder comparar cada reclamación con la configuración de tu emisor y regla: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` La reclamación `iss` decodificada debe ser igual al `issuer_url` registrado byte por byte, incluyendo esquema, puerto y cualquier barra final. Una discrepancia en un solo carácter falla la verificación. La reclamación `aud` decodificada debe contener el valor `audience` de la regla como una coincidencia exacta. Cuando `aud` es un arreglo, un elemento debe coincidir exactamente. 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 la reclamación de nivel superior del mismo nombre. `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. Para el modo `discovery`, obtén `/.well-known/openid-configuration` sobre HTTPS público en el puerto 443 y confirma que `jwks_uri` se resuelve. Para `explicit_url`, obtén la URL de 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 y almacenamiento en caché de claves](https://platform.claude.com/docs/es/manage-claude/wif-reference#key-rotation-and-caching). ## Modos de fuente 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 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; configúralo cuando la URL de descubrimiento difiera de `issuer_url`) | Anthropic obtiene `/.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 la comparación de cadenas con la reclamación `iss` del JWT y nunca se marca. | 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 envoltorio). Anthropic no realiza ninguna solicitud saliente. El `issuer_url` se usa solo para la comparación de `iss`. | Entornos aislados, clústeres de Kubernetes autogestionados con URL de emisor internas del 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 `ca_cert_pem` opcional para emisores que sirven TLS desde una CA privada. ### Rotación y almacenamiento en caché de claves 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 presentan 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 gestionados normalmente siguen esta disciplina por su cuenta. 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 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 la verificación de firma.