Lewati ke konten utama

Login with 2FA & Recovery Flow

Dokumentasi ini adalah kelanjutan logis dari Alur Login Konvensional.

Apabila fitur keamanan tambahan (Two-Factor Authentication / 2FA) aktif pada akun pengguna, proses login POST /api/auth/login tidak akan langsung memberikan Cookies otentikasi penuh pada tahap pertama. Sebagai gantinya, Backend akan menginstruksikan Frontend untuk menunda akses masuk dan memunculkan Layar Verifikasi 2FA.

Pada layar ini, pengguna memiliki dua opsi:

  1. Menginput Kode TOTP (dari aplikasi seperti Google Authenticator).
  2. Menggunakan Kode Pemulihan (Recovery Code) jika mereka kehilangan akses ke aplikasi Authenticator mereka.

Diagram Alur Login 2FA​

Urutan Integrasi API untuk Frontend​

Step 1: Deteksi Kebutuhan 2FA pada saat Login Utama​

Saat memanggil POST /api/auth/login, Frontend harus selalu bersiap untuk mem-parsing data balasan dari Backend.

Jika Backend merespons dengan HTTP Status 200 OK TETAPI struktur datanya mengindikasikan instruksi redirect ke 2FA (misalnya terdapat properti redirect: "2FA" pada data kembalian), maka FE tidak boleh mengalihkan pengguna ke Dashboard.

Alih-alih, FE harus:

  • Menyimpan sementara alamat email pengguna di state.
  • Mengubah tampilan antarmuka menjadi input kode 6-digit TOTP.

Step 2A: Verifikasi Kode TOTP (Alur Normal)​

Pengguna membuka aplikasi Authenticator di perangkat (HP) mereka dan mengetikkan 6-digit angka acak yang tertera di sana.

Request
POST /api/auth/2fa/verify-code
Content-Type: application/json
Request Body
{
  "email": "customer@frogcloud.com",
  "code": "123456"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Kode TOTP valid. Backend resmi mencetak Cookies otentikasi penuh (JWT). FE dapat merampungkan proses dengan me-redirect pengguna ke /dashboard.
  • Error (400 Bad Request): Kode yang dimasukkan salah, kadaluarsa (lewat dari batas waktu), atau salah format. Tampilkan teks peringatan kepada user, contoh: "Kode autentikasi tidak valid".

Step 2B: Verifikasi Menggunakan Kode Pemulihan (Alur Darurat)​

Sebagai UI/UX best practice, FE sebaiknya menyediakan tautan sekunder bertuliskan "Tidak bisa mengakses ponsel Anda? Gunakan Kode Pemulihan" di bawah form 2FA.

Jika diklik, ubah mode input menjadi format panjang (seringkali mengandung huruf dan tanda penghubung, misal 12345-ABCDE).

Request
POST /api/auth/2fa/verify-recovery
Content-Type: application/json
Request Body
{
  "email": "customer@frogcloud.com",
  "recovery_code": "12345-ABCDE"
}

Kondisi & Tindakan:

  • Sukses (200 OK): Kode pemulihan valid. Pengguna lolos autentikasi dan kode cadangan tersebut secara otomatis hangus (tidak bisa dipakai dua kali). Frontend mendapatkan Cookies sesi penuh dan dapat mengalihkan navigasi ke Dashboard.
  • Error (400 Bad Request): Kode salah, format berantakan, atau kode sudah pernah digunakan sebelumnya. Tampilkan peringatan merah agar pengguna mencoba kode cadangan mereka yang lain.