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 RFC 7523. SDK membangun permintaan ini untuk Anda dari variabel lingkungan; contoh cURL di 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 langsung melalui variabel lingkungan 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 diatur. ANTHROPIC_WORKSPACE_ID dibaca bersamaan tetapi tidak menentukan aktivasi.

Prioritas kredensial

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

Di CLI ant, pengaturan untuk Claude Models on Google Cloud (Anthropic managed) berada di urutan prioritas setelah variabel lingkungan federasi dan sebelum profil aktif. Pengaturan tersebut adalah proyek, ID workspace, dan lokasi. Anda mengaturnya dengan flag --google-cloud-* atau variabel ANTHROPIC_GOOGLE_CLOUD_*. CLI menggunakan pengaturan ini ketika salah satu di antaranya diatur. Dengan pengaturan ini, CLI mendapatkan kredensialnya dari Google Application Default Credentials.

Ketika profil dimuat, variabel lingkungan mengisi field apa pun yang dihilangkan oleh profil tetapi tidak pernah mengesampingkan field yang diatur secara eksplisit oleh profil. Misalnya, ANTHROPIC_WORKSPACE_ID mengisi workspace_id hanya ketika profil aktif tidak mengaturnya.

File konfigurasi profil

Profil adalah file konfigurasi bernama yang dibaca oleh SDK dan CLI ant. Profil memungkinkan Anda menyertakan parameter federasi bersama image container Anda atau beralih 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 mengikuti urutan resolusi yang sama, sehingga profil federasi yang dikonfigurasi di sini juga mengautentikasi alat-alat tersebut tanpa penyiapan tambahan.

Tata letak file

File konfigurasi dan file kredensial sama-sama memiliki 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 konfigurasi 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 beralih ke ANTHROPIC_IDENTITY_TOKEN_FILE atau ANTHROPIC_IDENTITY_TOKEN dari lingkungan.

Scope OAuth

oauth_scope yang Anda atur pada aturan federasi menentukan endpoint Claude API mana yang dapat dipanggil oleh token akses 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 akun layanan target (developer atau admin) menentukan scope mana yang dapat diberikan, sehingga aturan yang memberikan org:admin harus menargetkan akun layanan dengan organization_role=admin. Izin efektif adalah irisan dari scope aturan dan peran akun layanan.

Aturan validasi

Anthropic memberlakukan batasan-batasan ini ketika Anda membuat atau memperbarui issuer dan aturan, serta saat 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 awalan 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 salah satu dari subject_prefix, claims, atau condition harus diatur; blok match yang hanya berisi audience (atau tanpa matcher sama sekali) ditolak. Ini melindungi dari 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 melaporkan kegagalan pertukaran sebagai WorkloadIdentityError, yang memberikan status HTTP dan detail error dari body respons. ID permintaan terdapat pada error di Python, TypeScript, dan Ruby, dan di header respons exception di Java. Di Go, ID tersebut hanya ada di pesan error, karena tipe error berada di paket internal; error C# dan PHP tidak membawanya.

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 di riwayat autentikasi di Claude Console, 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 di riwayat autentikasi, bukan di respons.

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

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

1. 1

   Dekode JWT

   Dekode 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 apakah iss cocok dengan issuer

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

3. 3

   Periksa apakah aud cocok dengan aturan

   Klaim aud yang telah didekode 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 awalan, selain itu pencocokan persis). Bandingkan setiap kunci di map claims aturan dengan klaim tingkat atas yang bernama sama.

5. 5

   Periksa exp, nbf, dan iat

   exp harus berada di masa depan dan nbf/iat harus berada di masa lalu, dalam jendela skew 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 di port 443 dan pastikan jwks_uri dapat di-resolve. Untuk explicit_url, ambil URL JWKS secara langsung. Untuk inline, pastikan kunci penandatanganan issuer belum dirotasi sejak Anda mendaftarkan kunci tersebut.

   Jika issuer merotasi kunci penandatanganannya dan segera mulai menandatangani dengannya, pertukaran dapat gagal hingga satu menit selama 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 melakukan cache terhadap JWKS yang diambil. Jika penyedia identitas Anda menerbitkan kunci penandatanganan baru dan segera mulai menandatangani token dengannya, pertukaran yang menyajikan token tersebut dapat gagal dengan error tanda tangan hingga 1 menit selama cache diperbarui.

Untuk menghindari jendela ini, terbitkan kunci penandatanganan baru di JWKS setidaknya 15 menit sebelum penyedia identitas Anda mulai menandatangani token dengannya, dan pertahankan kunci yang digantikan di JWKS hingga token yang ditandatanganinya 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 server otorisasi kustom Okta dengan jadwal rotasi yang dikonfigurasi), pastikan kebijakan rotasi Anda menerbitkan kunci baru sebelum penggunaan pertama.