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 & Alur Sign Up: Backend memvalidasi code ke Google dan mengotentikasi pengguna (JWT Access Token diberikan). Di sinilah Frontend perlu membedakan antara pengguna lama (Login) dan pengguna baru (Sign Up) melalui data status registrasi.

  • Login: Jika pengguna sudah pernah melengkapi profil, Backend mengembalikan state is_registration_completed: true dan pesan sukses standar. Frontend dapat me-redirect ke /dashboard.
  • Sign Up: Jika ini adalah proses login pertama kali bagi pengguna (mereka baru membuat akun via Google), Backend akan mengembalikan is_registration_completed: false beserta pesan khusus "Please complete your registration". Pada titik ini, Frontend harus me-redirect pengguna ke halaman Complete Registration untuk melengkapi No. HP, Alamat, dsb.

  [!TIP] Keamanan & Session Complete Registration Karena token otentikasi (JWT Access Token) sudah divalidasi dan diberikan oleh backend pada saat callback sukses, pengguna secara teknis telah berstatus "Login". Dengan demikian, ketika mereka mengirimkan form dari halaman Complete Registration ke API penyelesaian pendaftaran (Complete Profile), request tersebut akan sepenuhnya lolos dari middleware Auth.

  Response Sukses (Login Lama - 200 OK)

  {
    "message": "Login Google successfully",
    "data": {
      "redirect": "/dashboard",
      "user": {
        "is_registration_completed": true
      }
    }
  }

  Response Sukses (Pengguna Baru / Sign Up - 200 OK)

  {
    "message": "Please complete your registration",
    "data": {
      "redirect": "/dashboard",
      "user": {
        "is_registration_completed": false
      }
    }
  }

• 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").