Menggunakan WIF dengan SPIFFE

SPIFFE adalah standar CNCF untuk menerbitkan identitas kepada workload. SPIRE adalah implementasi referensi open-source-nya, dan beberapa produk komersial juga menerbitkan identitas yang sesuai dengan SPIFFE. Anthropic melakukan federasi dengan implementasi SPIFFE apa pun yang mengeluarkan JWT-SVID yang kompatibel dengan OIDC. Untuk daftar implementasi terkini, lihat Commercial software that implements SPIFFE di situs proyek SPIFFE.

Federasi bekerja baik melalui dokumen discovery OIDC di URL HTTPS publik (mode discovery, tunduk pada batasan URL) atau dengan mendaftarkan JWKS secara langsung (mode inline).

Spesifikasi JWT-SVID mendefinisikan sub sebagai SPIFFE ID workload, dan SPIFFE Workload API mengharuskan pemanggil untuk menyediakan aud pada saat pengambilan, sehingga klaim tersebut sama di semua implementasi. Anthropic juga mewajibkan iss dan iat, yang keduanya tidak diwajibkan oleh spesifikasi JWT-SVID, jadi konfigurasikan implementasi Anda untuk mengisi keduanya (di SPIRE, iss adalah pengaturan server jwt_issuer dan iat diatur secara otomatis). Dengan keduanya terpasang, bagian Konfigurasi Anthropic, Dapatkan dan gunakan token, dan Batasi cakupan aturan Anda dari panduan ini berlaku untuk implementasi SPIFFE apa pun.

SPIFFE memberikan setiap workload sebuah URI identitas yang stabil dalam bentuk spiffe://<trust-domain>/<path>, dan SPIRE menerbitkan identitas tersebut sebagai JWT-SVID sesuai permintaan melalui Workload API. JWT-SVID adalah JWT bertanda tangan biasa yang klaim sub-nya adalah SPIFFE ID workload dan klaim aud-nya disediakan oleh workload pada saat pengambilan.

Jembatan dari trust domain SPIRE ke OIDC standar adalah SPIRE OIDC Discovery Provider, sebuah helper mandiri yang mempublikasikan /.well-known/openid-configuration dan endpoint JWKS untuk kunci penandatanganan JWT trust domain tersebut. Dengan discovery provider berjalan, JWT-SVID divalidasi seperti token OIDC lainnya: daftarkan URL discovery sebagai federation issuer, tulis federation rule yang cocok dengan SPIFFE ID workload, dan buat workload menyajikan JWT-SVID-nya ke endpoint token-exchange Anthropic.

Contoh-contoh di halaman ini menggunakan SPIRE dan berlaku di mana pun SPIRE Agent berjalan: pod Kubernetes, virtual machine, dan host bare-metal.



Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Deployment SPIFFE dengan identitas workload yang sudah diterbitkan (contoh di halaman ini menggunakan SPIRE Server dan Agent), dan registration entry untuk workload yang perlu memanggil Claude API.
• Endpoint discovery OIDC untuk trust domain (di SPIRE, OIDC Discovery Provider) yang berjalan dengan endpoint HTTPS yang dapat dijangkau secara publik, atau JWKS yang diekspor untuk pendaftaran inline.
• Penerbit SPIFFE Anda dikonfigurasi untuk mengatur klaim iss pada JWT-SVID ke nilai yang akan Anda daftarkan sebagai issuer_url federation issuer. Untuk mode discovery, ini adalah URL publik endpoint discovery (di SPIRE, pengaturan server jwt_issuer).
• JWT-SVID tersedia untuk workload Anda. WIF hanya menerima JWT-SVID, bukan X.509-SVID.
• Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.

Nilai audience yang diminta saat mengambil JWT-SVID selalu https://api.anthropic.com. Gunakan nilai ini di jwt_audience spiffe-helper, panggilan Workload API FetchJWTSVID, dan matcher audience pada federation rule.



Konfigurasi SPIRE

Instruksi di bagian ini khusus untuk SPIRE. Jika Anda menggunakan penerbit SPIFFE yang berbeda, konfigurasikan endpoint discovery OIDC dan pengambilan JWT-SVID-nya sesuai dengan dokumentasinya sendiri, lalu lanjutkan di Konfigurasi Anthropic.

Jika Anda sudah menjalankan SPIRE dengan OIDC Discovery Provider, federasi dengan Anthropic memerlukan tiga hal di sisi SPIRE: jwt_issuer yang cocok dengan URL discovery, registration entry untuk workload yang akan memanggil Claude API, dan cara bagi workload tersebut untuk mengambil JWT-SVID dengan audience Anthropic. Subbagian berikut membahas masing-masing. Cuplikan konfigurasi hanya menampilkan pengaturan yang relevan dengan federasi Anthropic, bukan konfigurasi deployment SPIRE yang lengkap.



Verifikasi JWT issuer

Anthropic memvalidasi JWT-SVID dengan mencocokkan klaim iss-nya terhadap federation issuer yang terdaftar dan mengambil JWKS dari dokumen discovery issuer tersebut. Dua pengaturan SPIRE harus menyepakati URL yang sama: jwt_issuer SPIRE Server (yang menjadi klaim iss di setiap JWT-SVID yang diterbitkan) dan daftar domains OIDC Discovery Provider (yang menentukan host tempat dokumen discovery dan JWKS disajikan). URL bersama itulah yang Anda daftarkan ke Anthropic.

Trust domain dan URL issuer bersifat independen. Trust domain (spiffe://prod.example.com) menentukan cakupan klaim sub. URL issuer (https://oidc-discovery.prod.example.com) adalah tempat Anthropic mengambil kunci penandatanganan. Keduanya tidak perlu berbagi hostname.

Pastikan jwt_issuer diatur dalam konfigurasi SPIRE Server dan mengarah ke URL publik discovery provider. Contoh berikut juga menunjukkan masa berlaku JWT-SVID default. Default bawaan SPIRE adalah 5 menit, yang cukup singkat sehingga rotasi berkelanjutan diperlukan (lihat Jalankan spiffe-helper). Endpoint token-exchange Anthropic menolak token identitas apa pun yang masa berlakunya melebihi maksimum yang dikonfigurasi pada federation issuer, yaitu 1 jam secara default (lihat Aturan validasi). Pemeriksaan ini berlaku untuk setiap implementasi SPIFFE, bukan hanya SPIRE, jadi pertahankan default_jwt_svid_ttl (atau override per-entry apa pun) pada atau di bawah maksimum tersebut.

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

Dalam konfigurasi OIDC Discovery Provider, hostname yang sama harus muncul di bawah domains, dan provider harus dapat menjangkau socket API SPIRE Server. Provider menyajikan dokumen discovery dan JWKS melalui HTTPS. Terminasi TLS dengan dukungan ACME bawaannya, atau letakkan load balancer yang melakukannya di depannya.

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

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

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



Daftarkan workload

Setiap workload yang memanggil Claude API memerlukan registration entry SPIRE yang memetakan selector runtime-nya ke sebuah SPIFFE ID. Jika workload sudah terdaftar, catat SPIFFE ID-nya, yang Anda gunakan di subject_prefix federation rule. Jika belum, daftarkan. Untuk pod Kubernetes, selector-nya biasanya adalah namespace dan service account Kubernetes:

# Ganti NODE_UID dengan UID node:
#   kubectl get node <node-name> -o jsonpath='{.metadata.uid}'
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

Workload di luar Kubernetes menggunakan selector tingkat host seperti unix:uid:1000 (unix:path juga tersedia tetapi memerlukan discover_workload_path = true dalam konfigurasi unix workload attestor milik agent). Klaster yang menjalankan spire-controller-manager dapat mendeklarasikan entry dengan custom resource ClusterSPIFFEID alih-alih memanggil spire-server entry create secara langsung.



Jalankan spiffe-helper

spiffe-helper adalah utilitas sidecar yang terhubung ke socket SPIRE Agent, mengambil JWT-SVID untuk audience tertentu, menulisnya ke sebuah file, dan mengambilnya kembali sebelum kedaluwarsa. Helper ini berjalan dalam mode daemon secara default. Contoh berikut mengatur daemon_mode = true secara eksplisit.

agent_address = "/run/spire/sockets/agent.sock"
# The JWT-SVID file is written under cert_dir
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

Di Kubernetes, jalankan spiffe-helper sebagai container sidecar yang berbagi volume emptyDir berbasis memori (medium: Memory) dengan container aplikasi Anda sehingga bearer SVID tidak pernah tersimpan di disk node. Mount socket SPIRE Agent dari host ke dalam sidecar, mount volume bersama di /var/run/secrets/anthropic.com di kedua container, dan atur ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token pada container aplikasi. Pada VM dan bare metal, jalankan spiffe-helper sebagai layanan sistem di samping workload dan arahkan keduanya ke direktori bersama.



Konfigurasi Anthropic

Di Claude Console, buka Settings → Workload identity, klik Connect workload, dan pilih Custom OIDC. 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: Daftarkan URL publik OIDC Discovery Provider dalam mode discovery. Anthropic mengambil /.well-known/openid-configuration dari URL ini dan mengikuti jwks_uri yang dikembalikan untuk mengambil kunci penandatanganan trust domain.

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

Jika discovery provider tidak dapat dijangkau dari internet publik, ambil JWKS sendiri (curl https://oidc-discovery.prod.example.com/keys) dan daftarkan issuer dengan "jwks": {"type": "inline", "keys": [...]} menggunakan isi array keys yang dikembalikan. Dalam mode inline, issuer_url hanya dibandingkan dengan klaim iss JWT-SVID. Anthropic tidak pernah mencoba menjangkaunya.

Untuk mengotomatiskan pembaruan JWKS tanpa mengekspos endpoint discovery publik, konfigurasikan plugin BundlePublisher SPIRE Server (aws_s3, gcp_cloudstorage, atau k8s_configmap) dengan format = "jwks" untuk mendorong kunci penandatanganan JWT ke penyimpanan eksternal pada setiap rotasi, lalu perbarui kunci inline issuer melalui Admin API.

Federation rule: Cocokkan sub JWT-SVID (SPIFFE ID) dan aud yang Anda konfigurasikan untuk diminta oleh spiffe-helper. SPIFFE ID adalah string URI dan subject_prefix mencocokkannya sebagai teks opak, sehingga nilai eksak atau pencocokan prefiks dengan * di akhir keduanya berfungsi. Untuk pola yang lebih kompleks, gunakan 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
}

token_lifetime_seconds adalah masa berlaku access token Anthropic yang dikembalikan oleh exchange, bukan masa berlaku JWT-SVID. SDK menyegarkan access token secara otomatis.

Buat sespesifik mungkin sesuai yang dimungkinkan oleh workload. Longgarkan subject_prefix menjadi spiffe://prod.example.com/ns/inference/* hanya jika setiap workload yang terdaftar di bawah path tersebut harus dipetakan ke service account Anthropic yang sama. Tambahkan ID fdrl_... milik rule ke variabel lingkungan ANTHROPIC_FEDERATION_RULE_ID workload.



Dapatkan dan gunakan token

SDK Anthropic dapat membaca JWT-SVID dari file yang dikelola spiffe-helper atau memanggil SPIFFE Workload API secara langsung melalui callable token-provider. Jalur file adalah integrasi paling sederhana dan berfungsi di setiap bahasa SDK. Jalur callable menghilangkan sidecar tetapi memerlukan klien SPIFFE Workload API dalam bahasa aplikasi Anda.

import anthropic

# Membaca JWT-SVID yang ditulis spiffe-helper ke
# ANTHROPIC_IDENTITY_TOKEN_FILE, ditambah ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, dan ANTHROPIC_WORKSPACE_ID.
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 penyiapan

Sebelum menghubungkan SDK, ambil JWT-SVID langsung dari SPIRE Agent dan pastikan klaimnya cocok dengan yang diharapkan oleh federation rule Anda. Jika Anda menggunakan implementasi SPIFFE yang berbeda, ambil JWT-SVID dengan CLI atau klien Workload API-nya dan dekode payload dengan cara yang sama.

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'

Flag -output json mengembalikan respons SVID dan respons bundle sebagai array JSON dua elemen, sehingga jq -r '.[0].svids[0].svid' mengekstrak token mentahnya. Pada versi SPIRE lama tanpa -output, perintah tersebut mencetak blok berlabel sebagai gantinya. Dalam kasus itu, alirkan output default melalui awk '/^[[:space:]]*eyJ/{print $1; exit}' untuk mengekstrak baris token. Periksa bahwa iss adalah URL OIDC Discovery Provider yang Anda daftarkan, sub adalah SPIFFE ID workload, dan aud berisi https://api.anthropic.com. Kemudian jalankan contoh cURL dari Dapatkan dan gunakan token. Exchange yang berhasil mengembalikan access_token yang dimulai dengan sk-ant-oat01-. Pada 400 invalid_grant, lihat Pemecahan masalah exchange yang gagal. Penyebab paling umum di sisi SPIRE adalah ketidakcocokan antara jwt_issuer SPIRE Server dan URL yang terdaftar sebagai federation issuer.



Batasi cakupan aturan Anda

Konvensi path SPIFFE ID ditentukan oleh operator, sehingga matcher subject_prefix pada federation rule harus mencerminkan skema path yang digunakan registration entry Anda. Skema umum meliputi spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (default yang dihasilkan oleh resource ClusterSPIFFEID di spire-controller-manager) dan spiffe://<trust-domain>/host/<hostname>/<service> untuk workload VM dan bare-metal.

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

• Pin ke satu workload: Atur subject_prefix ke SPIFFE ID lengkap tanpa * di akhir.
• Selalu atur audience: Wajibkan audience pada rule dan konfigurasikan spiffe-helper (atau panggilan Workload API) dengan nilai yang sama sehingga SVID yang diterbitkan untuk relying party lain ditolak.
• Batasi cakupan berdasarkan segmen path: Gunakan spiffe://prod.example.com/ns/inference/* untuk memberikan akses kepada setiap workload yang terdaftar di bawah sebuah namespace, dan buat rule serta service account Anthropic terpisah per namespace alih-alih memperluas satu rule.
• Satu issuer per trust domain: Setiap trust domain SPIRE memiliki kunci penandatanganan dan OIDC Discovery Provider sendiri. Daftarkan masing-masing sebagai federation issuer terpisah dan ikat rule ke issuer yang memiliki SPIFFE ID yang dicocokkannya.



Langkah selanjutnya