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 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 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 en tu organización. No hay secretos estáticos que generar, 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 solo tan fuerte 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 una 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 parecen a 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 como el que actúa un token federado. Las cuentas de servicio existen a nivel de organización y se vuelven activas 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, ni 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 generadas 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 dice a Anthropic "los JWT firmados por este proveedor pueden afirmar la identidad de cargas de trabajo para mi organización."

Un emisor tiene dos piezas 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 Anthropic obtiene 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 para 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 se 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 una 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 parecen a Y, genera 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 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 exactos de claims, una expresión condition de CEL para lógica compleja, o cualquier combinación. Al menos uno de subject_prefix, claims o condition debe estar configurado, y todos los comparadores 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 bloquean el alcance cuando creas una regla desde su flujo; por ejemplo, el modal de creación de túnel de los 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 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 sus claims sub y otros 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, 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 actualiza 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 JWKS accesible (o un documento JWKS que puedas pegar, para clústeres aislados de internet), 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 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 detalles completos de los parámetros y los esquemas de respuesta.



Autenticarse 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 actualizació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: 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 tokens sigue RFC 6749 §5.1. Consulta Respuesta del intercambio de tokens para la referencia de los 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 la tabla de precedencia completa, la semántica por 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 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). Debido a que 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 actualización del token

La duración del token de Anthropic generado es el menor entre (a) el token_lifetime_seconds de la regla (predeterminado 3,600 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 ascendente de la que se derivó por más de un pequeño margen.

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

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

Debido a que el SDK vuelve a leer ANTHROPIC_IDENTITY_TOKEN_FILE en cada intercambio, detecta 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 del emisor y la 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 generados de solicitud y respuesta para cada endpoint de la Admin API