Lewati ke konten utama

Google Login Flow (SSO)

Dokumentasi ini memandu Frontend (FE) dalam mengimplementasikan integrasi Single Sign-On (SSO) menggunakan Google. Alur ini membutuhkan pengalihan (redirect) bolak-balik antara platform Customer dan sistem Google.

Diagram Alur (Sequence Diagram)​

Berikut adalah urutan proses otorisasi antara Pengguna, Frontend, Backend, dan Google OAuth.

Urutan Integrasi API untuk Frontend​

Step 1: Inisiasi Login Google​

Saat pengguna mengklik tombol "Login dengan Google", Frontend TIDAK langsung mengarahkan pengguna ke situs Google secara hardcode, melainkan harus meminta URL-nya terlebih dahulu dari Backend.

Request
GET /api/auth/google?referral_code=opsional123

Kondisi & Tindakan:

  • Backend akan mengembalikan URL persetujuan OAuth yang sudah dibubuhi state (untuk keamanan CSRF).
  • Setelah menerima response, Frontend harus melakukan navigasi penuh (misalnya via window.location.href) ke URL yang diberikan.
Response Sukses (200 OK)
{
  "message": "Success",
  "data": "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=..."
}

Step 2: Menangani Callback (Dari Google)​

Setelah pengguna menyetujui izin di Google, Google akan me-redirect kembali pengguna ke URL yang telah disetel sebelumnya (di Google Console), biasanya berupa halaman khusus di Frontend (misalnya /auth/google/callback).

URL ini akan membawa query parameters rahasia, misalnya: https://customer.frogcloud.com/auth/google/callback?state=xyz123&code=4/0AX4XfWh...

Frontend bertugas membaca URL parameters tersebut dan mengirimkannya ke Backend untuk ditukarkan dengan Token Sesi (Session Cookies).

Request
POST /api/auth/google/callback
Content-Type: application/json
Request Body
{
  "code": "4/0AX4XfWh... (Didapatkan dari URL parameter)",
  "state": "xyz123 (Didapatkan dari URL parameter)",
  "referral_code": "opsional123"
}

Kondisi & Error Handling (Step 2):

  • Kondisi Sukses: Backend memvalidasi code ke Google dan mencatat/mengotentikasi pengguna. Backend mengembalikan status 200 OK dan menanamkan Cookies sesi ke browser. Frontend wajib menghapus sisa query parameters di URL (clean up URL) lalu me-redirect pengguna masuk ke /dashboard.
    Response Sukses (200 OK)
    {
      "message": "Login Google successfully",
      "data": {
        "redirect": "/dashboard"
      }
    }
  • Error Handling: Jika Backend merespons dengan 400 Bad Request atau status error lainnya (misalnya karena code kadaluarsa atau koneksi API Google gagal), Frontend harus me-redirect kembali pengguna ke halaman Login utama dan menampilkan notifikasi error (misal: "Login dengan Google gagal, silakan coba lagi").