Referensi WIF

Halaman ini mengumpulkan permukaan konfigurasi, batasan validasi, dan pemetaan error untuk Workload Identity Federation. Untuk panduan penyiapan langkah demi langkah, lihat panduan penyedia.

Permintaan pertukaran token

POST /v1/oauth/token menerima body JSON menggunakan grant jwt-bearer dari RFC 7523. SDK membangun permintaan ini untuk Anda dari variabel lingkungan; contoh cURL pada setiap panduan penyedia menunjukkan body mentahnya.

Respons pertukaran token

POST /v1/oauth/token mengembalikan respons token OAuth 2.0 standar (RFC 6749 §5.1):

Variabel lingkungan

SDK membaca variabel-variabel ini untuk melakukan pertukaran token terfederasi tanpa argumen konstruktor.

Jalur federasi variabel-lingkungan langsung hanya aktif ketika ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, dan salah satu dari ANTHROPIC_IDENTITY_TOKEN_FILE atau ANTHROPIC_IDENTITY_TOKEN semuanya disetel. ANTHROPIC_WORKSPACE_ID dibaca bersamaan tetapi tidak menentukan aktivasi.

Prioritas kredensial

SDK menyelesaikan kredensial dalam urutan ini. Sumber pertama yang menghasilkan kredensial yang menang.

Ketika sebuah profil dimuat, variabel lingkungan mengisi field apa pun yang dihilangkan profil tetapi tidak pernah menimpa field yang disetel profil secara eksplisit. Misalnya, ANTHROPIC_WORKSPACE_ID mengisi workspace_id hanya ketika profil aktif tidak menyetelnya.

File konfigurasi profil

Profil adalah file konfigurasi bernama yang dibaca oleh SDK dan CLI ant. Profil memungkinkan Anda mengirimkan parameter federasi bersama image container Anda atau berpindah antar lingkungan tanpa mengubah kode.

Direktori konfigurasi

SDK menemukan direktori konfigurasi dalam urutan ini:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic di Linux dan macOS
3. %APPDATA%\Anthropic di Windows

Profil aktif

Nama profil aktif diselesaikan dalam urutan ini:

1. $ANTHROPIC_PROFILE
2. Isi dari <config_dir>/active_config (file satu baris yang ditulis oleh ant profile activate <name>)
3. Nama literal default

Claude Code dan Claude Agent SDK mematuhi urutan resolusi yang sama ini, sehingga profil federasi yang dikonfigurasi di sini juga mengautentikasi alat-alat tersebut tanpa penyiapan tambahan.

Tata letak file

Baik file config maupun file credentials membawa field string version tingkat atas dalam format major.minor (saat ini "1.0"). SDK menulis field ini secara otomatis sehingga rilis mendatang dapat mendeteksi dan memigrasikan format lama; hilangkan field ini saat menulis config secara manual dan SDK akan memperlakukan file tersebut sebagai versi saat ini.

Contoh profil federasi

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Jika authentication.identity_token dihilangkan, SDK melakukan fallback ke ANTHROPIC_IDENTITY_TOKEN_FILE atau ANTHROPIC_IDENTITY_TOKEN dari lingkungan.

Scope OAuth

oauth_scope yang Anda setel pada aturan federasi menentukan endpoint Claude API mana yang dapat dipanggil oleh access token yang dicetak.

Permintaan ke endpoint di luar scope token mengembalikan HTTP 403. Scope yang lebih terperinci (per sumber daya, atau baca versus tulis) saat ini tidak tersedia.

Batas izin

oauth_scope aturan federasi adalah batas atas: token yang dicetak tidak pernah dapat melampauinya. organization_role service account target (developer atau admin) menentukan scope mana yang dapat diberikan, sehingga aturan yang memberikan org:admin harus menargetkan service account dengan organization_role=admin. Izin efektif adalah irisan dari scope aturan dan role service account.

Aturan validasi

Anthropic menegakkan batasan-batasan ini ketika Anda membuat atau memperbarui issuer dan aturan, serta ketika memverifikasi JWT yang masuk pada saat pertukaran.

Untuk detail parameter lengkap dan skema respons, lihat referensi API Service accounts, referensi API Federation issuers, dan referensi API Federation rules.

Field sumber daya

Field URL

Field issuer_url, jwks.discovery_base, dan jwks.url divalidasi:

Kegagalan validasi URL mengembalikan 400 invalid_request_error dengan nama field sebagai prefiks pada pesan error (misalnya, issuer_url: url must use https scheme).

Verifikasi JWT

Semantik pencocokan aturan

Blok match aturan federasi menentukan apakah JWT yang masuk diterima. Semua field yang terisi dievaluasi dengan semantik AND: JWT harus memenuhi setiap matcher yang terisi. Setidaknya satu dari subject_prefix, claims, atau condition harus disetel; blok match yang hanya berisi audience (atau tanpa matcher sama sekali) ditolak. Ini mencegah aturan yang akan menerima setiap token dari suatu issuer.

Lingkungan evaluasi CEL

Ekspresi condition memiliki akses ke satu variabel:

Contoh:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Error

Error pertukaran token

POST /v1/oauth/token mengembalikan error dalam bentuk error API standar. SDK membungkus kegagalan pertukaran dalam FederationExchangeError bertipe (atau padanannya di bahasa lain) yang mengekspos status HTTP, body respons, dan request_id.

Setiap penolakan assertion mengembalikan 401 authentication_error buram yang sama dengan pesan tetap Authentication failed, terlepas dari pemeriksaan mana yang gagal; error yang dapat dibedakan akan memungkinkan pemanggil menyelidiki konfigurasi aturan. Alasan penolakan dicatat pada entri percobaan tersebut di riwayat autentikasi, misalnya match_subject_prefix ketika klaim sub gagal memenuhi subject_prefix aturan, atau workspace_id_required ketika aturan mencakup beberapa workspace dan permintaan tidak menyebutkan satu pun. Permintaan yang ditolak sebelum organisasi aturan dikonfirmasi (keluarga 400 invalid_request_error di atas) tidak meninggalkan entri riwayat; pesan responsnya menyebutkan masalahnya secara langsung. 401 tanpa entri riwayat yang cocok biasanya berarti federation_rule_id itu sendiri tidak dikenali.

Kegagalan umum di sisi SDK

Memecahkan masalah pertukaran yang gagal

Respons 401 authentication_error sengaja dibuat buram dan pesannya selalu Authentication failed; alasan penolakan dicatat dalam riwayat autentikasi, bukan dalam respons.

Salah satu kegagalan buram yang umum adalah assertion yang di-replay: assertion yang membawa klaim jti hanya dapat ditukar sekali, sehingga workload yang mengirim ulang JWT yang sama (loop retry, atau refresh yang membaca ulang token yang belum dirotasi) ditolak pada pertukaran kedua. Halaman riwayat autentikasi menampilkan percobaan ini dengan alasan jti_reused; perbaikannya adalah mencetak assertion baru untuk setiap pertukaran.

Jika Anda masih perlu melakukan debug dari JWT itu sendiri, lakukan pemeriksaan berikut secara berurutan:

1. 1

   Decode JWT

   Decode assertion yang Anda kirim sehingga Anda dapat membandingkan setiap klaim dengan konfigurasi issuer dan aturan Anda:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Periksa iss cocok dengan issuer

   Klaim iss yang telah di-decode harus sama dengan issuer_url yang terdaftar byte demi byte, termasuk skema, port, dan garis miring di akhir jika ada. Ketidakcocokan pada satu karakter saja menggagalkan verifikasi.

3. 3

   Periksa aud cocok dengan aturan

   Klaim aud yang telah di-decode harus berisi nilai audience aturan sebagai pencocokan persis. Ketika aud berupa array, satu elemen harus cocok persis.

4. 4

   Periksa sub dan setiap entri claims

   Bandingkan sub dengan subject_prefix aturan (peka huruf besar/kecil; * di akhir adalah pencocokan prefiks, selain itu adalah pencocokan persis). Bandingkan setiap kunci dalam map claims aturan dengan klaim tingkat atas bernama sama.

5. 5

   Periksa exp, nbf, dan iat

   exp harus di masa depan dan nbf/iat harus di masa lalu, dalam jendela selisih 30 detik. Jika jam host workload telah bergeser, token yang sebenarnya valid akan ditolak.

6. 6

   Periksa keterjangkauan JWKS

   Untuk mode discovery, ambil <jwks.discovery_base or issuer_url>/.well-known/openid-configuration melalui HTTPS publik pada port 443 dan pastikan jwks_uri ter-resolve. Untuk explicit_url, ambil URL JWKS secara langsung. Untuk inline, pastikan kunci penandatanganan issuer belum dirotasi sejak Anda mendaftarkan kunci-kunci tersebut.

   Jika issuer merotasi kunci penandatanganannya dan langsung mulai menandatangani dengannya, pertukaran dapat gagal hingga satu menit selagi cache JWKS Anthropic diperbarui. Lihat Rotasi kunci dan caching.

Mode sumber JWKS

Ketika Anda mendaftarkan issuer federasi, field jwks mengontrol bagaimana Anthropic memperoleh kunci publik yang digunakan untuk memverifikasi tanda tangan JWT dari issuer tersebut. Field ini adalah discriminated union dengan kunci type:

Discriminated union membuat field pendamping saling eksklusif secara konstruksi. Baik discovery maupun explicit_url juga menerima string ca_cert_pem opsional untuk issuer yang menyajikan TLS dari CA privat.

Rotasi kunci dan caching

Dalam mode discovery dan explicit_url, Anthropic meng-cache JWKS yang diambil. Jika penyedia identitas Anda memublikasikan kunci penandatanganan baru dan langsung mulai menandatangani token dengannya, pertukaran yang menyajikan token tersebut dapat gagal dengan error tanda tangan hingga 1 menit selagi cache diperbarui.

Untuk menghindari jendela ini, publikasikan kunci penandatanganan baru dalam JWKS setidaknya 15 menit sebelum penyedia identitas Anda mulai menandatangani token dengannya, dan pertahankan kunci yang digantikan dalam JWKS hingga token yang ditandatanganinya telah kedaluwarsa. Penyedia identitas terkelola biasanya mengikuti disiplin ini dengan sendirinya. Jika Anda mengoperasikan issuer sendiri (cluster Kubernetes yang dikelola sendiri, penyedia discovery OIDC SPIRE, atau authorization server kustom Okta dengan irama rotasi yang dikonfigurasi), pastikan kebijakan rotasi Anda memublikasikan kunci baru sebelum penggunaan pertama.