Menggunakan WIF dengan SPIFFE

SPIFFE adalah standar CNCF untuk menerbitkan identitas bagi 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 menghasilkan 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 milik workload, dan SPIFFE Workload API mengharuskan pemanggil menyediakan aud pada saat pengambilan, sehingga klaim-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 semua itu terpenuhi, bagian Konfigurasi Anthropic, Memperoleh dan menggunakan token, dan Membatasi cakupan aturan Anda dalam panduan ini berlaku untuk implementasi SPIFFE apa pun.

SPIFFE memberikan setiap workload sebuah URI identitas yang stabil dengan 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 milik 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 memublikasikan /.well-known/openid-configuration dan endpoint JWKS untuk kunci penandatanganan JWT milik trust domain. Dengan discovery provider berjalan, JWT-SVID divalidasi seperti token OIDC lainnya: daftarkan URL discovery sebagai federation issuer (penerbit federasi), tulis federation rule (aturan federasi) yang cocok dengan SPIFFE ID milik workload, dan minta 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, mesin virtual, dan host bare-metal.

Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Deployment SPIFFE dengan identitas workload yang telah diterbitkan (contoh di halaman ini menggunakan SPIRE Server dan Agent), serta 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 milik federation issuer. Untuk mode discovery, ini adalah URL publik endpoint discovery (di SPIRE, pengaturan server jwt_issuer).
• JWT-SVID tersedia bagi 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 milik 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 dokumentasinya sendiri, lalu lanjutkan ke 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 milik issuer tersebut. Dua pengaturan SPIRE harus sepakat pada URL yang sama: jwt_issuer milik SPIRE Server (yang menjadi klaim iss di setiap JWT-SVID yang dicetak) dan daftar domains milik 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) membatasi 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 menampilkan masa berlaku JWT-SVID default. Default bawaan SPIRE adalah 5 menit, yang cukup singkat sehingga rotasi berkelanjutan diperlukan (lihat Menjalankan 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 milik SPIRE Server. Provider menyajikan dokumen discovery dan JWKS melalui HTTPS. Terminasi TLS dengan dukungan ACME bawaannya, atau tempatkan di belakang load balancer yang melakukannya.

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

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

acme {
    email        = "platform@example.com"
    tos_accepted = true
}

Mendaftarkan 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 pada 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). Cluster yang menjalankan spire-controller-manager dapat mendeklarasikan entry dengan custom resource ClusterSPIFFEID alih-alih memanggil spire-server entry create secara langsung.

Menjalankan spiffe-helper

spiffe-helper adalah utilitas sidecar yang terhubung ke socket SPIRE Agent, mengambil JWT-SVID untuk audience tertentu, menuliskannya ke 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 pada 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 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: 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 milik 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 pada 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 milik issuer melalui Admin API.

Federation rule: Cocokkan sub pada 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 persis maupun pencocokan prefiks dengan * di akhir sama-sama 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 memperbarui access token secara otomatis.

Buatlah sespesifik 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 aturan ke variabel lingkungan ANTHROPIC_FEDERATION_RULE_ID pada workload.

Memperoleh dan menggunakan token

SDK Anthropic dapat membaca JWT-SVID dari file yang dikelola spiffe-helper atau memanggil SPIFFE Workload API secara langsung melalui callable penyedia token. 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 klaim-klaimnya cocok dengan yang diharapkan 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, salurkan 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 milik workload, dan aud berisi https://api.anthropic.com. Kemudian jalankan contoh cURL dari Memperoleh dan menggunakan token. Exchange yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01-. Jika exchange gagal dengan respons opak 401 authentication_error (pesan Authentication failed), periksa halaman riwayat autentikasi untuk alasan penolakan dan lihat Memecahkan masalah exchange yang gagal. Penyebab paling umum di sisi SPIRE adalah ketidakcocokan antara jwt_issuer milik SPIRE Server dan URL yang didaftarkan sebagai federation issuer.

Membatasi 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 mencakup 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 aturan ke cakupan tersempit yang sesuai dengan kasus penggunaan Anda:

• Sematkan ke satu workload: Atur subject_prefix ke SPIFFE ID lengkap tanpa * di akhir.
• Selalu atur audience: Wajibkan audience pada aturan dan konfigurasikan spiffe-helper (atau panggilan Workload API) dengan nilai yang sama sehingga SVID yang dicetak untuk relying party lain ditolak.
• Batasi cakupan berdasarkan segmen path: Gunakan spiffe://prod.example.com/ns/inference/* untuk memberi akses kepada setiap workload yang terdaftar di bawah sebuah namespace, dan buat aturan serta service account Anthropic terpisah per namespace alih-alih memperluas satu aturan.
• 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 aturan ke issuer yang memiliki SPIFFE ID yang dicocokkannya.

Langkah selanjutnya