sfsso-frappe
ENID

Cara Kerja

Sebelum menulis kode, pahami tiga bagian utama integrasi ini. Halaman ini menjelaskan alur OAuth2, entry point package, dan batas keamanan yang perlu diterapkan.

Tiga bagian utama

Browser (React/Vue/Next) → Backend aplikasi → Frappe
       user login             simpan secret       provider identity
  1. Browser — tempat user menekan tombol login. Gunakan sso-frappe/browser, atau biarkan backend mengelola redirect sepenuhnya.
  2. Backend aplikasi — satu-satunya tempat clientSecret boleh disimpan. Gunakan sso-frappe/server untuk menukar authorization code dan mengambil profile.
  3. Frappe — identity provider yang menyediakan halaman login, authorization code, dan profile user.

Alur langkah demi langkah

  1. startLogin() membuat state acak dan pasangan PKCE, menyimpannya di sessionStorage, lalu mengarahkan browser ke Frappe.
  2. User login dan memberikan persetujuan di Frappe.
  3. Frappe mengarahkan kembali ke redirectUri dengan code dan state.
  4. handleCallback() membaca URL dan memvalidasi state.
  5. Frontend mengirim { code, codeVerifier } ke backend. Jangan melakukan token exchange di browser.
  6. Backend menjalankan exchangeCode() menggunakan clientSecret dan codeVerifier.
  7. Backend menjalankan getUserProfile() untuk mengambil data user.
  8. Aplikasi mencocokkan atau membuat user lokal. Rekomendasi: identity schema, yaitu users + user_identities.
  9. Aplikasi membuat session cookie atau JWT sendiri.

Entry point

Import Lingkungan Kegunaan
sso-frappe Semua Types, validator config, error classes, validateState.
sso-frappe/server Node.js / Nitro / Bun / Deno Token exchange dan userinfo. Memegang clientSecret.
sso-frappe/browser Browser SPA State, PKCE, redirect, dan callback validation. Tidak memiliki clientSecret.
sso-frappe/next-auth Next.js Konfigurasi provider Auth.js v5.

Aturan keamanan

  • clientSecret hanya boleh berada di backend. Jangan simpan di VITE_*, NEXT_PUBLIC_*, atau bundle browser.
  • redirectUri harus sama persis dengan URL yang didaftarkan di Frappe.
  • state harus divalidasi pada callback untuk mencegah CSRF.
  • PKCE menggunakan S256 dan aktif secara default.
  • id_token Frappe tidak digunakan; profile diambil melalui userinfo endpoint.

Tanggung jawab package dan aplikasi

Tanggung jawab Package Aplikasi kamu
OAuth URL, state, PKCE ✅
Token exchange dan normalisasi profile ✅
User table dan migration ✅
Match/create user ✅
Role mapping dan status user ✅
Session management ✅
Tampilan tombol login ✅

Selanjutnya: Setup Frappe Provider.