Usar WIF con SPIFFE

SPIFFE es el estándar de la CNCF para emitir identidad a cargas de trabajo. SPIRE es su implementación de referencia de código abierto, y varios productos comerciales también emiten identidades compatibles con SPIFFE. Anthropic se federa con cualquier implementación de SPIFFE que emita JWT-SVIDs compatibles con OIDC. La federación funciona ya sea a través de un documento de descubrimiento OIDC en una URL HTTPS pública (modo discovery; consulta las restricciones de URL) o registrando el JWKS directamente (modo inline). La especificación de JWT-SVID define sub como el SPIFFE ID de la carga de trabajo, y la Workload API de SPIFFE requiere que el llamador proporcione aud al momento de la obtención, por lo que esos claims son los mismos en todas las implementaciones. Anthropic requiere adicionalmente iss e iat, ninguno de los cuales es obligatorio según la especificación de JWT-SVID, así que configura tu implementación para que rellene ambos (en SPIRE, iss es la configuración de servidor jwt_issuer e iat se establece automáticamente). Con eso en su lugar, las secciones Configurar Anthropic, Obtener y usar el token y Delimitar tu regla de esta guía aplican a cualquier implementación de SPIFFE. Para ver una lista actualizada, consulta Commercial software that implements SPIFFE en el sitio del proyecto SPIFFE.

SPIFFE asigna a cada carga de trabajo una URI de identidad estable con la forma spiffe://<trust-domain>/<path>, y SPIRE emite esa identidad como un JWT-SVID bajo demanda a través de la Workload API. Un JWT-SVID es un JWT firmado ordinario cuyo claim sub es el SPIFFE ID de la carga de trabajo y cuyo claim aud es proporcionado por la carga de trabajo al momento de la obtención.

El puente entre un dominio de confianza de SPIRE y OIDC estándar es el SPIRE OIDC Discovery Provider, un componente auxiliar independiente que publica /.well-known/openid-configuration y un endpoint JWKS para las claves de firma de JWT del dominio de confianza. Con el discovery provider en ejecución, un JWT-SVID se valida como cualquier otro token OIDC: registra la URL de descubrimiento como un emisor de federación, escribe una regla de federación que coincida con el SPIFFE ID de la carga de trabajo y haz que la carga de trabajo presente su JWT-SVID al endpoint de intercambio de tokens de Anthropic.

Los ejemplos de esta página usan SPIRE y aplican en cualquier lugar donde se ejecute SPIRE Agent: pods de Kubernetes, máquinas virtuales y hosts bare-metal.

Requisitos previos

• Familiaridad con los conceptos de WIF: cuentas de servicio, emisores de federación y reglas de federación.
• Un despliegue de SPIFFE con identidades de carga de trabajo emitidas (los ejemplos de esta página usan SPIRE Server y Agent), y entradas de registro para las cargas de trabajo que necesitan llamar a la API de Claude.
• Un endpoint de descubrimiento OIDC para el dominio de confianza (en SPIRE, el OIDC Discovery Provider) ejecutándose con un endpoint HTTPS accesible públicamente, o el JWKS exportado para el registro en modo inline.
• Tu emisor SPIFFE configurado para establecer el claim iss en los JWT-SVIDs con el valor que registrarás como issuer_url del emisor de federación. Para el modo discovery, esta es la URL pública del endpoint de descubrimiento (en SPIRE, la configuración de servidor jwt_issuer).
• JWT-SVIDs disponibles para tus cargas de trabajo. WIF acepta únicamente JWT-SVIDs; los X.509-SVIDs no se utilizan.
• Permiso para crear cuentas de servicio, emisores de federación y reglas de federación en Claude Console para tu organización de Anthropic.

El valor de audiencia que debes solicitar al obtener un JWT-SVID es siempre https://api.anthropic.com. Usa este valor en jwt_audience de spiffe-helper, en la llamada FetchJWTSVID de la Workload API y en el matcher audience de la regla de federación.

Configurar SPIRE

Las instrucciones de esta sección son específicas de SPIRE. Si usas un emisor SPIFFE diferente, configura su endpoint de descubrimiento OIDC y la obtención de JWT-SVID según su propia documentación, y luego continúa en Configurar Anthropic.

Si ya ejecutas SPIRE con el OIDC Discovery Provider, federarte con Anthropic requiere tres cosas del lado de SPIRE: un jwt_issuer que coincida con la URL de descubrimiento, una entrada de registro para la carga de trabajo que llamará a la API de Claude, y una forma de que esa carga de trabajo obtenga un JWT-SVID con la audiencia de Anthropic. Las siguientes subsecciones recorren cada una. Los fragmentos de configuración muestran solo los ajustes relevantes para la federación con Anthropic; no son configuraciones completas de despliegue de SPIRE.

Verificar el emisor de JWT

Anthropic valida un JWT-SVID comparando su claim iss con un emisor de federación registrado y obteniendo el JWKS del documento de descubrimiento de ese emisor. Dos configuraciones de SPIRE deben coincidir en la misma URL: jwt_issuer de SPIRE Server (que se convierte en el claim iss de cada JWT-SVID emitido) y la lista domains del OIDC Discovery Provider (que determina el host desde el cual se sirven el documento de descubrimiento y el JWKS). Esa URL compartida es la que registras con Anthropic.

El dominio de confianza y la URL del emisor son independientes. El dominio de confianza (spiffe://prod.example.com) delimita el claim sub; la URL del emisor (https://oidc-discovery.prod.example.com) es de donde Anthropic obtiene las claves de firma. No necesitan compartir un nombre de host.

Confirma que jwt_issuer esté configurado en SPIRE Server y apunte a la URL pública del discovery provider. El siguiente ejemplo también muestra un tiempo de vida predeterminado para JWT-SVID; el valor predeterminado integrado de SPIRE es de 5 minutos, lo cual es lo suficientemente corto como para requerir rotación continua (consulta Ejecutar spiffe-helper). El endpoint de intercambio de tokens de Anthropic rechaza cualquier token de identidad cuyo tiempo de vida exceda el máximo configurado del emisor de federación (1 hora de forma predeterminada; consulta Reglas de validación). Esta verificación aplica a todas las implementaciones de SPIFFE, no solo a SPIRE, así que mantén default_jwt_svid_ttl (o cualquier override por entrada) en ese máximo o por debajo de él.

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

En la configuración del OIDC Discovery Provider, el mismo nombre de host debe aparecer bajo domains, y el provider debe poder alcanzar el socket de la API de SPIRE Server. El provider sirve el documento de descubrimiento y el JWKS a través de HTTPS; termina TLS con su soporte ACME integrado o colócalo detrás de un balanceador de carga que lo haga.

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}

Registrar la carga de trabajo

Cada carga de trabajo que llama a la API de Claude necesita una entrada de registro de SPIRE que asocie sus selectores de tiempo de ejecución a un SPIFFE ID. Si la carga de trabajo ya está registrada, anota su SPIFFE ID; lo usarás en el subject_prefix de la regla de federación. Si no, regístrala. Para un pod de Kubernetes, los selectores son típicamente el namespace y la cuenta de servicio de Kubernetes:

spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Las cargas de trabajo fuera de Kubernetes usan selectores a nivel de host como unix:uid:1000 (unix:path también está disponible pero requiere discover_workload_path = true en la configuración del atestador de cargas de trabajo unix del agente). Los clústeres que ejecutan spire-controller-manager pueden declarar entradas con el recurso personalizado ClusterSPIFFEID en lugar de llamar directamente a spire-server entry create.

Ejecutar spiffe-helper

spiffe-helper es una utilidad sidecar que se conecta al socket de SPIRE Agent, obtiene un JWT-SVID para una audiencia dada, lo escribe en un archivo y lo vuelve a obtener antes de que expire. El helper se ejecuta en modo daemon de forma predeterminada; el ejemplo a continuación establece daemon_mode = true explícitamente.

agent_address = "/run/spire/sockets/agent.sock"
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

En Kubernetes, ejecuta spiffe-helper como un contenedor sidecar que comparta un volumen emptyDir respaldado por memoria (medium: Memory) con tu contenedor de aplicación, de modo que el SVID portador nunca llegue al disco del nodo. Monta el socket de SPIRE Agent desde el host en el sidecar, monta el volumen compartido en /var/run/secrets/anthropic.com en ambos contenedores y establece ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token en el contenedor de la aplicación. En VMs y bare metal, ejecuta spiffe-helper como un servicio del sistema junto a la carga de trabajo y apunta ambos a un directorio compartido.

Configurar Anthropic

Sigue el tutorial de configuración para registrar un emisor de federación, crear una cuenta de servicio de Anthropic y crear una regla de federación en Claude Console. Usa estos valores específicos de SPIFFE.

Emisor de federación: Registra la URL pública del OIDC Discovery Provider en modo discovery. Anthropic obtiene /.well-known/openid-configuration desde esta URL y sigue el jwks_uri devuelto para recuperar las claves de firma del dominio de confianza.

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

Si el discovery provider no es accesible desde la internet pública, obtén el JWKS tú mismo (curl https://oidc-discovery.prod.example.com/keys) y registra el emisor con "jwks": {"type": "inline", "keys": [...]} usando el contenido del array keys devuelto. En modo inline, el issuer_url solo se compara con el claim iss del JWT-SVID; Anthropic nunca intenta acceder a él.

Para automatizar las actualizaciones de JWKS sin exponer un endpoint de descubrimiento público, configura un plugin BundlePublisher de SPIRE Server (aws_s3, gcp_cloudstorage o k8s_configmap) con format = "jwks" para enviar las claves de firma de JWT a almacenamiento externo en cada rotación, y luego sincroniza eso con las claves inline del emisor.

Regla de federación: Haz coincidir el sub del JWT-SVID (el SPIFFE ID) y el aud que configuraste en spiffe-helper para solicitar. Los SPIFFE IDs son cadenas URI y subject_prefix los compara como texto opaco, por lo que tanto un valor exacto como una coincidencia de prefijo con * al final funcionan con ellos. Para patrones más complejos, usa una condition CEL.

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Sé tan específico como la carga de trabajo lo permita. Relaja subject_prefix a spiffe://prod.example.com/ns/inference/* solo si todas las cargas de trabajo registradas bajo esa ruta deben asociarse a la misma cuenta de servicio de Anthropic. Agrega el ID fdrl_... de la regla a la variable de entorno ANTHROPIC_FEDERATION_RULE_ID de la carga de trabajo.

Obtener y usar el token

Los SDKs de Anthropic pueden leer el JWT-SVID desde el archivo que spiffe-helper mantiene o llamar directamente a la Workload API de SPIFFE a través de un callable proveedor de tokens. La ruta de archivo es la integración más simple y funciona en todos los lenguajes de SDK; la ruta del callable elimina el sidecar pero requiere un cliente de la Workload API de SPIFFE en el lenguaje de tu aplicación.

Verificar la configuración

Antes de integrar el SDK, obtén un JWT-SVID directamente desde SPIRE Agent y confirma que los claims coincidan con lo que tu regla de federación espera. Si usas una implementación de SPIFFE diferente, obtén un JWT-SVID con su CLI o cliente de la Workload API y decodifica el payload de la misma manera.

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

La opción -output json devuelve la respuesta del SVID y la respuesta del bundle como un array JSON de dos elementos, por lo que jq -r '.[0].svids[0].svid' extrae el token sin adornos. En versiones antiguas de SPIRE sin -output, el comando imprime un bloque etiquetado en su lugar; en ese caso, pasa la salida predeterminada por awk '/^[[:space:]]*eyJ/{print $1; exit}' para extraer la línea del token. Verifica que iss sea la URL del OIDC Discovery Provider que registraste, que sub sea el SPIFFE ID de la carga de trabajo y que aud contenga https://api.anthropic.com. Luego ejecuta el ejemplo de cURL de Obtener y usar el token; un intercambio exitoso devuelve un access_token que comienza con sk-ant-oat01-. Ante un 400 invalid_grant, consulta Solucionar problemas de un intercambio fallido; la causa más común del lado de SPIRE es una discrepancia entre el jwt_issuer de SPIRE Server y la URL registrada como emisor de federación.

Delimitar tu regla

Las convenciones de ruta de los SPIFFE IDs las define el operador, por lo que el matcher subject_prefix de la regla de federación debe reflejar el esquema de rutas que usan tus entradas de registro. Los esquemas comunes incluyen spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (el predeterminado emitido por el recurso ClusterSPIFFEID en spire-controller-manager) y spiffe://<trust-domain>/host/<hostname>/<service> para cargas de trabajo en VM y bare-metal.

Restringe el bloque match de la regla al alcance más estrecho que se ajuste a tu caso de uso:

• Fijar a una sola carga de trabajo: Establece subject_prefix al SPIFFE ID completo sin * al final.
• Siempre establece una audiencia: Requiere audience en la regla y configura spiffe-helper (o la llamada a la Workload API) con el mismo valor para que los SVIDs emitidos para otras relying parties sean rechazados.
• Delimitar por segmento de ruta: Usa spiffe://prod.example.com/ns/inference/* para conceder acceso a todas las cargas de trabajo registradas bajo un namespace, y crea una regla y una cuenta de servicio de Anthropic separadas por namespace en lugar de ampliar una sola regla.
• Un emisor por dominio de confianza: Cada dominio de confianza de SPIRE tiene sus propias claves de firma y su propio OIDC Discovery Provider. Registra cada uno como un emisor de federación separado y vincula las reglas al emisor que posee los SPIFFE IDs con los que coinciden.

Próximos pasos

• Workload Identity Federation: conceptos, el flujo de intercambio de tokens y opciones de configuración del SDK.
• Referencia de WIF: variables de entorno, modos de origen de JWKS y modos de coincidencia de reglas.
• Usar WIF con Kubernetes: para clústeres que usan tokens de cuenta de servicio proyectados nativos en lugar de SPIRE.