Claude Platform Docs
AdminPenyedia identitas

Menggunakan WIF dengan Kubernetes

Autentikasi ke Claude API dari klaster Kubernetes yang dikelola sendiri menggunakan projected service account token.

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 (penerbit 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:

cURL
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 Mengonfigurasi Anthropic).
  • Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.

Mengonfigurasi 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.

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

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

Mengonfigurasi Anthropic

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

Wizard membuat sumber daya ini untuk Anda. Gunakan nilai-nilai berikut, baik Anda memasukkannya di wizard maupun 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:

cURL
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 atur 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 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_... milik rule ke variabel lingkungan ANTHROPIC_FEDERATION_RULE_ID pada pod Anda.

Memperoleh dan menggunakan token

Spesifikasi pod di Mengonfigurasi Kubernetes mengatur ANTHROPIC_IDENTITY_TOKEN_FILE ke projected mount path, 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 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Memverifikasi penyiapan

Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Jika pertukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed), periksa halaman riwayat autentikasi untuk mengetahui alasan penolakan dan lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum di sisi Kubernetes adalah ketidakcocokan kunci JWKS (untuk mode inline, ambil ulang dengan kubectl get --raw /openid/v1/jwks dan perbarui issuer).

Membatasi 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 atur audience: Wajibkan audience pada rule dan atur 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 daripada 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

Was this page helpful?