Workload Identity Federation

"Workload Identity Federation" (federasi identitas workload), atau WIF, memungkinkan workload Anda melakukan autentikasi ke Claude API dengan token OpenID Connect (OIDC) berumur pendek alih-alih kunci API sk-ant-... berumur panjang. Token tersebut berasal dari "identity provider" (penyedia identitas), atau IdP, yang sudah Anda operasikan: AWS IAM, Google Cloud, atau penerbit OIDC apa pun yang sesuai standar seperti GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID, atau Okta.

Workload Anda menyajikan JWT yang ditandatangani dari penyedia identitas Anda. Anthropic memvalidasinya terhadap aturan kepercayaan yang Anda konfigurasikan di Claude Console dan mengembalikan token akses Anthropic berumur pendek yang terikat ke akun layanan di organisasi Anda. Tidak ada rahasia statis yang perlu dibuat, disimpan di CI, dirotasi, atau berisiko bocor.

Workload Identity Federation memperkuat postur keamanan Anda dengan mengganti kunci API statis dengan token yang kedaluwarsa dalam hitungan menit, bukan tidak pernah kedaluwarsa. Namun, ini bukan solusi keamanan yang lengkap dengan sendirinya: autentikasi terfederasi hanya sekuat penyedia identitas upstream yang menandatangani JWT tersebut. Padukan Workload Identity Federation dengan kontrol yang sudah didukung IdP Anda (pengikatan identitas workload, akses bersyarat, pencatatan audit) untuk pertahanan berlapis.

Konsep

Anda mengonfigurasi tiga sumber daya di Claude Console sebelum workload apa pun dapat melakukan federasi. Bersama-sama, ketiganya menyatakan "token yang ditandatangani oleh penerbit X, dengan klaim yang terlihat seperti Y, boleh bertindak sebagai akun layanan Z."

Akun layanan

Akun layanan (svac_...) adalah identitas non-manusia bernama di dalam organisasi Anthropic Anda. Ini adalah prinsipal yang diwakili oleh token terfederasi saat bertindak. Akun layanan berada di tingkat organisasi dan menjadi aktif di sebuah workspace ketika Anda menambahkannya sebagai anggota workspace tersebut. Pada saat pertukaran, Anthropic memeriksa bahwa workspace pada aturan federasi cocok dengan salah satu keanggotaan workspace akun layanan; token yang dibuat kemudian mengikuti batas laju dan atribusi penggunaan workspace tersebut, sama seperti kunci API. Tidak seperti pengguna manusia, akun layanan tidak memiliki email, kata sandi, maupun login Console.

Perbedaan utama dari kunci API: kunci API adalah kredensial, sedangkan akun layanan memiliki kredensial yang dibuat untuknya sesuai permintaan. Anda dapat mengaudit workload mana yang bertindak sebagai akun layanan mana.

Penerbit federasi

Penerbit federasi (fdis_...) mendaftarkan penyedia identitas OIDC ke organisasi Anda. Mendaftarkan penerbit memberi tahu Anthropic "JWT yang ditandatangani oleh penyedia ini boleh menyatakan identitas workload untuk organisasi saya."

Sebuah penerbit memiliki dua bagian konfigurasi:

• Issuer URL: Nilai klaim iss persis yang muncul di JWT penyedia, misalnya https://token.actions.githubusercontent.com atau https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• Sumber JWKS: Cara Anthropic mengambil kunci publik untuk memverifikasi tanda tangan JWT. Gunakan discovery (default) untuk penyedia apa pun yang menyajikan /.well-known/openid-configuration di URL penerbitnya. Gunakan explicit_url untuk menunjuk langsung ke endpoint JWKS, atau inline untuk mengunggah kumpulan kunci bagi penerbit yang tidak dapat dijangkau dari internet publik (misalnya, klaster Kubernetes privat).

URL penerbit dan JWKS harus menggunakan https, pada port 443, dan menggunakan nama host DNS publik yang me-resolve ke alamat IP publik; literal IP tidak diterima. Batasan ini hanya berlaku untuk URL yang diambil Anthropic; dalam mode explicit_url dan inline, issuer_url dibandingkan sebagai string dan boleh merujuk ke nama host internal.

Anda biasanya mendaftarkan satu penerbit per lingkungan: klaster EKS produksi Anda, klaster staging Anda, dan GitHub Actions adalah tiga penerbit terpisah.

Aturan federasi

Aturan federasi (fdrl_...) adalah jembatan antara penerbit dan akun layanan: "ketika JWT dari penerbit X memiliki klaim yang terlihat seperti Y, buat token untuk akun layanan Z dengan cakupan S."

Sebuah aturan mendefinisikan kondisi pencocokan, target, serta cakupan otorisasi dan masa berlaku token yang diterapkan ketika aturan tersebut cocok:

• Match: Kondisi yang harus dipenuhi oleh JWT yang masuk. Anda dapat mencocokkan berdasarkan subject_prefix (misalnya, system:serviceaccount:prod:worker, atau dengan * di akhir untuk pencocokan prefiks), audience yang persis, map nilai klaim yang persis, ekspresi condition CEL untuk logika kompleks, atau kombinasi apa pun. Setidaknya salah satu dari subject_prefix, claims, atau condition harus diatur, dan semua pencocok yang dikonfigurasi harus lolos agar JWT diterima.
• Target: Akun layanan yang dipetakan ke JWT yang cocok.
• Authorization: scope OAuth yang diberikan pada token yang dibuat. Default-nya adalah workspace:developer, yang memberikan akses yang sama seperti kunci API yang diterbitkan untuk workspace tersebut. Beberapa produk mengunci cakupan ketika Anda membuat aturan dari alur mereka; misalnya, modal create-tunnel pada MCP tunnels membuat aturan dengan cakupan org:manage_tunnels. Lihat Cakupan OAuth. Aturan ini juga mengatur token_lifetime_seconds (60 hingga 86400, default 3600).

Satu penerbit dapat memiliki banyak aturan: satu per tim, namespace, atau tingkat izin. Aturan dievaluasi berdasarkan ID: klien menentukan aturan mana yang akan digunakan dalam permintaan pertukaran, dan Anthropic memverifikasi bahwa JWT memenuhi kriteria pencocokan aturan tersebut. Tidak ada pencarian aturan implisit.

Cara kerjanya

1. IdP Anda menerbitkan JWT ke workload. Pada sebagian besar platform, ini bersifat ambien: token service-account terproyeksi Kubernetes, server metadata Google Cloud, Azure IMDS, atau endpoint OIDC GitHub Actions. Klaim iss pada JWT mengidentifikasi penyedia, dan klaim sub serta klaim lainnya mengidentifikasi workload spesifik.
2. SDK menukar JWT dengan token akses Anthropic. SDK mengirim JWT ke POST /v1/oauth/token menggunakan grant jwt-bearer RFC 7523. Anthropic memverifikasi JWT terhadap JWKS penerbit dan kondisi pencocokan aturan federasi, lalu mengembalikan token sk-ant-oat01-... berumur pendek yang bertindak atas nama akun layanan target aturan tersebut.
3. SDK mengirim token pada setiap permintaan dan me-refresh-nya sebelum kedaluwarsa. Kode aplikasi Anda membuat klien tanpa api_key dan memanggil API seperti biasa. SDK menjalankan ulang pertukaran sebelum token kedaluwarsa.

Menyiapkan federasi

Anda memerlukan akses admin ke organisasi Anthropic Anda, penyedia identitas berkemampuan OIDC dengan endpoint JWKS yang dapat dijangkau (atau dokumen JWKS yang dapat Anda tempel, untuk klaster air-gapped), dan workload yang dapat memperoleh token identitas dari penyedia tersebut.

Di Claude Console, buka Settings → Workload identity.

Autentikasi dari workload Anda

Dengan federasi yang telah dikonfigurasi, workload Anda menukar JWT yang diterbitkan IdP dengan token Anthropic pada saat runtime. SDK menangani pertukaran dan loop refresh untuk Anda. Tab cURL menunjukkan pertukaran HTTP yang mendasarinya untuk skrip shell, debugging, atau bahasa tanpa dukungan SDK.

Membuat klien SDK

Anda dapat membuat klien dengan kredensial eksplisit atau tanpa argumen. Tanpa argumen, SDK me-resolve kredensial dari variabel lingkungan atau profil aktif, seperti dijelaskan di bagian Prioritas kredensial. Bentuk tanpa argumen adalah pola yang direkomendasikan untuk workload produksi: kirimkan image container yang sama ke mana saja dan injeksikan ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID, dan ANTHROPIC_IDENTITY_TOKEN_FILE per lingkungan.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Respons pertukaran token mengikuti RFC 6749 §5.1. Lihat Respons pertukaran token untuk referensi kolom.

Prioritas kredensial

Setiap SDK me-resolve kredensial dalam urutan lima tingkat yang sama: argumen konstruktor, lalu ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, lalu ANTHROPIC_PROFILE eksplisit, lalu variabel lingkungan federasi, lalu profil aktif implisit. Sumber pertama yang menghasilkan kredensial akan menang.

Untuk tabel prioritas lengkap, semantik per tingkat, dan skema file profil, lihat Prioritas kredensial di referensi WIF.

Migrasi dari kunci API

Untuk mengalihkan workload yang ada dari kunci API statis ke federasi tanpa downtime:

1. Konfigurasikan federasi secara paralel. Selesaikan panduan penyiapan dan pastikan aturan federasi cocok dengan token workload Anda. Biarkan ANTHROPIC_API_KEY yang ada tetap di tempatnya untuk saat ini.
2. Lakukan smoke-test untuk melihat kredensial mana yang menang. Jalankan ant auth status dari dalam workload (atau periksa log debug SDK). Karena ANTHROPIC_API_KEY berada di atas tingkat federasi dalam rantai prioritas, kunci API masih menang pada tahap ini.
3. Hapus pengaturan ANTHROPIC_API_KEY di mana pun ia diinjeksikan. Hapus dari rahasia CI, lingkungan container, dan profil shell (lihat peringatan sebelumnya). Jalankan ulang ant auth status dan pastikan sumber federasi sekarang terpilih.
4. Cabut kunci API. Setelah workload berjalan dengan token terfederasi, hapus kunci tersebut di Claude Console di bawah Settings → API keys.

Masa berlaku token dan refresh

Masa berlaku token Anthropic yang dibuat adalah nilai yang lebih kecil antara (a) token_lifetime_seconds aturan (default 3600 detik) dan (b) dua kali sisa masa berlaku JWT IdP yang Anda sajikan. Hasilnya tidak pernah kurang dari 60 detik. Batasan kedua mencegah token Anthropic bertahan lebih lama dari identitas upstream asalnya dengan selisih lebih dari margin kecil.

SDK menyimpan token dalam cache dan me-refresh-nya dengan jadwal dua tingkat yang dimodelkan dari botocore:

• Advisory refresh pada waktu kedaluwarsa dikurangi 120 detik. SDK mencoba pertukaran baru. Jika endpoint token tidak dapat dijangkau, SDK terus menyajikan token yang di-cache, yang masih valid selama sekitar 90 detik lagi.
• Mandatory refresh pada waktu kedaluwarsa dikurangi 30 detik. Pertukaran yang gagal pada titik ini memunculkan error. Token yang di-cache terlalu dekat dengan waktu kedaluwarsa untuk aman digunakan.

Karena SDK membaca ulang ANTHROPIC_IDENTITY_TOKEN_FILE pada setiap pertukaran, SDK secara transparan mengambil token terproyeksi yang dirotasi (token service-account Kubernetes, misalnya, dirotasi jauh sebelum exp-nya).

Penyedia identitas

Setiap panduan membahas dari mana JWT berasal pada platform tersebut, seperti apa klaimnya, serta konfigurasi penerbit dan aturan yang perlu didaftarkan.

Lihat juga

• Referensi WIF: variabel lingkungan, skema file profil, aturan validasi, dan kode error
• Autentikasi: semua opsi autentikasi di seluruh SDK Anthropic