Konsolidasi JWT via Proxy

A. Ringkasan & Definition of Done

Sejak nginx/default.conf.docker mengarahkan seluruh /api/v1/* ke proxy-service (bukan lagi langsung ke tiap service), ada dua lapis flag terpisah yang menentukan apakah verifikasi JWT benar-benar dipindahkan ke proxy, atau topologi baru ini cuma menambah satu loncatan jaringan tanpa mengubah perilaku auth:

• PROXY_RESOLVE_JWT (dibaca proxy-service) — menyalakan resolusi identitas di jalur preset.
• RESOLVE_JWT_VIA_PROXY (dibaca tiap backend service) — menyalakan kepercayaan pada header X-User-*/X-Tenant-* yang dikirim proxy, alih-alih verifikasi JWT sendiri.

DoD aktivasi dianggap selesai bila:

• Urutan aktivasi §F dijalankan berurutan, tiap tahap diverifikasi sebelum lanjut ke tahap berikutnya.
• Log startup proxy mencetak Gateway identity headers: ON dan tiap service yang sudah dipindah mencetak mode 2 (lihat §E.3).
• Probe akses langsung ke port service (bukan lewat proxy) ditolak 401/403 — lihat §E.3.4.

B. Dua mode & arti flag

PROXY_RESOLVE_JWT / PROXY_RESOLVE_JWT_ENFORCE — sisi proxy-service

RESOLVE_JWT_VIA_PROXY — sisi tiap backend service

Dipakai identik di sembilan service Go (authentication, tenant-management, migration, integration, bpm, report, notification, compro, generate-test) dan diadaptasi ke Java/Spring di camunda.

Dalam Mode 2, kalau kredensial gateway valid tapi header identitas kosong (mis. request service-to-service, atau lewat jalur preset yang belum resolve_jwt), service turun lagi ke jalur lama dan memverifikasi token sendiri — bukan ditolak. Ini "mode dual" yang membuat Mode 2 tidak memutus trafik internal.

C. Diagram alur request

Sebelum — nginx proxy_pass langsung ke tiap container service:

Sesudah — setiap location ^~ /api/v1/<slug>/ (kecuali /api/v1/proxy/ milik proxy sendiri) diarahkan ke proxy-service:3011, yang lalu meneruskannya ke backend asli lewat PresetForwarder (config/services.json):

Port tiap service (3001–3012) memakai expose: di docker-compose.yml, bukan ports: — sejak sebelum task ini, tapi sekarang inilah syarat mutlak Mode 2 aman: kalau salah satu berubah jadi ports: saat debugging, service itu bisa dijangkau langsung dari host sambil melewati proxy sepenuhnya. Jangan lupa kembalikan ke expose: sebelum merge.

Path yang SENGAJA TIDAK lewat proxy (tidak diubah, tetap langsung ke service-nya):

Panggilan service-to-service di dalam network (bpm-service memanggil notification:3005, worker Camunda memanggil camunda:8080/engine-rest/...) tidak lewat nginx sama sekali, jadi tidak terpengaruh oleh perubahan topologi ini.

D. Kontrak header X-User-* / X-Tenant-*

Sisi pengirim: proxy-service/middleware/identity_headers.go. Nama header harus sama persis di semua service consumer — ini kontrak lintas repo, bukan konvensi per service.

Dua field tambahan yang TIDAK ada di kontrak proxy, tapi tetap wajib jalan di report-service: camunda_tenant_uuid dan act_env. Keduanya tetap di-resolve lokal di report-service dari header x-act-env + tabel tenant_environment_mapping, di kedua mode — lihat gejala tenant bocor di §H.

E. Gateway shared secret

E.1 Mekanisme

Proxy mengirim X-Gateway-Token: <GATEWAY_SHARED_SECRET> pada setiap request yang diteruskannya. Backend memvalidasi dengan perbandingan constant-time (crypto/subtle.ConstantTimeCompare di Go, MessageDigest.isEqual di camunda) — bukan == biasa, supaya waktu respons tidak bocor informasi tentang seberapa cocok tebakan penyerang. Secret kosong selalu dijawab tidak valid lebih dulu, sebelum membandingkan apa pun.

Strip header identitas dari request masuk (X-User-*, X-Tenant-*, X-Gateway-Token) berjalan selalu, tanpa syarat — bahkan saat GATEWAY_SHARED_SECRET kosong dan tidak ada injeksi sama sekali. Mengosongkan secret mematikan injeksi, bukan strip; tidak ada konfigurasi yang mengirim header identitas tanpa token gateway.

E.2 Membuat & menyetel

openssl rand -hex 32

Syarat: sama persis di proxy-service dan di setiap service upstream. Jangan pakai ulang nilai dari secret lain yang masa pakainya berbeda (mis. TENANT_SETTINGS_ENCRYPTION_KEY).

# .env
GATEWAY_SHARED_SECRET=<hasil openssl rand -hex 32>

kubectl -n alurkerja create secret generic alurkerja-gateway \
  --from-literal=GATEWAY_SHARED_SECRET="$(openssl rand -hex 32)"

envFrom:
  - secretRef:
      name: alurkerja-gateway

E.3 Verifikasi

E.3.1 — Mode mana yang berjalan. Startup proxy mencetak satu baris tanpa membocorkan nilai secret:

Gateway identity headers: ON - X-User-*/X-Tenant-* diinjeksi + X-Gateway-Token; ...

atau

Gateway identity headers: OFF (GATEWAY_SHARED_SECRET unset) - ...

E.3.2 — Semua replica/service memakai nilai yang sama. Bandingkan hash-nya, jangan nilainya langsung:

docker compose exec proxy sh -c 'printf "%s" "$GATEWAY_SHARED_SECRET" | sha256sum | cut -c1-16'
docker compose exec auth  sh -c 'printf "%s" "$GATEWAY_SHARED_SECRET" | sha256sum | cut -c1-16'

Semua harus identik. Satu yang berbeda menghasilkan kegagalan acak — sebagian request 401, retry sering berhasil — pola yang sangat sulit didiagnosis dari laporan user.

E.3.3 — Header palsu tidak menembus. Kirim identitas palsu lewat proxy, periksa apa yang benar-benar diterima upstream (harus identitas asli pemilik token, bukan nilai yang dikirim di request):

curl -s https://<domain>/api/v1/proxy/<slug>/<path> \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-User-Id: 1" -H "X-User-Is-Admin: true" -H "X-Gateway-Token: tebakan"

E.3.4 — Akses langsung ke port service ditolak. Dari dalam network, lewati proxy sepenuhnya:

docker compose exec proxy sh -c \
  'curl -si http://auth:3001/api/v1/authentication/<path> -H "X-User-Id: 1" -H "X-User-Is-Admin: true"'

Harus 401/403. Kalau 200, service itu belum memasang middleware verifikasi X-Gateway-Token — jangan aktifkan Mode 2 di service tersebut sampai probe ini ditolak.

E.4 Rotasi

X-Gateway-Token dibandingkan nilai persis — tidak ada periode di mana dua nilai berlaku bersamaan secara otomatis. Rotasi wajib urutan ini:

1. Tambahkan secret baru sebagai nilai kedua yang diterima di sisi upstream (service menerima nilai lama atau baru).
2. Rollout ulang seluruh service upstream. Verifikasi semua sudah menerima keduanya.
3. Ganti GATEWAY_SHARED_SECRET di proxy ke nilai baru. Rollout proxy.
4. Verifikasi E.3.1–E.3.3.
5. Hapus nilai lama dari daftar yang diterima upstream. Rollout ulang.

F. Urutan aktivasi yang aman

Membalik urutan ini menyebabkan outage (trafik nyasar sebelum proxy siap) atau lubang auth (flag service menyala sebelum proxy benar-benar satu-satunya jalan masuk).

1. Deploy proxy-service dengan GATEWAY_SHARED_SECRET sudah terisi tapi PROXY_RESOLVE_JWT=false dan PROXY_RESOLVE_JWT_ENFORCE=false. Tunggu healthy.
2. Pindahkan trafik: deploy nginx/default.conf.docker yang mengarahkan /api/v1/* ke proxy:3011.
3. Verifikasi Mode 1 (default, semua flag false): dari log proxy, pastikan tiap /api/v1/<slug>/... benar-benar tercatat lewat proxy DAN responsnya identik dengan sebelum migrasi (login, CRUD dasar tiap service). Ini wajib hijau dulu — kalau ada endpoint 404/502 di sini, ada path yang belum disisir di nginx atau salah map di services.local.json.
4. Baru setelah §3 hijau: PROXY_RESOLVE_JWT=true, PROXY_RESOLVE_JWT_ENFORCE tetap false. Proxy mulai injeksi header, service masih verifikasi sendiri — overlap aman.
5. Baca log sampai sepi. Setiap kegagalan resolve di jalur preset mencetak satu baris preset: identity not resolved for <method> <path> ... — diteruskan tanpa header identitas. Pesan no Authorization header biasanya berarti route itu memang publik di upstream tapi belum ada di public_routes — tambahkan polanya. Pesan invalid token/not a Bearer token berarti client memang mengirim kredensial salah — tidak ada yang perlu diubah di proxy.
6. PROXY_RESOLVE_JWT_ENFORCE=true — hanya setelah langkah 5 sepi minimal satu siklus pemakaian penuh (termasuk akhir pekan/jam sepi; beberapa route publik hanya dipakai lewat link email).
7. RESOLVE_JWT_VIA_PROXY=true satu service per satu, dipantau dari log 401 tak terduga sebelum lanjut ke service berikutnya.

G. Rollback

Rollback per lapis, dari yang paling baru dinyalakan — kebalikan urutan aktivasi di §F:

1. Mode 2 menyala dan bermasalah (401 massal / data user kosong / route publik ikut ditolak): set RESOLVE_JWT_VIA_PROXY=false di service yang bermasalah, restart service itu saja. Tidak perlu sentuh nginx atau proxy.
2. PROXY_RESOLVE_JWT_ENFORCE=true menolak request yang seharusnya publik: kembalikan ke false — pemulihan seketika, restart proxy saja.
3. Topologi nginx→proxy sendiri bermasalah (proxy down, salah map, latensi tambahan tidak diterima): kembalikan nginx/default.conf.docker ke revisi sebelum migrasi (proxy_pass langsung ke tiap service). Service tidak perlu direstart — mereka tidak tahu apakah trafik datang dari nginx langsung atau lewat proxy.
4. Jangan pernah ubah expose: jadi ports: di docker-compose.yml yang di-commit untuk keperluan debug — kalau perlu akses langsung sesaat, pakai docker compose exec <service> sh atau port-forward manual yang tidak masuk git.

H. Troubleshooting

I. Referensi

• Kontrak header & desain: proxy-service/README.md, proxy-service/middleware/identity_headers.go.
• Runbook rotasi & verifikasi lengkap (mencakup jalur Kubernetes): proxy-service/docs/GATEWAY_IDENTITY_HEADERS_RUNBOOK.md.
• Topologi nginx & urutan deploy/rollback sumber halaman ini: release-alurkerja-local/docs/PROXY_TOPOLOGY_RUNBOOK.md.
• Epic & task asal: Collabs #746 — #138963 s.d. #138968.