Workload Identity Federation

"Workload Identity Federation" (federación de identidades de cargas de trabajo), o WIF, permite que tus cargas de trabajo se autentiquen en la Claude API con tokens OpenID Connect (OIDC) de corta duración en lugar de claves de API sk-ant-... de larga duración. Los tokens provienen de un "identity provider" (proveedor de identidad), o IdP, que ya operas: AWS IAM, Google Cloud o cualquier emisor OIDC que cumpla con los estándares, como GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID u Okta.

Tu carga de trabajo presenta un JWT firmado por tu proveedor de identidad. Anthropic lo valida contra las reglas de confianza que configuras en la Claude Console y devuelve un token de acceso de Anthropic de corta duración vinculado a una cuenta de servicio de tu organización. No hay secretos estáticos que emitir, almacenar en CI, rotar o filtrar.

Workload Identity Federation fortalece tu postura de seguridad al reemplazar las claves de API estáticas con tokens que expiran en minutos en lugar de nunca. No es una solución de seguridad completa por sí sola: la autenticación federada es tan sólida como el proveedor de identidad ascendente que firma el JWT. Combina Workload Identity Federation con los controles que tu IdP ya admite (vinculación de identidad de cargas de trabajo, acceso condicional, registro de auditoría) para lograr una defensa en profundidad.

Conceptos

Configuras tres recursos en la Claude Console antes de que cualquier carga de trabajo pueda federarse. En conjunto expresan "los tokens firmados por el emisor X, con claims que se ven como Y, pueden actuar como la cuenta de servicio Z".

Cuentas de servicio

Una "service account" (cuenta de servicio) (svac_...) es una identidad no humana con nombre dentro de tu organización de Anthropic. Es el principal como el cual actúa una clave de cuenta de servicio o un token federado. Las cuentas de servicio existen a nivel de organización y se activan en un espacio de trabajo cuando las agregas como miembros de ese espacio de trabajo. En el momento del intercambio, Anthropic verifica que el espacio de trabajo de la regla de federación coincida con una de las membresías de espacio de trabajo de la cuenta de servicio; el token emitido sigue entonces los límites de velocidad y la atribución de uso de ese espacio de trabajo, igual que una clave de API. A diferencia de un usuario humano, una cuenta de servicio no tiene correo electrónico, ni contraseña, ni inicio de sesión en la Console. Toda cuenta de servicio es implícitamente miembro del espacio de trabajo predeterminado de tu organización; agrega membresías explícitas para cualquier otro espacio de trabajo en el que deba actuar. Para permitir que una clave de cuenta de servicio de todos los espacios de trabajo actúe en un espacio de trabajo, agrega la cuenta de servicio a ese espacio de trabajo.

La distinción clave frente a una clave de API de espacio de trabajo: una clave de API de espacio de trabajo es una credencial, mientras que una cuenta de servicio tiene credenciales. Puedes auditar más fácilmente qué cargas de trabajo actuaron como qué cuenta de servicio.

Emisores de federación

Un "federation issuer" (emisor de federación) (fdis_...) registra un proveedor de identidad OIDC en tu organización. Registrar un emisor le indica a Anthropic "los JWT firmados por este proveedor pueden afirmar la identidad de cargas de trabajo para mi organización".

Un emisor tiene dos elementos de configuración:

• URL del emisor: El valor exacto del claim iss que aparece en los JWT del proveedor, por ejemplo https://token.actions.githubusercontent.com o https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• Fuente JWKS: Cómo obtiene Anthropic las claves públicas para verificar las firmas de los JWT. Usa discovery (el valor predeterminado) para cualquier proveedor que sirva /.well-known/openid-configuration en su URL de emisor. Usa explicit_url para apuntar directamente a un endpoint JWKS, o inline para cargar el conjunto de claves de emisores que no son accesibles desde la internet pública (por ejemplo, un clúster privado de Kubernetes).

Las URL del emisor y de JWKS deben ser https, en el puerto 443, y usar un nombre de host DNS público que resuelva a direcciones IP públicas; no se aceptan literales de IP. Estas restricciones se aplican solo a las URL que Anthropic obtiene; en los modos explicit_url e inline, la issuer_url se compara como cadena y puede hacer referencia a un nombre de host interno.

Normalmente registras un emisor por entorno: tu clúster EKS de producción, tu clúster de staging y GitHub Actions son tres emisores separados.

Reglas de federación

Una "federation rule" (regla de federación) (fdrl_...) es el puente entre un emisor y una cuenta de servicio: "cuando un JWT del emisor X tiene claims que se ven como Y, emite un token para la cuenta de servicio Z con el alcance S".

Una regla define condiciones de coincidencia, un destino, y el alcance de autorización y la duración del token que se aplican cuando la regla coincide:

• Coincidencia: Las condiciones que debe cumplir un JWT entrante. Puedes hacer coincidir por un subject_prefix (por ejemplo, system:serviceaccount:prod:worker, o con un * al final para una coincidencia por prefijo), una audience exacta, un mapa de valores exactos de claims, una expresión condition en CEL para lógica compleja, o cualquier combinación. Al menos uno de subject_prefix, claims o condition debe estar definido, y todos los comparadores configurados deben cumplirse para que el JWT sea aceptado.
• Destino: La cuenta de servicio a la que se asigna el JWT coincidente.
• Autorización: El scope de OAuth otorgado en el token emitido. El valor predeterminado es workspace:developer, que otorga el mismo acceso que una clave de API de espacio de trabajo. Algunos productos bloquean el alcance cuando creas una regla desde su flujo; por ejemplo, el modal de creación de túneles de túneles MCP crea reglas con alcance workspace:manage_tunnels. Consulta Alcances de OAuth. La regla también establece token_lifetime_seconds (de 60 a 86400, predeterminado 3600).

Un solo emisor puede tener muchas reglas: una por equipo, namespace o nivel de permisos. Las reglas se evalúan por ID: el cliente especifica qué regla usar en la solicitud de intercambio, y Anthropic verifica que el JWT cumpla los criterios de coincidencia de esa regla. No hay búsqueda implícita de reglas.

Cómo funciona

1. Tu IdP emite un JWT a la carga de trabajo. En la mayoría de las plataformas esto es ambiental: un token proyectado de cuenta de servicio de Kubernetes, el servidor de metadatos de Google Cloud, Azure IMDS o el endpoint OIDC de GitHub Actions. El claim iss del JWT identifica al proveedor, y su sub y otros claims identifican la carga de trabajo específica.
2. El SDK intercambia el JWT por un token de acceso de Anthropic. El SDK envía el JWT a POST /v1/oauth/token usando el grant jwt-bearer de RFC 7523. Anthropic verifica el JWT contra el JWKS del emisor y las condiciones de coincidencia de la regla de federación, y luego devuelve un token sk-ant-oat01-... de corta duración que actúa en nombre de la cuenta de servicio de destino de la regla.
3. El SDK envía el token en cada solicitud y lo renueva antes de que expire. El código de tu aplicación construye el cliente sin api_key y llama a la API como de costumbre. El SDK vuelve a ejecutar el intercambio antes de que el token expire.

Configurar la federación

Necesitas el rol de administrador, propietario o propietario principal en tu organización de Anthropic, un proveedor de identidad compatible con OIDC con un endpoint JWKS accesible (o un documento JWKS que puedas pegar, para clústeres aislados), y una carga de trabajo que pueda obtener un token de identidad de ese proveedor.

El asistente Connect workload crea los tres recursos (el emisor, la cuenta de servicio y la regla de federación) en un único flujo guiado, y luego verifica la conexión de extremo a extremo.

1. 1

   Abre Connect workload

   En la Claude Console, ve a Settings → Workload identity y selecciona Connect workload.

2. 2

   Elige tu proveedor

   Selecciona el mosaico de tu proveedor de identidad: GitHub Actions, AWS, Google Cloud, Microsoft Entra ID o Kubernetes. Cada mosaico rellena previamente el patrón de URL del emisor y los campos de coincidencia que admiten los JWT de ese proveedor. Para cualquier otro proveedor que cumpla con los estándares (como SPIFFE u Okta), selecciona Custom OIDC.

3. 3

   Completa los campos guiados

   El asistente te guía por los campos específicos del proveedor: la configuración del emisor, las condiciones de coincidencia para los JWT entrantes, y los nombres de la cuenta de servicio y la regla de federación que crea. El asistente rellena previamente oauth_scope=workspace:developer y token_lifetime_seconds=600 (el valor predeterminado de la API cuando se omite token_lifetime_seconds es 3600); ajústalos si tu carga de trabajo necesita un alcance o una duración diferentes.

4. 4

   Verifica el emisor

   Opcionalmente, selecciona Verify issuer para hacer una prueba en seco de la configuración del emisor antes de que se cree nada. La verificación confirma que Anthropic puede obtener y analizar el JWKS desde las URL que ingresaste, lo que detecta temprano errores de accesibilidad y configuración.

5. 5

   Prueba la conexión

   El asistente crea el emisor, la cuenta de servicio y la regla de federación, y luego espera un intercambio de token exitoso durante 15 minutos. Activa un intercambio desde tu carga de trabajo dentro de esa ventana (consulta Autentícate desde tu carga de trabajo) para confirmar que la configuración funciona. Si la ventana transcurre, los recursos persisten; puedes volver a ejecutar la prueba desde la página de detalles de la regla de federación. Anota el ID de la regla (fdrl_...) y el ID de la cuenta de servicio (svac_...) que crea el asistente: tu carga de trabajo pasa ambos, junto con el ID de tu organización (y el ID de tu espacio de trabajo cuando la regla cubre más de un espacio de trabajo), en cada solicitud de intercambio de token.

Para administrar estos recursos de forma programática, consulta Administra WIF con la Admin API para el recorrido con curl, o consulta la referencia de la API de cuentas de servicio, la referencia de la API de emisores de federación y la referencia de la API de reglas de federación para obtener los detalles completos de los parámetros y los esquemas de respuesta.

Autentícate desde tu carga de trabajo

Con la federación configurada, tu carga de trabajo intercambia en tiempo de ejecución su JWT emitido por el IdP por un token de Anthropic. Los SDK manejan el intercambio y el ciclo de renovación por ti. La pestaña cURL muestra el intercambio HTTP subyacente para scripts de shell, depuración o lenguajes sin soporte de SDK.

Construye el cliente del SDK

Puedes construir el cliente con credenciales explícitas o sin argumentos. Sin argumentos, el SDK resuelve las credenciales a partir de variables de entorno o del perfil activo, como se describe en Precedencia de credenciales. La forma sin argumentos es el patrón recomendado para cargas de trabajo de producción: distribuye la misma imagen de contenedor en todas partes e inyecta ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID y ANTHROPIC_IDENTITY_TOKEN_FILE por entorno.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

La respuesta del intercambio de token sigue RFC 6749 §5.1. Consulta Respuesta del intercambio de token para la referencia de campos.

Precedencia de credenciales

Todos los SDK resuelven las credenciales en el mismo orden de cinco niveles: argumentos del constructor, luego ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, luego un ANTHROPIC_PROFILE explícito, luego las variables de entorno de federación, y luego el perfil activo implícito. La primera fuente que produce una credencial gana.

Para la tabla completa de precedencia, la semántica de cada nivel y el esquema del archivo de perfil, consulta Precedencia de credenciales en la referencia de WIF.

Migra desde claves de API

Para cambiar una carga de trabajo existente de una clave de API estática a la federación sin tiempo de inactividad:

1. Configura la federación en paralelo. Completa el recorrido de configuración y confirma que la regla de federación coincide con el token de tu carga de trabajo. Deja la ANTHROPIC_API_KEY existente en su lugar por ahora.
2. Haz una prueba rápida de qué credencial gana. Ejecuta ant auth status desde dentro de la carga de trabajo (o inspecciona los registros de depuración del SDK). Como ANTHROPIC_API_KEY está por encima de los niveles de federación en la cadena de precedencia, la clave de API todavía gana en esta etapa.
3. Elimina ANTHROPIC_API_KEY en todos los lugares donde se inyecta. Quítala de los secretos de CI, del entorno del contenedor y de los perfiles de shell (consulta la advertencia anterior). Vuelve a ejecutar ant auth status y confirma que ahora se selecciona la fuente de federación.
4. Elimina la clave de API. Una vez que la carga de trabajo esté funcionando con el token federado, elimina la clave en la Claude Console en Settings → API keys.

Duración y renovación del token

La duración del token de Anthropic emitido es el menor de (a) el token_lifetime_seconds de la regla (predeterminado 3600 segundos) y (b) el doble de la duración restante del JWT del IdP que presentaste. El resultado nunca es menor de 60 segundos. El segundo límite evita que un token de Anthropic sobreviva a la identidad ascendente de la que se derivó por más de un pequeño margen.

Los SDK almacenan el token en caché y lo renuevan según un esquema de dos niveles modelado a partir de botocore:

• Renovación recomendada a la expiración menos 120 segundos. El SDK intenta un nuevo intercambio. Si el endpoint de tokens no es accesible, el SDK sigue sirviendo el token en caché, que todavía es válido durante aproximadamente 90 segundos más.
• Renovación obligatoria a la expiración menos 30 segundos. Un intercambio fallido en este punto genera un error. El token en caché está demasiado cerca de expirar para ser seguro.

Como el SDK vuelve a leer ANTHROPIC_IDENTITY_TOKEN_FILE en cada intercambio, recoge de forma transparente los tokens proyectados rotados (los tokens de cuenta de servicio de Kubernetes, por ejemplo, rotan mucho antes de su exp).

De forma predeterminada, los tokens de identidad que llevan un claim jti son de un solo uso: cada intercambio debe presentar un JWT que no se haya intercambiado antes, y volver a presentar uno falla con el motivo jti_reused en la página de historial de autenticación. Si tu carga de trabajo obtiene sus propios tokens de tu proveedor de identidad, emite un JWT nuevo para cada intercambio en lugar de reutilizar uno en caché (los bucles de reintento son el culpable habitual). Lo mismo se aplica a un token leído desde ANTHROPIC_IDENTITY_TOKEN_FILE: el SDK vuelve a leer el archivo en cada intercambio, por lo que el archivo debe contener un token nuevo antes de cada renovación. Una renovación que vuelve a leer un token no rotado, o un proceso reiniciado que vuelve a presentar un token que ya intercambió, se rechaza de la misma manera. Rotar el token con suficiente margen dentro de la duración del token emitido mantiene el archivo por delante del esquema de renovación; si tu fuente de tokens no puede rotar con esa frecuencia, puedes deshabilitar check_jti para ese emisor como último recurso (esto elimina la protección contra repetición para todas las reglas del emisor). Consulta Verificación de JWT para más detalles.

Proveedores de identidad

Cada guía cubre de dónde proviene el JWT en esa plataforma, cómo se ven sus claims, y la configuración de emisor y regla que debes registrar.

Ver también

• Administra WIF con la Admin API: crea emisores, cuentas de servicio y reglas desde infraestructura como código
• Referencia de WIF: variables de entorno, esquema del archivo de perfil, reglas de validación y códigos de error
• Autenticación: todas las opciones de autenticación en los SDK de Anthropic
• Referencia de la Admin API: esquemas de solicitud y respuesta generados para cada endpoint de la Admin API