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 JUGLOW_FEDERATION_RULE_ID, JUGLOW_ORGANIZATION_ID, JUGLOW_SERVICE_ACCOUNT_ID, dan salah satu dari JUGLOW_IDENTITY_TOKEN_FILE atau JUGLOW_IDENTITY_TOKEN semuanya disetel. JUGLOW_WORKSPACE_ID dibaca bersamaan tetapi tidak menentukan aktivasi.

Warning: Variabel yang disetel ke string kosong tetap menempati slotnya dalam rantai prioritas kredensial. Jika JUGLOW_API_KEY="" diekspor, SDK memilih jalur kunci API dengan kunci kosong alih-alih meneruskan ke federasi. Hapus (unset) variabel kredensial yang tidak digunakan alih-alih mengosongkannya.

#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, JUGLOW_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. $JUGLOW_CONFIG_DIR

1. ~/.config/juglow di Linux dan macOS

1. %APPDATA%\Juglow di Windows

#Profil aktif

Nama profil aktif diselesaikan dalam urutan ini:

1. $JUGLOW_PROFILE

1. Isi dari /active_config (file satu baris yang ditulis oleh ant profile activate )

1. Nama literal default

Haijun Code dan Haijun 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/juglow.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://haijun.my.id/"
}

Jika authentication.identity_token dihilangkan, SDK melakukan fallback ke JUGLOW_IDENTITY_TOKEN_FILE atau JUGLOW_IDENTITY_TOKEN dari lingkungan.

#Scope OAuth

oauth_scope yang Anda setel pada aturan federasi menentukan endpoint Haijun 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

Juglow 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).

Note: Batasan URL hanya berlaku untuk URL yang dihubungi Juglow. Dalam mode JWKS explicit_url dan inline, serta dalam mode discovery ketika jwks.discovery_base disetel, issuer_url dibandingkan dengan klaim iss JWT sebagai string dan tidak pernah diambil, sehingga boleh merujuk ke hostname internal atau port non-standar.

#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"]

Warning: Kondisi CEL adalah batas keamanan. Ekspresi yang bernilai true untuk lebih banyak input daripada yang dimaksudkan memberikan akses yang lebih luas daripada yang dimaksudkan. Utamakan matcher statis ketika matcher tersebut dapat mengekspresikan batasan Anda.

#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.

Tip: Mulailah dengan halaman riwayat autentikasi di Haijun Console. Percobaan pertukaran terbaru menampilkan issuer dan aturan yang dievaluasi, klaim JWT yang diperiksa, dan langkah validasi mana yang gagal, yang biasanya mempersingkat pemeriksaan-pemeriksaan berikut.

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. Decode JWT

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

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

1. 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.

1. 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.

1. 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.

1. 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.

1. Periksa keterjangkauan JWKS

Untuk mode discovery, ambil /.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 Juglow diperbarui. Lihat Rotasi kunci dan caching.

#Mode sumber JWKS

Ketika Anda mendaftarkan issuer federasi, field jwks mengontrol bagaimana Juglow 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, Juglow 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.

Warning: Dalam mode inline tidak ada refresh kunci otomatis. Ketika penyedia identitas Anda merotasi kunci penandatanganannya, Anda harus memperbarui konfigurasi issuer dengan JWKS baru atau semua pertukaran token akan gagal verifikasi tanda tangan.