Usar WIF com SPIFFE

SPIFFE é o padrão da CNCF para emissão de identidade a workloads. SPIRE é sua implementação de referência open-source, e vários produtos comerciais também emitem identidades compatíveis com SPIFFE. A Anthropic federa com qualquer implementação SPIFFE que emita JWT-SVIDs compatíveis com OIDC. A federação funciona por meio de um documento de descoberta OIDC em uma URL HTTPS pública (modo discovery; consulte as restrições de URL) ou registrando o JWKS diretamente (modo inline). A especificação JWT-SVID define sub como o SPIFFE ID do workload, e a SPIFFE Workload API exige que o chamador forneça aud no momento da obtenção, portanto essas claims são as mesmas em todas as implementações. A Anthropic adicionalmente exige iss e iat, nenhuma das quais a especificação JWT-SVID torna obrigatória, então configure sua implementação para preencher ambas (no SPIRE, iss é a configuração de servidor jwt_issuer e iat é definido automaticamente). Com isso em vigor, as seções Configurar a Anthropic, Obter e usar o token e Definir o escopo da sua regra deste guia se aplicam a qualquer implementação SPIFFE. Para uma lista atualizada, consulte Commercial software that implements SPIFFE no site do projeto SPIFFE.

O SPIFFE atribui a cada workload uma URI de identidade estável no formato spiffe://<trust-domain>/<path>, e o SPIRE emite essa identidade como um JWT-SVID sob demanda por meio da Workload API. Um JWT-SVID é um JWT assinado comum cuja claim sub é o SPIFFE ID do workload e cuja claim aud é fornecida pelo workload no momento da obtenção.

A ponte entre um trust domain do SPIRE e o OIDC padrão é o SPIRE OIDC Discovery Provider, um utilitário independente que publica /.well-known/openid-configuration e um endpoint JWKS para as chaves de assinatura JWT do trust domain. Com o discovery provider em execução, um JWT-SVID é validado como qualquer outro token OIDC: registre a URL de descoberta como um emissor de federação, escreva uma regra de federação que corresponda ao SPIFFE ID do workload e faça o workload apresentar seu JWT-SVID ao endpoint de token-exchange da Anthropic.

Os exemplos desta página usam SPIRE e se aplicam a qualquer lugar onde o SPIRE Agent seja executado: pods do Kubernetes, máquinas virtuais e hosts bare-metal.

Pré-requisitos

• Familiaridade com os conceitos de WIF: service accounts, emissores de federação e regras de federação.
• Uma implantação SPIFFE com identidades de workload emitidas (os exemplos nesta página usam SPIRE Server e Agent) e entradas de registro para os workloads que precisam chamar a API do Claude.
• Um endpoint de descoberta OIDC para o trust domain (no SPIRE, o OIDC Discovery Provider) em execução com um endpoint HTTPS acessível publicamente, ou o JWKS exportado para registro inline.
• Seu emissor SPIFFE configurado para definir a claim iss nos JWT-SVIDs com o valor que você registrará como issuer_url do emissor de federação. Para o modo discovery, essa é a URL pública do endpoint de descoberta (no SPIRE, a configuração de servidor jwt_issuer).
• JWT-SVIDs disponíveis para seus workloads. O WIF aceita apenas JWT-SVIDs; X.509-SVIDs não são usados.
• Permissão para criar service accounts, emissores de federação e regras de federação no Claude Console para sua organização Anthropic.

O valor de audience a ser solicitado ao obter um JWT-SVID é sempre https://api.anthropic.com. Use esse valor no jwt_audience do spiffe-helper, na chamada FetchJWTSVID da Workload API e no matcher audience da regra de federação.

Configurar o SPIRE

As instruções nesta seção são específicas do SPIRE. Se você usa um emissor SPIFFE diferente, configure seu endpoint de descoberta OIDC e a obtenção de JWT-SVID de acordo com a documentação dele, depois continue em Configurar a Anthropic.

Se você já executa o SPIRE com o OIDC Discovery Provider, federar com a Anthropic requer três coisas do lado do SPIRE: um jwt_issuer que corresponda à URL de descoberta, uma entrada de registro para o workload que chamará a API do Claude e uma forma de esse workload obter um JWT-SVID com o audience da Anthropic. As subseções a seguir percorrem cada uma delas. Os trechos de configuração mostram apenas as configurações relevantes para a federação com a Anthropic; não são configurações completas de implantação do SPIRE.

Verificar o emissor JWT

A Anthropic valida um JWT-SVID comparando sua claim iss com um emissor de federação registrado e buscando o JWKS do documento de descoberta desse emissor. Duas configurações do SPIRE devem concordar na mesma URL: o jwt_issuer do SPIRE Server (que se torna a claim iss em cada JWT-SVID emitido) e a lista domains do OIDC Discovery Provider (que determina o host a partir do qual o documento de descoberta e o JWKS são servidos). Essa URL compartilhada é o que você registra na Anthropic.

O trust domain e a URL do emissor são independentes. O trust domain (spiffe://prod.example.com) define o escopo da claim sub; a URL do emissor (https://oidc-discovery.prod.example.com) é de onde a Anthropic busca as chaves de assinatura. Eles não precisam compartilhar um hostname.

Confirme que jwt_issuer está definido na configuração do SPIRE Server e aponta para a URL pública do discovery provider. O exemplo a seguir também mostra um tempo de vida padrão de JWT-SVID; o padrão interno do SPIRE é 5 minutos, o que é curto o suficiente para exigir rotação contínua (consulte Executar o spiffe-helper). O endpoint de token-exchange da Anthropic rejeita qualquer token de identidade cujo tempo de vida exceda o máximo configurado do emissor de federação (1 hora por padrão; consulte Regras de validação). Essa verificação se aplica a todas as implementações SPIFFE, não apenas ao SPIRE, então mantenha default_jwt_svid_ttl (ou qualquer override por entrada) igual ou abaixo desse máximo.

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

Na configuração do OIDC Discovery Provider, o mesmo hostname deve aparecer em domains, e o provider deve conseguir alcançar o socket da API do SPIRE Server. O provider serve o documento de descoberta e o JWKS via HTTPS; termine o TLS com o suporte ACME integrado dele ou coloque-o atrás de um load balancer que faça isso.

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

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

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

Registrar o workload

Cada workload que chama a API do Claude precisa de uma entrada de registro do SPIRE que mapeie seus seletores de runtime para um SPIFFE ID. Se o workload já estiver registrado, anote seu SPIFFE ID; você o usará no subject_prefix da regra de federação. Caso contrário, registre-o. Para um pod do Kubernetes, os seletores são tipicamente o namespace e a service account do 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

Workloads fora do Kubernetes usam seletores de nível de host, como unix:uid:1000 (unix:path também está disponível, mas requer discover_workload_path = true na configuração do unix workload attestor do agente). Clusters que executam o spire-controller-manager podem declarar entradas com o recurso personalizado ClusterSPIFFEID em vez de chamar spire-server entry create diretamente.

Executar o spiffe-helper

O spiffe-helper é um utilitário sidecar que se conecta ao socket do SPIRE Agent, obtém um JWT-SVID para um determinado audience, grava-o em um arquivo e o obtém novamente antes da expiração. O helper é executado em modo daemon por padrão; o exemplo abaixo define daemon_mode = true explicitamente.

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"
}]

No Kubernetes, execute o spiffe-helper como um container sidecar que compartilha um volume emptyDir em memória (medium: Memory) com o container da sua aplicação, para que o SVID bearer nunca seja gravado no disco do nó. Monte o socket do SPIRE Agent do host no sidecar, monte o volume compartilhado em /var/run/secrets/anthropic.com em ambos os containers e defina ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token no container da aplicação. Em VMs e bare metal, execute o spiffe-helper como um serviço de sistema ao lado do workload e aponte ambos para um diretório compartilhado.

Configurar a Anthropic

Siga o passo a passo de configuração para registrar um emissor de federação, criar uma service account da Anthropic e criar uma regra de federação no Claude Console. Use estes valores específicos do SPIFFE.

Emissor de federação: Registre a URL pública do OIDC Discovery Provider no modo discovery. A Anthropic busca /.well-known/openid-configuration dessa URL e segue o jwks_uri retornado para recuperar as chaves de assinatura do trust domain.

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

Se o discovery provider não for acessível pela internet pública, busque o JWKS você mesmo (curl https://oidc-discovery.prod.example.com/keys) e registre o emissor com "jwks": {"type": "inline", "keys": [...]} usando o conteúdo do array keys retornado. No modo inline, o issuer_url é apenas comparado com a claim iss do JWT-SVID; a Anthropic nunca tenta acessá-lo.

Para automatizar atualizações de JWKS sem expor um endpoint de descoberta público, configure um plugin BundlePublisher do SPIRE Server (aws_s3, gcp_cloudstorage ou k8s_configmap) com format = "jwks" para enviar as chaves de assinatura JWT para armazenamento externo a cada rotação, e então sincronize isso com as chaves inline do emissor.

Regra de federação: Faça a correspondência com o sub do JWT-SVID (o SPIFFE ID) e o aud que você configurou o spiffe-helper para solicitar. SPIFFE IDs são strings de URI e subject_prefix os compara como texto opaco, então tanto um valor exato quanto uma correspondência de prefixo com * no final funcionam com eles. Para padrões mais complexos, use uma 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
}

Seja tão específico quanto o workload permitir. Afrouxe subject_prefix para spiffe://prod.example.com/ns/inference/* apenas se todos os workloads registrados sob esse caminho devem ser mapeados para a mesma service account da Anthropic. Adicione o ID fdrl_... da regra à variável de ambiente ANTHROPIC_FEDERATION_RULE_ID do workload.

Obter e usar o token

Os SDKs da Anthropic podem ler o JWT-SVID do arquivo que o spiffe-helper mantém ou chamar a SPIFFE Workload API diretamente por meio de um callable provedor de token. O caminho via arquivo é a integração mais simples e funciona em todas as linguagens de SDK; o caminho via callable elimina o sidecar, mas requer um cliente da SPIFFE Workload API na linguagem da sua aplicação.

Verificar a configuração

Antes de integrar o SDK, obtenha um JWT-SVID diretamente do SPIRE Agent e confirme que as claims correspondem ao que sua regra de federação espera. Se você usa uma implementação SPIFFE diferente, obtenha um JWT-SVID com a CLI ou o cliente da Workload API dela e decodifique o payload da mesma forma.

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'

A flag -output json retorna a resposta do SVID e a resposta do bundle como um array JSON de dois elementos, então jq -r '.[0].svids[0].svid' extrai o token puro. Em versões mais antigas do SPIRE sem -output, o comando imprime um bloco rotulado; nesse caso, passe a saída padrão por awk '/^[[:space:]]*eyJ/{print $1; exit}' para extrair a linha do token. Verifique se iss é a URL do OIDC Discovery Provider que você registrou, sub é o SPIFFE ID do workload e aud contém https://api.anthropic.com. Em seguida, execute o exemplo cURL de Obter e usar o token; uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01-. Em caso de 400 invalid_grant, consulte Solucionar problemas de uma troca com falha; a causa mais comum do lado do SPIRE é uma incompatibilidade entre o jwt_issuer do SPIRE Server e a URL registrada como emissor de federação.

Definir o escopo da sua regra

As convenções de caminho de SPIFFE ID são definidas pelo operador, então o matcher subject_prefix da regra de federação deve refletir o esquema de caminho que suas entradas de registro usam. Esquemas comuns incluem spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (o padrão emitido pelo recurso ClusterSPIFFEID no spire-controller-manager) e spiffe://<trust-domain>/host/<hostname>/<service> para workloads em VM e bare-metal.

Restrinja o bloco match da regra ao escopo mais estreito que se adeque ao seu caso de uso:

• Fixar em um único workload: Defina subject_prefix como o SPIFFE ID completo, sem * no final.
• Sempre definir um audience: Exija audience na regra e configure o spiffe-helper (ou a chamada da Workload API) com o mesmo valor, para que SVIDs emitidos para outras relying parties sejam rejeitados.
• Definir escopo por segmento de caminho: Use spiffe://prod.example.com/ns/inference/* para conceder acesso a todos os workloads registrados sob um namespace, e crie uma regra e uma service account da Anthropic separadas por namespace em vez de ampliar uma única regra.
• Um emissor por trust domain: Cada trust domain do SPIRE tem suas próprias chaves de assinatura e OIDC Discovery Provider. Registre cada um como um emissor de federação separado e vincule as regras ao emissor que possui os SPIFFE IDs aos quais elas correspondem.

Próximos passos

• Workload Identity Federation: conceitos, o fluxo de token-exchange e opções de configuração do SDK.
• Referência de WIF: variáveis de ambiente, modos de origem de JWKS e modos de correspondência de regras.
• Usar WIF com Kubernetes: para clusters que usam tokens nativos de service account projetados em vez do SPIRE.