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 penerbit (issuer) OIDC, dan klaim sub setiap token mengikuti bentuk 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 mengaturnya 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 path mount dan merotasinya sebelum expirationSeconds berakhir.

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

Di Claude Console, buka Settings → Workload identity, klik Connect workload, dan pilih tile Kubernetes. Wizard akan memandu Anda melalui pendaftaran issuer, pembuatan service account, dan pembuatan federation rule.

Wizard ini membuat sumber daya tersebut untuk Anda. Gunakan nilai-nilai berikut baik saat Anda memasukkannya di wizard maupun saat mengirimkannya ke Admin API:

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 sekelilingnya):

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks": {
    "type": "inline",
    "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": {"type": "discovery"} sebagai gantinya.

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
}

Buatlah sespesifik mungkin sesuai yang dimungkinkan oleh 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 path mount yang diproyeksikan, bersama dengan ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, dan ANTHROPIC_WORKSPACE_ID. Dengan semua itu terpasang, SDK membaca token dari disk pada setiap pertukaran dan menyegarkan token akses 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 lingkungan 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"))



Verifikasi pengaturan

Pertukaran yang berhasil mengembalikan access_token yang diawali 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: 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 default-audience ditolak.
• Gunakan rule terpisah per namespace: Buat rule dan service account Anthropic yang berbeda untuk setiap namespace alih-alih memperluas satu rule.
• Batasi issuer inline-JWKS ke satu klaster: Ketika beberapa klaster berbagi URL issuer, daftarkan JWKS setiap klaster sebagai federation issuer tersendiri dan ikat rule hanya ke issuer tersebut.



Langkah selanjutnya

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