--- 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 ver guías de configuración paso a paso, 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 va 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. 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 del intercambio de tokens `POST /v1/oauth/token` devuelve una respuesta de token estándar de OAuth 2.0 ([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 en el constructor. | Variable | Obligatoria | Descripción | Ejemplo | | ------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `ANTHROPIC_FEDERATION_RULE_ID` | Sí | ID etiquetado de la regla de federación que se va a 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 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. 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 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. 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 va a cargar. Tiene prioridad sobre las variables de entorno de federación de esta tabla. | `staging-profile` | La ruta de federación directa mediante variables de entorno se activa solo cuando `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` y una de `ANTHROPIC_IDENTITY_TOKEN_FILE` o `ANTHROPIC_IDENTITY_TOKEN` están todas definidas. `ANTHROPIC_WORKSPACE_ID` se lee junto con ellas, pero no condiciona la activación. Una variable definida como cadena vacía aún puede ocupar su lugar en la cadena de precedencia de credenciales. Elimina las variables de credenciales que no uses en lugar de dejarlas vacías. ### Precedencia de credenciales El SDK resuelve las credenciales en este orden. Gana la primera fuente que proporcione una credencial. | 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` | Oculta la federación por completo. Elimina estas variables al migrar desde claves de API. | | 3 | `ANTHROPIC_PROFILE` | Carga `/configs/.json`. Un perfil con nombre que no existe es un error, no un paso a la siguiente fuente. | | 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 | Se resuelve desde `/active_config`, y si no, se usa un perfil llamado `default`. | En la CLI `ant`, la configuración de [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication) tiene prioridad después de las variables de entorno de federación y antes del perfil activo. La configuración consiste en el proyecto, el ID del espacio de trabajo y la ubicación. La estableces con las marcas `--google-cloud-*` o con las variables `ANTHROPIC_GOOGLE_CLOUD_*`. La CLI usa esta configuración cuando cualquiera de estos valores está establecido. Con esta configuración, la CLI obtiene su credencial de Google Application Default Credentials. Cuando se carga un perfil, las variables de entorno completan los campos que el perfil omite, pero nunca anulan los campos que el perfil define explícitamente. Por ejemplo, `ANTHROPIC_WORKSPACE_ID` completa `workspace_id` solo cuando el perfil activo no lo define. ## Archivo de configuración de perfil Un perfil es un archivo de configuración con nombre que leen tanto el SDK como la CLI `ant`. Los perfiles te permiten incluir los parámetros de federación en tu imagen de contenedor o cambiar entre entornos sin modificar el código. ### Directorio de configuración El SDK localiza el directorio de configuración en este orden: 1. `$ANTHROPIC_CONFIG_DIR` 2. `~/.config/anthropic` en Linux y macOS 3. `%APPDATA%\Anthropic` en Windows ### Perfil activo El nombre del perfil activo se resuelve en este orden: 1. `$ANTHROPIC_PROFILE` 2. El contenido de `/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. ### Estructura de archivos | Ruta | Contenido | Sensibilidad | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `/configs/.json` | `version`, el bloque `authentication`, `organization_id`, `workspace_id` y `base_url`. | No secreto. Es seguro confirmarlo en el repositorio o incluirlo en una imagen. | | `/credentials/.json` | `version`, el `access_token` en caché, `expires_at` y (para el inicio de sesión interactivo) `refresh_token`. | Secreto. El SDK lo escribe con el modo `0600`. | Tanto el archivo de configuración como el archivo de credenciales incluyen un campo de cadena `version` de nivel superior en formato `major.minor` (actualmente `"1.0"`). El SDK escribe este campo automáticamente para que las versiones futuras puedan detectar y migrar formatos anteriores; omítelo al escribir una configuración a mano y el SDK tratará el archivo como la versión actual. ### Ejemplo de perfil de federación ```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 defines en una regla de federación determina 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 espacio de trabajo de la regla: [Messages](https://platform.claude.com/docs/es/api/messages) (incluidos 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) (incluidos 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 administrar 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 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](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 respalde 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. Actualmente no hay alcances más detallados (por recurso, o de lectura frente a escritura). ### Límites de permisos El `oauth_scope` de una regla de federación es un límite máximo: el token emitido nunca puede superarlo. El `organization_role` de la cuenta de servicio de destino (`developer` o `admin`) determina qué alcances se pueden otorgar, por lo que una regla que otorga `org:admin` debe apuntar a una cuenta de servicio con `organization_role=admin`. Los permisos efectivos son la intersección del alcance de la regla y el rol de la cuenta de servicio. | `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 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 excepciones para llamadores 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 al verificar un JWT entrante en el momento del intercambio. Para ver los detalles completos de los parámetros y los esquemas de respuesta, consulta la [referencia de la API de cuentas de servicio](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-]+$`, con una longitud de 1 a 255 caracteres. | | `workspace_id` | Obligatorio al crear, a menos que `applies_to_all_workspaces` sea true. 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. | | `applies_to_all_workspaces` | Booleano. Defínelo como `true` para habilitar la regla en todos los espacios de trabajo de la organización en lugar de nombrar uno; al crear se requiere este campo o `workspace_id`. | | `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 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 errores de validación de URL devuelven `400 invalid_request_error` con el nombre del campo como prefijo en el mensaje de error (por ejemplo, `issuer_url: url must use https scheme`). 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 se define `jwks.discovery_base`, el `issuer_url` se compara con la 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 `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`. | | Claims 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 claim `jti` solo se puede intercambiar una vez por emisor: repetir un intercambio con el mismo `jti` se rechaza como reproducción. El campo `check_jti` del emisor (habilitado de forma predeterminada) controla esta comprobación; las aserciones sin una claim `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 completados se evalúan con semántica AND: el JWT debe satisfacer cada comparador completado. Se debe definir al menos uno de `subject_prefix`, `claims` o `condition`; se rechaza un bloque `match` que contenga solo `audience` (o ningún comparador). Esto protege contra reglas que aceptarían todos los tokens de un emisor. | Comparador | Tipo | Semántica | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `subject_prefix` | string | Coincidencia exacta con la claim `sub` del JWT. Un `*` 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 | La claim `aud` del JWT debe contener exactamente esta cadena. Cuando `aud` es un arreglo, cualquier elemento que coincida exactamente satisface la comprobación. | | `claims` | map\ | Cada clave es el nombre de una claim de nivel superior y cada valor es el valor de cadena exacto requerido. Para claims 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 de CEL La expresión `condition` tiene acceso a una sola variable: | Variable | Tipo | Contenido | | -------- | ---- | -------------------------------------------------------------------------------------------------------------- | | `claims` | map | El conjunto completo de claims decodificadas del JWT. 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 del intercambio de tokens `POST /v1/oauth/token` devuelve errores con la [forma de error estándar de la API](https://platform.claude.com/docs/es/api/errors). 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 | Solución | | ------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | `federation_rule_id` tiene un formato incorrecto 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_error` | `workspace_id` está presente, pero no es un ID `wrkspc_...` con formato correcto ni el literal `default`. | Corrige el valor de `workspace_id`; el mensaje de respuesta indica el formato esperado. | | 401 | `authentication_error` | La 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"`. | | 401 | `authentication_error` | La obtención del JWKS falló, el JWKS está desactualizado 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 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é](https://platform.claude.com/docs/es/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | La 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. | | 401 | `authentication_error` | 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. | | 401 | `authentication_error` | El `federation_rule_id` no existe, está archivado o el JWT no está autorizado para él (se consolida para evitar la enumeración). | Confirma el ID de la regla en la Claude Console y que la regla no se haya archivado. | | 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 el motivo `workspace_id_required`. | 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 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é comprobación haya fallado; un error distinguible permitiría a un llamador sondear la configuración de la regla. El motivo de la denegación se registra en la entrada del intento en el [historial de autenticación](https://platform.claude.com/settings/workload-identity-federation?tab=history) de la Claude Console, por ejemplo `match_subject_prefix` cuando la claim `sub` no cumple el `subject_prefix` de la regla, o `workspace_id_required` cuando la regla abarca varios espacios de trabajo y la solicitud no nombra ninguno. Las solicitudes rechazadas antes de que se corrobore la organización de la regla (la familia `400 invalid_request_error` anterior) no dejan ninguna entrada en el historial; sus mensajes de respuesta indican el problema directamente. Un `401` sin una entrada coincidente en el historial suele significar que no se reconoció el propio `federation_rule_id`. ### Fallos comunes del lado del SDK | Síntoma | Causa | Solució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 usar la federación | `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` está definida y tiene prioridad. | Elimina la variable de la clave o del 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 se realiza correctamente, pero una solicitud a la Claude API devuelve 403 | El alcance del token emitido no otorga acceso a ese endpoint. | Compara el `oauth_scope` de la regla con [Alcances de OAuth](https://platform.claude.com/docs/es/manage-claude/wif-reference#oauth-scopes). | | La autenticación falla con una credencial vacía | Una variable de entorno de credenciales está exportada, pero definida como cadena vacía. Los valores vacíos pueden seguir ganando su lugar en la precedencia. | Elimina la variable con `unset VAR` en lugar de `VAR=""`. | ## Solucionar un intercambio fallido Una respuesta `401` `authentication_error` es intencionalmente opaca y su mensaje siempre es `Authentication failed`; el motivo de la denegación se registra en el historial de autenticación, no en la respuesta. Comienza con la [página del 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 claims del JWT que se inspeccionaron y qué paso de validación falló, lo que normalmente te ahorra las siguientes comprobaciones. Un fallo opaco común es una aserción reproducida: una aserción que incluye una claim `jti` solo se puede [intercambiar una vez](https://platform.claude.com/docs/es/manage-claude/wif-reference#jwt-verification), por lo que una carga de trabajo que vuelve a enviar el mismo JWT (un bucle de reintentos, o una actualización que vuelve a leer un token no rotado) se rechaza en el segundo intercambio. La página del historial de autenticación muestra estos intentos con el motivo `jti_reused`; la solución es emitir una aserción nueva para cada intercambio. Si aún necesitas depurar a partir del propio JWT, realiza estas comprobaciones en orden: Decodifica la aserción que enviaste para poder comparar cada claim con la configuración de tu emisor y tu regla: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` La claim `iss` decodificada debe ser igual byte por byte al `issuer_url` registrado, incluidos el esquema, el puerto y cualquier barra final. Una discrepancia en un solo carácter hace que falle la verificación. La claim `aud` decodificada debe contener el valor `audience` de la regla como coincidencia exacta. Cuando `aud` es un arreglo, un elemento debe coincidir exactamente. Compara `sub` con el `subject_prefix` de la regla (distingue mayúsculas de minúsculas; un `*` final es una coincidencia de prefijo, cualquier otra cosa es exacta). Compara cada clave del mapa `claims` de la regla con la claim de nivel superior del mismo nombre. `exp` debe estar en el futuro y `nbf`/`iat` deben estar en el pasado, dentro de la ventana de desfase de 30 segundos. Si el reloj del host de la carga de trabajo se ha desviado, se rechaza un token que de otro modo sería válido. Para el modo `discovery`, obtén `/.well-known/openid-configuration` mediante HTTPS público en el puerto 443 y confirma que `jwks_uri` se resuelva. Para `explicit_url`, obtén la URL del JWKS directamente. Para `inline`, confirma que la clave de firma del emisor no haya rotado desde que registraste las claves. Si el emisor rotó su clave de firma y comenzó a firmar con ella de inmediato, los intercambios pueden fallar durante hasta un minuto mientras se actualiza la caché de JWKS de Anthropic. Consulta [Rotación de claves y almacenamiento en caché](https://platform.claude.com/docs/es/manage-claude/wif-reference#key-rotation-and-caching). ## Modos de origen del JWKS Cuando registras un emisor de federación, el campo `jwks` controla cómo obtiene Anthropic las claves públicas que se usan para verificar las firmas de los JWT de ese emisor. Es una unión discriminada con clave en `type`: | `jwks.type` | Forma de `jwks` | Comportamiento | Úsalo 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 `/.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 internet pública. La mayoría de los proveedores administrados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) lo admiten. | | `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 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, clústeres de Kubernetes autoadministrados con URL de emisor internas del clúster, o cuando quieres un 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 y comienza a firmar tokens con ella de inmediato, los intercambios que presenten esos tokens pueden fallar con un error de firma durante hasta 1 minuto mientras se actualiza la caché. Para evitar este intervalo, publica una nueva clave de firma en el JWKS al menos 15 minutos antes de que tu proveedor de identidad comience a firmar tokens con ella, y mantén la clave reemplazada en el JWKS hasta que los tokens que firmó hayan expirado. Los proveedores de identidad administrados suelen seguir esta práctica por su cuenta. Si operas tu propio emisor (un clúster de Kubernetes autoadministrado, un proveedor de descubrimiento OIDC de SPIRE o un servidor de autorización personalizado de Okta con una cadencia de rotación configurada), confirma que tu política de rotación publique las nuevas claves antes de su primer uso. En el modo `inline` no hay actualización automática de claves. Cuando tu proveedor de identidad rote 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.