Authentication Flow for Frontend - Lumina-Enterprise-Solutions/prism-auth-service GitHub Wiki

🔑 Authentication Flow for Frontend

Dokumen ini menjelaskan alur kerja (flow) lengkap untuk menangani otentikasi di sisi klien (frontend) yang berinteraksi dengan prism-auth-service.

Konsep Dasar: Access Token & Refresh Token

Sistem ini menggunakan dua jenis token (JWT) untuk keamanan:

  1. Access Token (accessToken):

    • Masa Berlaku: Sangat singkat (default 15 menit).
    • Penggunaan: Digunakan di Authorization header untuk setiap permintaan ke endpoint yang terproteksi.
    • Penyimpanan: Sebaiknya disimpan di memori aplikasi (misalnya, state management seperti Redux, Zustand, Pinia, atau context React). Jangan disimpan di localStorage karena rentan terhadap serangan XSS.

  2. Refresh Token (refreshToken):

    • Masa Berlaku: Jauh lebih lama (default 7 hari).
    • Penggunaan: Hanya digunakan untuk meminta accessToken baru ketika yang lama sudah kedaluwarsa.
    • Penyimpanan: Bisa disimpan di localStorage atau lebih aman lagi di cookie HttpOnly.

Diagram Alur Login dan Refresh Token

Berikut adalah visualisasi alur standar saat pengguna login dan sesi mereka tetap aktif.

sequenceDiagram
    participant Client as Frontend
    participant Server as Backend

    rect rgb(230, 240, 255)
        note over Client, Server: 1. Proses Login Awal
        Client->>Server: POST /auth/login (email, password)
        Server->>Client: 200 OK (accessToken, refreshToken)
        note over Client: Simpan kedua token.
    end

    rect rgb(230, 255, 230)
        note over Client, Server: 2. Permintaan API Normal (Menggunakan Access Token)
        Client->>Server: GET /api/data (Header: Authorization: Bearer accessToken)
        Server->>Client: 200 OK (Data yang diminta)
    end

    rect rgb(255, 255, 220)
        note over Client, Server: 3. Access Token Kedaluwarsa
        Client->>Server: GET /api/data (Header: Authorization: Bearer accessTokenLama)
        Server->>Client: 401 Unauthorized (Token expired)
    end

    rect rgb(255, 230, 230)
        note over Client, Server: 4. Proses Refresh Token
        note over Client: Mendeteksi error 401.
        Client->>Server: POST /auth/refresh (refreshToken)
        Server->>Client: 200 OK (accessTokenBaru, refreshTokenBaru)
        note over Client: Ganti token lama dengan yang baru.
    end

    rect rgb(230, 255, 230)
        note over Client, Server: 5. Mengulang Permintaan yang Gagal
        Client->>Server: GET /api/data (Header: Authorization: Bearer accessTokenBaru)
        Server->>Client: 200 OK (Data yang diminta)
    end

Alur-Alur Autentikasi

Alur 1: Registrasi Pengguna Baru

Pengguna membuat akun baru dengan email dan password.

  1. Aksi: Frontend mengirim data registrasi pengguna.
  2. Endpoint: POST /auth/register
  3. Request Body: 
    {
  "email": "[email protected]",
  "password": "passwordKuat123!",
  "first_name": "User",
  "last_name": "Baru"
}
  4. Response Sukses (201 Created): 
    {
  "message": "User created successfully",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
  5. Tindakan Frontend:
    • Tampilkan pesan sukses kepada pengguna.
    • Arahkan pengguna ke halaman login.

Alur 2: Login Standar (Tanpa 2FA)

Pengguna login dan langsung mendapatkan token karena 2FA tidak aktif.

  1. Aksi: Frontend mengirim kredensial login.
  2. Endpoint: POST /auth/login
  3. Request Body: 
    {
  "email": "[email protected]",
  "password": "passwordKuat123!"
}
  4. Response Sukses (200 OK): 
    {
  "is_2fa_required": false,
  "auth_tokens": {
    "access_token": "eyJhbGciOiJI...",
    "refresh_token": "eyJsdfsdf..."
  }
}
  5. Tindakan Frontend:
    • Simpan access_token dan refresh_token.
    • Arahkan pengguna ke halaman utama/dashboard.
    • Mulai gunakan access_token untuk permintaan API yang terproteksi.

Alur 3: Login dengan Two-Factor Authentication (2FA)

Login ini memerlukan dua langkah: verifikasi password, lalu verifikasi kode TOTP.

Langkah 1: Verifikasi Password

  1. Aksi: Frontend mengirim kredensial login.
  2. Endpoint: POST /auth/login
  3. Request Body: 
    {
  "email": "[email protected]",
  "password": "passwordKuat123!"
}
  4. Response Sukses (200 OK): 
    {
  "is_2fa_required": true,
  "auth_tokens": null
}
  5. Tindakan Frontend:
    • Jangan simpan token apa pun.
    • Tampilkan form untuk memasukkan 6 digit kode 2FA.

Langkah 2: Verifikasi Kode 2FA

  1. Aksi: Frontend mengirim email dan kode 2FA yang diinput pengguna.
  2. Endpoint: POST /auth/login/2fa
  3. Request Body: 
    {
  "email": "[email protected]",
  "code": "123456"
}
  4. Response Sukses (200 OK): 
    {
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJsdfsdf..."
}
  5. Tindakan Frontend:
    • Sekarang simpan access_token dan refresh_token.
    • Arahkan pengguna ke halaman utama/dashboard.

Alur 4: Menggunakan Access Token

Setelah login berhasil, setiap permintaan ke endpoint yang terproteksi wajib menyertakan accessToken.

  1. Aksi: Frontend membuat permintaan ke API yang aman.
  2. Header: Authorization
  3. Contoh: 
    GET /api/v1/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...

Alur 5: Memperbarui Access Token (Refresh Flow)

Ini adalah alur paling penting untuk menjaga sesi pengguna tetap aktif.

  1. Kondisi: Permintaan API menggunakan accessToken gagal dengan status 401 Unauthorized.
  2. Tindakan Frontend (Otomatis):
    • Secara transparan (tanpa sepengetahuan pengguna), kirim permintaan untuk token baru.
    • Endpoint: POST /auth/refresh
    • Request Body: 
      {
  "refresh_token": "token-refresh-yang-disimpan-sebelumnya"
}
    • Response Sukses (200 OK): 
      {
  "access_token": "accessTokenBARU...",
  "refresh_token": "refreshTokenBARU..."
}
    • Aksi Lanjutan: a. Perbarui accessToken dan refreshToken yang disimpan dengan yang baru. b. Ulangi (retry) permintaan API yang tadi gagal, kali ini menggunakan accessTokenBARU.
  3. Kondisi Gagal: Jika permintaan ke /auth/refresh itu sendiri gagal (misalnya, refreshToken juga sudah kedaluwarsa dan server merespons 401 Unauthorized):
    • Tindakan Frontend: Hapus semua token dan data sesi dari penyimpanan. Arahkan pengguna kembali ke halaman login. Sesi mereka telah berakhir.

💡 Tips Implementasi: Alur refresh token ini paling baik diimplementasikan menggunakan interceptor pada library HTTP client Anda (seperti Axios atau fetch wrapper). Interceptor akan menangani logika 401 -> refresh -> retry secara otomatis untuk semua permintaan API.

Alur 6: Lupa Password

Pengguna meminta untuk mereset password mereka.

Langkah 1: Meminta Link Reset

  1. Aksi: Pengguna memasukkan email mereka di halaman "Lupa Password".
  2. Endpoint: POST /auth/forgot-password
  3. Request Body: 
    {
  "email": "[email protected]"
}
  4. Response Sukses (200 OK): 
    {
  "message": "If an account with that email exists, a password reset link has been sent."
}
  5. Tindakan Frontend: Tampilkan pesan tersebut kepada pengguna.

Langkah 2: Menggunakan Link Reset

  1. Aksi: Pengguna mengklik link di email mereka dan diarahkan ke halaman reset password di aplikasi Anda. URL-nya akan terlihat seperti: https://aplikasianda.com/reset-password?token=xxxxxxxxxx
  2. Tindakan Frontend:
    • Ambil token dari parameter URL.
    • Tampilkan form untuk memasukkan password baru.

Langkah 3: Mengirim Password Baru

  1. Aksi: Pengguna mengirimkan token dan password baru mereka.
  2. Endpoint: POST /auth/reset-password
  3. Request Body: 
    {
  "token": "token-dari-url-tadi",
  "new_password": "passwordBaruSuperAman123!"
}
  4. Response Sukses (200 OK): 
    {
  "message": "Password has been reset successfully."
}
  5. Tindakan Frontend: Tampilkan pesan sukses dan arahkan pengguna ke halaman login.

Kembali ke Halaman Utama