Menggunakan WIF dengan Kubernetes

Klaster Kubernetes yang dikelola sendiri (kubeadm, k3s, OpenShift, dan distribusi on-premises) menandatangani OIDC JSON Web Token (JWT) untuk setiap pod melalui projected service account token. API server klaster bertindak sebagai OIDC issuer, dan klaim sub pada setiap token mengikuti format system:serviceaccount:<namespace>:<service-account>. Anda dapat menemukan URL issuer klaster Anda dengan membaca dokumen discovery-nya:

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

Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Klaster Kubernetes dengan flag --service-account-issuer yang dikonfigurasi pada API server. Sebagian besar distribusi mengatur ini secara default; klaster kubeadm biasanya menggunakan https://kubernetes.default.svc.cluster.local. Tim platform Anda dapat mengonfirmasi nilainya jika Anda tidak memiliki akses langsung ke konfigurasi API server.
• Salah satu dari berikut ini agar Anthropic dapat memvalidasi tanda tangan token:
  • Endpoint JWKS issuer dapat dijangkau dari internet publik melalui HTTPS pada port 443, atau
  • Anda dapat mengambil JWKS dari dalam klaster dan mendaftarkannya dalam mode inline (dibahas di Konfigurasi Anthropic).
• Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.

Konfigurasi Kubernetes

Proyeksikan service account token ke dalam pod Anda dengan audience dan masa berlaku yang diharapkan oleh federation rule Anda. Proyeksi serviceAccountToken menulis JWT baru ke mount path dan merotasinya sebelum expirationSeconds berlalu.

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

Token yang diterbitkan untuk pod ini membawa sub: "system:serviceaccount:inference:inference-worker" dan aud: ["https://api.anthropic.com"].

Konfigurasi Anthropic

Ikuti panduan penyiapan untuk mendaftarkan federation issuer, membuat service account Anthropic, dan membuat federation rule di Claude Console. Gunakan nilai-nilai khusus Kubernetes berikut.

Federation issuer: Banyak klaster yang dikelola sendiri menggunakan URL issuer seperti https://kubernetes.default.svc.cluster.local yang tidak dapat dijangkau dari internet publik. Jika hal itu berlaku untuk klaster Anda, pilih sumber JWKS inline dan tempelkan kunci klaster. Ambil kunci tersebut dari dalam klaster:

kubectl get --raw /openid/v1/jwks

Kemudian konfigurasikan issuer dengan isi array keys yang dikembalikan (bukan pembungkus {"keys": [...]} di sekitarnya):

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

Dalam mode inline, issuer_url hanya dibandingkan dengan klaim iss pada JWT; Anthropic tidak pernah mencoba menjangkaunya. Jika issuer Anda dapat dijangkau secara publik, gunakan "jwks_source": "discovery" sebagai gantinya dan hilangkan jwks_keys.

Federation rule: Cocokkan klaim sub service account dan audience yang Anda tetapkan pada projected token.

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

Buat sespesifik mungkin sesuai yang diizinkan workload. Longgarkan subject_prefix menjadi system:serviceaccount:inference:* (tanda * di akhir menjadikannya pencocokan prefiks) hanya jika setiap service account di namespace tersebut harus dipetakan ke service account Anthropic yang sama. Tambahkan ID fdrl_... dari rule tersebut ke variabel lingkungan ANTHROPIC_FEDERATION_RULE_ID pada pod Anda.

Memperoleh dan menggunakan token

Spesifikasi pod di Konfigurasi Kubernetes menetapkan ANTHROPIC_IDENTITY_TOKEN_FILE ke mount path yang diproyeksikan, bersama dengan ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, dan ANTHROPIC_WORKSPACE_ID. Dengan semua itu tersedia, SDK membaca token dari disk pada setiap pertukaran dan menyegarkan access token Anthropic secara otomatis.

import anthropic

# Membaca ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, dan ANTHROPIC_WORKSPACE_ID
# dari environment pod.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Verifikasi penyiapan

Pertukaran yang berhasil mengembalikan access_token yang dimulai dengan sk-ant-oat01- dan nilai expires_in dalam detik. Pada 400 invalid_grant, lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum dari sisi Kubernetes adalah ketidakcocokan kunci JWKS (untuk mode inline, ambil ulang dengan kubectl get --raw /openid/v1/jwks dan perbarui issuer).

Batasi cakupan rule Anda

Kunci blok match pada rule ke cakupan tersempit yang sesuai dengan kasus penggunaan Anda:

• Tetapkan namespace dan nama service-account secara spesifik: Gunakan nilai lengkap system:serviceaccount:<namespace>:<name> tanpa * di akhir.
• Selalu tetapkan audience: Wajibkan audience pada rule dan tetapkan nilai yang sama pada proyeksi serviceAccountToken pod sehingga token dengan audience default ditolak.
• Gunakan rule terpisah per namespace: Buat rule dan service account Anthropic yang berbeda untuk setiap namespace daripada memperluas satu rule.
• Batasi cakupan issuer inline-JWKS ke satu klaster: Ketika beberapa klaster berbagi URL issuer yang sama, daftarkan JWKS setiap klaster sebagai federation issuer tersendiri dan ikat rule hanya ke issuer tersebut.

Langkah selanjutnya

• Workload Identity Federation: konsep, alur token-exchange, dan opsi konfigurasi SDK.
• Referensi WIF: variabel lingkungan, mode sumber JWKS, dan mode pencocokan rule.