Two-Factor Authentication (2FA)
Frog Cloud mendukung otentikasi dua faktor berbasis TOTP (Time-based One-Time Password) menggunakan aplikasi authenticator pihak ketiga (seperti Google Authenticator, Authy, atau Microsoft Authenticator).
1. Mengaktifkan 2FA (Enable)
Untuk mengaktifkan 2FA pada profil pengguna, diperlukan dua langkah (2 endpoint): Generate Secret dan Verify Code.
Tindakan mengaktifkan atau mematikan 2FA dilindungi secara ketat oleh keamanan Sudo Mode. Frontend wajib menyisipkan HTTP Header X-Access-Token pada pemanggilan API ini. Baca dokumentasi Sudo Mode untuk detail cara mendapatkan token tersebut.
Diagram Alur Aktivasi 2FA
Step 1A: Membuat Kode QR (Generate Code)
API ini dipanggil ketika pengguna membuka halaman Pengaturan 2FA.
POST /api/auth/profile/2fa/generate-code
Kondisi & Tindakan:
- Sukses (200 OK): Backend merespons dengan URI Secret dan gambar QR Code (bisa berupa Base64 Image atau URL). Frontend wajib merender QR Code tersebut di layar agar pengguna bisa melakukan scan menggunakan aplikasi Authenticator mereka. Frontend juga harus menampilkan kode Recovery (jika diberikan di langkah ini).
Step 1B: Verifikasi dan Simpan (Enable)
Setelah pengguna men-scan QR, mereka diminta memasukkan 6-digit kode acak dari aplikasi Authenticator mereka untuk memvalidasi bahwa pemasangan berhasil.
POST /api/auth/profile/2fa/enable
Content-Type: application/json
{
"code": "123456"
}
Kondisi & Tindakan:
- Sukses (200 OK): Kode TOTP valid dan 2FA sekarang resmi aktif di akun ini.
- Error (400 Bad Request): Kode salah atau tidak sinkron. Minta pengguna mencoba lagi.
2. Mematikan 2FA (Disable)
Untuk mematikan 2FA, pengguna harus memberikan bukti (mengisi form) berupa kode OTP 6-digit dari aplikasi Authenticator mereka saat ini.
POST /api/auth/profile/2fa/disable
Content-Type: application/json
{
"code": "123456"
}
Kondisi & Tindakan:
- Sukses (200 OK): 2FA berhasil dimatikan.
- Error (400 Bad Request): Kode tidak valid.
3. Login dengan 2FA
Jika 2FA aktif pada suatu akun, respons pada saat pengguna melakukan POST /api/auth/login tidak akan memberikan JWT Access Token. Melainkan, API login akan merespons status 200 OK yang mengindikasikan Redirect ke jalur 2FA (Lihat dokumentasi Alur Login untuk lebih lengkapnya).
Untuk menuntaskan login tersebut, Frontend harus memanggil:
POST /api/auth/2fa/verify-code
Content-Type: application/json
{
"email": "customer@frogcloud.com",
"code": "123456"
}
- Sukses (200 OK): Kode TOTP valid, Frontend mendapatkan Cookies sesi.
- Error (400 Bad Request): Kode salah, login tertunda.
4. Recovery Codes (Kode Pemulihan)
Jika pengguna kehilangan akses ke aplikasi Authenticator mereka (misal: HP hilang atau rusak), mereka dapat menggunakan Recovery Codes (Kode Pemulihan) darurat yang diberikan saat pertama kali mengaktifkan 2FA.
4A. Melihat Daftar Kode Pemulihan
Pengguna dapat melihat sisa daftar kode pemulihan mereka kapan saja di halaman Pengaturan 2FA.
GET /api/auth/profile/2fa/recovery
(Catatan: Endpoint ini mungkin dilindungi oleh Sudo Mode)
4B. Membuat Ulang (Regenerate) Kode
Jika pengguna merasa kode pemulihannya telah bocor atau hampir habis terpakai, mereka dapat membuat sekumpulan kode baru yang akan membatalkan kode-kode lama.
POST /api/auth/profile/2fa/recovery/regenerate
(Catatan: Endpoint ini mungkin dilindungi oleh Sudo Mode)
4C. Login Menggunakan Kode Pemulihan
Saat berada di halaman input 2FA pada alur Login, Frontend sangat disarankan untuk menyediakan tombol opsi alternatif, misalnya: "Tidak bisa mengakses ponsel Anda? Gunakan Kode Pemulihan".
POST /api/auth/2fa/verify-recovery
Content-Type: application/json
{
"email": "customer@frogcloud.com",
"code": "12345-ABCDE"
}
Kondisi & Tindakan:
- Sukses (200 OK): Kode pemulihan valid dan autentikasi berhasil. Kode yang baru saja diinput akan otomatis hangus (hanya bisa dipakai satu kali). Frontend mendapatkan Cookies sesi penuh.
- Error (400 Bad Request): Kode salah, format tidak sesuai, atau kode sudah pernah digunakan sebelumnya.