Claude Platform Docs
AdministraçãoProvedores de identidade

Usar WIF com Kubernetes

Autentique-se na Claude API a partir de clusters Kubernetes autogerenciados usando tokens de conta de serviço projetados.

Clusters Kubernetes autogerenciados (kubeadm, k3s, OpenShift e distribuições on-premises) assinam JSON Web Tokens (JWTs) OIDC para cada pod por meio de projected service account tokens (tokens de conta de serviço projetados). O servidor de API do cluster atua como o emissor OIDC, e a claim sub de cada token segue o formato system:serviceaccount:<namespace>:<service-account>. Você pode encontrar a URL do emissor do seu cluster lendo seu documento de descoberta:

cURL
kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

Pré-requisitos

  • Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
  • Um cluster Kubernetes com a flag --service-account-issuer configurada no servidor de API. A maioria das distribuições define isso por padrão; clusters kubeadm normalmente usam https://kubernetes.default.svc.cluster.local. Sua equipe de plataforma pode confirmar o valor se você não tiver acesso direto à configuração do servidor de API.
  • Uma das seguintes opções para que a Anthropic possa validar as assinaturas dos tokens:
    • O endpoint JWKS do emissor é acessível a partir da internet pública via HTTPS na porta 443, ou
    • Você pode obter o JWKS de dentro do cluster e registrá-lo no modo inline (abordado em Configurar a Anthropic).
  • Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para a sua organização Anthropic.

Configurar o Kubernetes

Projete um token de conta de serviço no seu pod com a audiência e o tempo de vida que a sua regra de federação espera. A projeção serviceAccountToken grava um JWT novo no caminho de montagem e o rotaciona antes que expirationSeconds expire.

Pod
apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

O token emitido para este pod carrega sub: "system:serviceaccount:inference:inference-worker" e aud: ["https://api.anthropic.com"].

Configurar a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Kubernetes. O assistente orienta você no registro do emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: Muitos clusters autogerenciados usam uma URL de emissor como https://kubernetes.default.svc.cluster.local, que não é acessível a partir da internet pública. Se isso se aplica ao seu cluster, escolha a origem de JWKS inline e cole as chaves do cluster. Obtenha-as de dentro do cluster:

cURL
kubectl get --raw /openid/v1/jwks

Em seguida, configure o emissor com o conteúdo do array keys retornado (não o wrapper {"keys": [...]} ao redor):

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks": {
    "type": "inline",
    "keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
  }
}

No modo inline, a issuer_url é apenas comparada com a claim iss do JWT; a Anthropic nunca tenta acessá-la. Se o seu emissor for acessível publicamente, use "jwks": {"type": "discovery"} em vez disso.

Regra de federação: Faça a correspondência com a claim sub da conta de serviço e com a audiência que você definiu no token projetado.

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-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 a carga de trabalho permitir. Afrouxe subject_prefix para system:serviceaccount:inference:* (o * final o torna uma correspondência por prefixo) somente se todas as contas de serviço no namespace devem ser mapeadas para a mesma conta de serviço Anthropic. Adicione o ID fdrl_... da regra à variável de ambiente ANTHROPIC_FEDERATION_RULE_ID do seu pod.

Obter e usar o token

A especificação do pod em Configurar o Kubernetes define ANTHROPIC_IDENTITY_TOKEN_FILE como o caminho de montagem projetado, junto com ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e ANTHROPIC_WORKSPACE_ID. Com isso configurado, o SDK lê o token do disco em cada troca e renova o token de acesso da Anthropic automaticamente.

import anthropic

# Lê ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e ANTHROPIC_WORKSPACE_ID
# do ambiente do pod.
client = anthropic.Anthropic()

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"))

Verificar a configuração

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação e consulte Solucionar problemas de uma troca com falha; a causa mais comum do lado do Kubernetes é uma incompatibilidade de chave JWKS (para o modo inline, obtenha novamente com kubectl get --raw /openid/v1/jwks e atualize o emissor).

Delimitar o escopo da sua regra

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

  • Fixe o namespace e o nome da conta de serviço: Use o valor completo system:serviceaccount:<namespace>:<name> sem * final.
  • Sempre defina uma audiência: Exija audience na regra e defina o mesmo valor na projeção serviceAccountToken do pod para que tokens de audiência padrão sejam rejeitados.
  • Use uma regra separada por namespace: Crie uma regra e uma conta de serviço Anthropic distintas para cada namespace em vez de ampliar uma única regra.
  • Delimite emissores com JWKS inline a um único cluster: Quando vários clusters compartilham uma URL de emissor, registre o JWKS de cada cluster como seu próprio emissor de federação e vincule regras somente a esse emissor.

Próximos passos

Was this page helpful?