Belajar Backstage - Secrets & External Service Integration

#Pendahuluan

Di episode 13, kalian mengunci akses internal dengan permission framework dan RBAC. Episode 14 ini membalik arah: dari melindungi di dalam menjadi menghubungkan ke luar. Developer portal yang berguna hampir selalu butuh menarik data dari sistem lain — CI/CD, monitoring, ticketing, atau layanan internal. Masalahnya, menghubungkan sistem berarti membagikan kredensial, dan kredensial yang bocor adalah pintu masuk terbesar. Episode ini membahas dua sisi sekaligus: cara meneruskan request ke layanan eksternal lewat proxy backend, dan cara menjaga kredensial tetap aman sepanjang siklus hidupnya.

#Proxy Backend: /api/proxy

Cara paling umum Backstage berkomunikasi dengan layanan eksternal adalah lewat proxy backend. Daripada browser memanggil layanan eksternal secara langsung — yang akan memaparkan kredensial di sisi klien — request dikirim ke endpoint /api/proxy/... milik Backstage, lalu backend meneruskan (forward) request tersebut ke target sebenarnya. Fitur ini diimplementasikan lewat @backstage/plugin-proxy-backend.

proxy:
  endpoints:
    '/github':
      target: 'https://api.github.com'
      changeOrigin: true
      headers:
        Authorization: Bearer ${GITHUB_TOKEN}

Di sisi frontend, kalian cukup memanggil /api/proxy/github, dan Backstage yang menangani autentikasi ke GitHub. Kredensial tidak pernah keluar dari backend. Kata kunci changeOrigin memastikan host header mengikuti target, dan kredensial diambil dari variabel env agar tidak tertulis di repo.

#Kasus Penggunaan Proxy

Pola pentingnya: proxy backend membuat Backstage menjadi satu-satunya pihak yang memegang kredensial, dan tiap endpoint bisa dikunci dengan permission dari episode 13 — sehingga bukan hanya soal jaringan, tetapi juga soal siapa yang boleh memanggil endpoint mana.

Selain memilih target, putuskan juga metode yang dipakai tiap endpoint: read-only untuk sumber yang hanya dibaca, dan jalur khusus untuk operasi yang menulis. Dengan memisahkan endpoint baca dan tulis, kalian bisa memberi scope token yang berbeda untuk masing-masing — dan memperkecil dampak jika salah satu token bocor.

#Backend Service vs API Gateway

Saat memilih target proxy, kalian punya dua pilihan umum:

• Langsung ke backend service — paling sederhana, cocok untuk layanan internal yang butuh latensi rendah dan sudah saling percaya di jaringan yang sama.
• Lewat API gateway — cocok saat target berada di luar jaringan atau butuh lapisan auth, rate limiting, dan observability terpusat.

API gateway menambah satu hop, tetapi memberi keuntungan: kontrol lalu lintas, logging terpusat, dan kemampuan mengganti backend di balik gateway tanpa mengubah konfigurasi proxy Backstage. Untuk integrasi ke sistem milik pihak ketiga, gateway hampir selalu pilihan yang lebih aman.

#Menguji Endpoint Proxy

Sebelum menyambungkan UI, uji dulu endpoint proxy dari terminal agar masalah jaringan dan kredensial terlihat lebih dulu:

curl -s http://localhost:7007/api/proxy/github/rate_limit

Jika respons datang dari GitHub, berarti alur proxy, token, dan routing sudah benar. Jika tidak, periksa urutannya: log backend untuk memastikan request masuk, konfigurasi target untuk memastikan URL benar, lalu token untuk memastikan scope-nya mencukupi. Kebiasaan menguji dari terminal ini menghemat waktu debugging jauh lebih besar daripada yang kalian kira.

Lakukan pengujian ini dari environment yang sama dengan produksi — perbedaan jaringan, proxy keluar, dan firewall adalah penyebab tersembunyi yang baru terlihat saat deploy.

#Keamanan Integrasi: Token Lifecycle

Mengirim token dalam konfigurasi itu mudah; menjaganya tetap aman sepanjang hidupnya yang sulit. Model token yang dianjurkan mengikuti pola access token dan refresh token:

• Short-lived token — berlaku singkat, dalam hitungan menit hingga jam. Jika bocor, jendela eksploitasi kecil. Token inilah yang dipakai untuk tiap request.
• Refresh token — berlaku lebih lama, tetapi hanya untuk menukar access token baru, bukan untuk akses langsung.

Alurnya: saat access token kedaluwarsa, Backstage memakai refresh token untuk mendapat access token baru, dan refresh token itu sendiri berumur panjang — sehingga integrasi tetap berjalan tanpa campur tangan manusia. Semua nilai ini disimpan sebagai secret (lihat episode 9), bukan di app-config.yaml yang ter-commit.

#OIDC Session Handling

Banyak layanan eksternal memakai OIDC untuk autentikasi service-to-service. Backstage menangani ini lewat sesi OIDC: saat backend memanggil layanan OIDC, ia menyimpan session yang berisi token, dan melakukan refresh ketika token hampir habis.

Yang perlu dijaga adalah validitas session: session yang kedaluwarsa harus di-refresh atau dihapus, dan session yang gagal validasi harus dianggap tidak valid, bukan diteruskan begitu saja. Konfigurasi scope dan audience harus sesuai dengan yang disyaratkan target, dan secret session disimpan dengan aman agar tidak bisa dibajak untuk mengeluarkan token atas nama Backstage.

Logging yang baik juga membantu: catat kapan token di-refresh, kapan session dihentikan, dan kapan validasi gagal. Pola kegagalan yang berulang sering kali merupakan tanda awal masalah pada konfigurasi scope atau waktu clock yang tidak sinkron antara Backstage dan provider OIDC.

#Rotasi Credential

Tidak peduli seberapa aman token disimpan, token yang tidak pernah diganti adalah risiko yang menumpuk. Rotasi credential — mengganti kredensial secara berkala — adalah kebiasaan yang wajib untuk integrasi produksi. Ada plugin yang mengotomatiskan rotasi ini untuk beberapa jenis kredensial, misalnya token GitHub App atau service account.

rotate-credentials --provider github-app
verify --provider github-app

Rotasi bisa dijalankan terjadwal, dipicu sebelum token kedaluwarsa, atau manual saat ada indikasi kebocoran. Idealnya proses rotasi tidak menutup layanan: Backstage tetap memakai token lama selama beberapa waktu sampai token baru terverifikasi, lalu beralih secara mulus. Simpan riwayat rotasi di log — kapan kredensial diganti dan oleh siapa — sehingga kalian tahu mana yang masih aktif dan mana yang sudah tidak dipakai.

#Penutup

Episode 14 ini menghubungkan Backstage dengan dunia luar secara aman: meneruskan request lewat proxy backend, memilih antara backend service dan API gateway, mengelola siklus hidup token dengan pola short-lived dan refresh, menangani sesi OIDC, serta merotasi credential secara teratur. Sekarang portal kalian tidak hanya terlindungi di dalam, tetapi juga bisa berinteraksi dengan ekosistem di sekitarnya.

Inti yang harus dibawa pulang:

• Semua request eksternal lewat /api/proxy — jangan pernah memaparkan kredensial ke browser.
• Short-lived token meminimalkan dampak kebocoran — refresh token hanya untuk menukar, bukan akses langsung.
• Gateway memberi lapisan kontrol untuk integrasi lintas jaringan.
• Rotasi credential itu rutin, bukan insiden — jadwalkan sebelum token kedaluwarsa.

Di episode 15 berikutnya, kalian mengamankan deployment itu sendiri: deployment security & hardening — reverse proxy dan TLS, trusted proxies, CSP, secure cookies, hingga prinsip least privilege untuk semua integrasi. Ini saatnya membuat instance Backstage kalian tahan banting di produksi.