Panduan Memulai Integrasi (Step-by-Step)

Dokumen ini menjelaskan tahapan integrasi teknis untuk menghubungkan sub-aplikasi (Sub-App) ke dalam portal SuperApps BP Batam yang terintegrasi dengan Goauthentik Single Sign-On (SSO).

---

Langkah 1: Registrasi Provider & Application di Goauthentik

Sebelum melakukan pengkodean, pastikan sub-aplikasi Anda telah terdaftar pada server Goauthentik:

1. Mengajukan permohonan pembuatkan OAuth2/OIDC Provider kepada Administrator BP Batam:
   • Client ID: superapps-subapp-[nama-aplikasi] (contoh: superapps-subapp-iboss)
   • Client Secret: (Disimpan secara aman pada backend sub-aplikasi)
   • Redirect URIs: https://superapps.bpbatam.go.id/auth/callback
   • Allowed Origins: Domain resmi portal SuperApps dan domain sub-aplikasi Anda.
2. Mencatat nilai Issuer URL, Client ID, dan JWKS URI Goauthentik.

---

Langkah 2: Mekanisme Pengiriman dari Parent Portal (superapps-fe & superapps-be)

ARSITEKTUR BACKEND-FOR-FRONTEND (BFF)

superapps-fe tidak berhubungan langsung secara mandiri ke Goauthentik, melainkan melalui perantara Backend Utama SuperApps (superapps-be). superapps-be mengelola transaksi autentikasi OIDC ke Goauthentik, memverifikasi kode otorisasi, dan meneruskan payload autentikasi ke superapps-fe.

Saat pengguna mengakses layanan sub-aplikasi pada portal SuperApps, superapps-fe akan memuat halaman sub-aplikasi di dalam elemen <iframe> dan menyiarkan payload autentikasi melalui fungsi window.postMessage.

Struktur Payload Autentikasi:

{
  "type": "SUPERAPPS_AUTH_SUCCESS",
  "payload": {
    "authCode": "auth_code_xyz123abc...",
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "idToken": "eyJhbGciOiJSUzI1NiIs...",
    "user": {
      "id": "usr-1092",
      "email": "user@bpbatam.go.id",
      "name": "Budi Santoso",
      "company": "PT Batam Jaya",
      "nib": "91200012345678"
    },
    "timestamp": 1785599000000
  }
}

KEBIJAKAN TARGET ORIGIN

Parent Portal HANYA mengirimkan payload autentikasi ke atribut src iframe yang terdaftar. Parent Portal TIDAK PERNAH menggunakan targetOrigin = '*' demi menjaga keamanan data.

---

Langkah 3: Menambahkan Event Listener pada Sub-Aplikasi (Child Iframe)

Setiap sub-aplikasi WAJIB mendaftarkan message event listener pada tingkat global window sesegera mungkin saat komponen atau halaman utama dimuat (mount).

Tahapan Kerja Event Listener:

1. Pendaftaran Event Listener: Mendaftarkan handler menggunakan window.addEventListener('message', handleAuthMessage).
2. Verifikasi event.origin: WAJIB memverifikasi bahwa event.origin berasal dari domain resmi SuperApps Parent (https://superapps.bpbatam.go.id). Apabila origin tidak cocok, pesan harus diabaikan.
3. Validasi Tipe Pesan (event.data.type): Memastikan tipe pesan bernilai SUPERAPPS_AUTH_SUCCESS.
4. Pengiriman Kredensial ke Backend Sub-Aplikasi: Mengirimkan authCode atau accessToken ke backend sub-aplikasi via HTTP API internal (POST /api/auth/sso-login).

---

Langkah 4: Verifikasi Kredensial ke Goauthentik oleh Backend Sub-Aplikasi

Backend sub-aplikasi WAJIB melakukan verifikasi kredensial secara langsung ke Goauthentik sebelum menerbitkan sesi lokal:

1. Penukaran Auth Code / Verifikasi Token:
   • Jika menerima authCode: Backend sub-aplikasi melakukan HTTP POST ke Endpoint Token Goauthentik (/oauth2/token) menggunakan client_id & client_secret milik sub-aplikasi.
   • Jika menerima accessToken: Backend sub-aplikasi melakukan verifikasi ke Endpoint Introspect/JWKS Goauthentik (/oauth2/introspect atau public key JWKS).
2. Konfirmasi Respon Goauthentik:
   • Apabila Goauthentik mengembalikan status HTTP 200 OK dan klaim identitas pengguna yang valid, Backend sub-aplikasi mengonfirmasi bahwa pengguna sah.
3. Penerbitan Sesi Lokal Sub-Aplikasi:
   • Backend sub-aplikasi menerbitkan token/sesi lokalnya sendiri (seperti Bearer JWT atau Session Cookie internal).
   • Frontend sub-aplikasi menyimpan token lokal dan menampilkan antarmuka yang telah terautentikasi.

---

Langkah 5: Penanganan Query Parameter Embedding (embed=true & form=...)

Untuk memastikan antarmuka sub-aplikasi tampil secara bersih (clean form view) dan langsung mengarah ke formulir tujuan saat dimuat di dalam iframe SuperApps, URL iframe akan dilengkapi dengan query parameter:

Contoh URL Iframe dari SuperApps: https://subapp.bpbatam.go.id/layanan?embed=true&form=perizinan-lahan-v2

Ketentuan Implementasi:

1. Parameter embed=true (Menyembunyikan Layout Ekstra):
   • Apabila URL mengandung embed=true, sub-aplikasi wajib menyembunyikan elemen Navbar, Header, Sidebar, dan Footer bawaan.
   • Menampilkan hanya formulir atau konten utama (clean form view) guna menghindari duplikasi elemen navigasi dengan portal SuperApps.
2. Parameter form=specific-form (Navigasi Otomatis ke Form Spesifik):
   • Apabila URL mengandung parameter form=nama-form (contoh: form=alokasi-lahan), sub-aplikasi harus melakukan pengarahan otomatis (auto-route) ke formulir tersebut setelah aplikasi selesai dimuat.

---

Langkah 6: Ringkasan Checklist Implementasi Sub-Aplikasi

• Mendaftarkan event listener window.addEventListener('message', ...) saat aplikasi dimuat.
• Memverifikasi dan memvalidasi event.origin === 'https://superapps.bpbatam.go.id'.
• Memeriksa ketersediaan payload authCode atau accessToken dari event data.
• Meneruskan authCode / accessToken ke Backend Sub-Aplikasi (POST /api/auth/sso-login).
• Backend Sub-Aplikasi melakukan verifikasi / penukaran Auth Code secara langsung ke server Goauthentik.
• Memeriksa query parameter embed=true untuk menyembunyikan Navbar/Sidebar & form=... untuk auto-routing.
• Menerbitkan dan menyimpan sesi login lokal sub-aplikasi setelah verifikasi Goauthentik berhasil.
• Mengirimkan konfirmasi balasan ke Parent Portal (opsional): window.parent.postMessage({ type: 'SUBAPP_AUTH_READY' }, parentOrigin).