Menggunakan WIF dengan SPIFFE

SPIFFE adalah standar CNCF untuk menerbitkan identitas ke 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. Federasi bekerja baik melalui dokumen OIDC discovery di URL HTTPS publik (mode discovery; lihat 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 untuk menyediakan aud pada saat pengambilan, sehingga klaim-klaim tersebut sama di semua implementasi. Anthropic juga memerlukan 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 hal-hal tersebut tersedia, bagian Mengonfigurasi Anthropic, Memperoleh dan menggunakan token, dan Membatasi cakupan rule Anda dalam panduan ini berlaku untuk implementasi SPIFFE apa pun. Untuk daftar terkini, lihat Commercial software that implements SPIFFE di situs proyek SPIFFE.

SPIFFE menetapkan 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 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, tulis federation rule 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), dan registration entry untuk workload yang perlu memanggil Claude API.
• Endpoint OIDC discovery untuk trust domain (di SPIRE, OIDC Discovery Provider) yang berjalan dengan endpoint HTTPS yang dapat dijangkau secara publik, atau JWKS yang diekspor untuk registrasi 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; X.509-SVID tidak digunakan.
• 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.

Mengonfigurasi SPIRE

Instruksi di bagian ini khusus untuk SPIRE. Jika Anda menggunakan penerbit SPIFFE yang berbeda, konfigurasikan endpoint OIDC discovery dan pengambilan JWT-SVID sesuai dokumentasinya sendiri, lalu lanjutkan ke Mengonfigurasi 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 menunjukkan pengaturan yang relevan dengan federasi Anthropic; ini bukan konfigurasi deployment SPIRE yang lengkap.

Memverifikasi 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) membatasi cakupan klaim sub; URL issuer (https://oidc-discovery.prod.example.com) adalah tempat Anthropic mengambil kunci penandatanganan. Keduanya tidak perlu berbagi hostname yang sama.

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 Menjalankan spiffe-helper). Endpoint token-exchange Anthropic menolak token identitas apa pun yang masa berlakunya melebihi maksimum yang dikonfigurasi pada federation issuer (1 jam secara default; lihat Aturan validasi). Pemeriksaan ini berlaku untuk setiap implementasi SPIFFE, bukan hanya SPIRE, jadi jaga 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 tempatkan load balancer di depannya yang melakukan hal tersebut.

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

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

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

Mendaftarkan workload

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

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 agent). Klaster 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, menulisnya ke file, dan mengambilnya kembali sebelum kedaluwarsa. Helper berjalan dalam mode daemon secara default; contoh di bawah ini mengatur daemon_mode = true secara eksplisit.

agent_address = "/run/spire/sockets/agent.sock"
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. Di VM dan bare metal, jalankan spiffe-helper sebagai layanan sistem di samping workload dan arahkan keduanya ke direktori bersama.

Mengonfigurasi Anthropic

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

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 sinkronkan itu ke dalam kunci inline issuer.

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 opaque, sehingga nilai persis atau pencocokan prefiks dengan * di akhir keduanya berfungsi terhadapnya. 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
}

Buat sespesifik yang diizinkan 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_... rule ke variabel lingkungan ANTHROPIC_FEDERATION_RULE_ID 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.

Memverifikasi 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 decode 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 mentah. Pada versi SPIRE lama tanpa -output, perintah mencetak blok berlabel; dalam kasus tersebut, pipe 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 Memperoleh dan menggunakan token; pertukaran yang berhasil mengembalikan access_token yang dimulai dengan sk-ant-oat01-. Pada 400 invalid_grant, lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum di sisi SPIRE adalah ketidakcocokan antara jwt_issuer SPIRE Server dan URL yang terdaftar sebagai federation issuer.

Membatasi cakupan rule Anda

Konvensi path SPIFFE ID ditentukan oleh operator, sehingga matcher subject_prefix 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 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 ke setiap workload yang terdaftar di bawah 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

• Workload Identity Federation: konsep, alur token-exchange, dan opsi konfigurasi SDK.
• Referensi WIF: variabel lingkungan, mode sumber JWKS, dan mode pencocokan rule.
• Menggunakan WIF dengan Kubernetes: untuk klaster yang menggunakan projected service-account token bawaan alih-alih SPIRE.