Workload Identity Federation

"Workload Identity Federation" (federación de identidad de cargas de trabajo), o WIF, permite que tus cargas de trabajo se autentiquen ante la API de Claude 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 compatible 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 en tu organización. No hay secretos estáticos que generar, almacenar en CI, rotar ni filtrar.

Workload Identity Federation fortalece tu postura de seguridad al reemplazar las claves de API estáticas por 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 upstream 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 defensa en profundidad.



Conceptos

Configuras tres recursos en la Claude Console antes de que cualquier carga de trabajo pueda federarse. Juntos 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 cuenta de servicio (svac_...) es una identidad no humana con nombre dentro de tu organización de Anthropic. Es el principal en nombre del cual actúa un token federado. Las cuentas de servicio existen a nivel de organización y se activan en un workspace cuando las agregas como miembros de ese workspace. En el momento del intercambio, Anthropic verifica que el workspace de la regla de federación coincida con una de las membresías de workspace de la cuenta de servicio; el token generado sigue entonces los límites de velocidad y la atribución de uso de ese workspace, igual que una clave de API. A diferencia de un usuario humano, una cuenta de servicio no tiene correo electrónico, contraseña ni inicio de sesión en la Console. Cada cuenta de servicio es implícitamente miembro del workspace predeterminado de tu organización; agrega membresías explícitas para cualquier otro workspace en el que deba actuar.

La distinción clave respecto a una clave de API: una clave de API es una credencial, mientras que una cuenta de servicio tiene credenciales que se generan para ella bajo demanda. Puedes auditar qué cargas de trabajo actuaron como qué cuenta de servicio.



Emisores de federación

Un 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 identidad de carga 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 de 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 de JWKS, o inline para cargar el conjunto de claves en el caso 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 consulta; 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 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, genera un token para la cuenta de servicio Z con el scope S".

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

• Coincidencia: Las condiciones que un JWT entrante debe satisfacer. Puedes hacer coincidir por un subject_prefix (por ejemplo, system:serviceaccount:prod:worker, o con un * al final para una coincidencia de prefijo), un audience exacto, un mapa de valores de claims exactos, 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 matchers configurados deben pasar 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 generado. El valor predeterminado es workspace:developer, que otorga el mismo acceso que una clave de API emitida para ese workspace. Algunos productos fijan el scope cuando creas una regla desde su flujo; por ejemplo, el modal de creación de túnel de MCP tunnels crea reglas con scope workspace:manage_tunnels. Consulta Scopes 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 satisfaga 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 de cuenta de servicio proyectado 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 mediante POST 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 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 admin, owner o primary owner en tu organización de Anthropic, un proveedor de identidad compatible con OIDC con un endpoint de 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 solo flujo guiado, y luego verifica la conexión de extremo a extremo.

Para administrar estos recursos de forma programática, consulta Administrar WIF con la Admin API para ver el tutorial 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 detalles completos de parámetros y esquemas de respuesta.



Autenticar desde tu carga de trabajo

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



Construir 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: despliega 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

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



Precedencia de credenciales

Cada SDK resuelve 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 ver 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.



Migrar desde claves de API

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

1. Configura la federación en paralelo. Completa el tutorial 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 logs 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 de 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. Revoca 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 generado es el menor valor entre (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 a 60 segundos. El segundo límite evita que un token de Anthropic sobreviva a la identidad upstream 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 calendario de dos niveles inspirado en botocore:

• Renovación recomendada a la expiración menos 120 segundos. El SDK intenta un nuevo intercambio. Si el endpoint de token no está accesible, el SDK continúa sirviendo el token en caché, que sigue siendo 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 la expiración 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).



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.



Consulta también

• Administrar 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