Belajar Authelia - TOTP (Time-based One-Time Password)

#Pendahuluan

Di episode 8, storage kalian sudah siap menyimpan data permanen — termasuk TOTP secret yang akan menjadi bintang episode ini. Di episode 6, kalian berjanji pada pengguna bahwa layanan sensitif dilindungi two_factor. Saatnya menepati janji itu: mengaktifkan metode kedua yang paling universal, TOTP.

TOTP adalah metode kedua yang tidak membutuhkan perangkat keras khusus, hanya sebuah aplikasi di ponsel — Google Authenticator, Authy, FreeOTP, atau Aegis. Karena itulah TOTP menjadi baseline yang hampir semua pengguna sudah kenal. Di episode ini kalian akan memahami cara kerjanya dari sisi kriptografi, mengonfigurasi perilakunya, menjalankan proses enrollment, dan merancang strategi pemulihan ketika pengguna kehilangan perangkat.

#Cara Kerja TOTP: Kode yang Bernapas Bersama Waktu

TOTP adalah standar RFC 6238, yang merupakan perpanjangan berbasis waktu dari HOTP (RFC 4226). Prinsipnya elegan: kedua pihak — Authelia dan aplikasi authenticator — berbagi satu secret rahasia yang sama. Kode dihasilkan dari secret tersebut digabung dengan counter waktu: nilai epoch saat ini dibagi panjang periode (biasanya 30 detik).

kode = HMAC(secret, floor(unix_time / period)) -> 6 digit

Karena kedua sisi memakai secret dan waktu yang sama, keduanya menghasilkan kode yang identik di jendela waktu yang sama. Ini seperti sebuah gembok kombinasi di mana angka berubah setiap 30 detik, dan baik penjaga maupun kalian memegang jam serta seed yang sama persis.

Konsekuensi pentingnya: jam harus sinkron. Jika perangkat kalian melenceng jauh dari waktu server, kode yang dihasilkan tidak akan cocok. Karena itu jam ponsel dan server Authelia wajib memakai NTP. Persoalan waktu inilah yang membuat TOTP lebih rapuh daripada metode yang tidak bergantung pada sinkronisasi waktu.

#Konfigurasi TOTP

Perilaku TOTP dikendalikan lewat section totp:

totp:
  issuer: "example.com"
  algorithm: "sha1"
  digits: 6
  period: 30
  skew: 1
  secret_size: 32

• issuer: nama yang ditampilkan aplikasi authenticator untuk membedakan entri Authelia dari entri lain.
• algorithm: fungsi hash yang dipakai. Default sha1 dipilih demi kompatibilitas dengan hampir semua aplikasi.
• digits: jumlah digit kode. Default 6; hanya 6 atau 8 yang didukung.
• period: panjang jendela waktu dalam detik. Default 30.
• skew: jumlah jendela di sebelah kiri dan kanan jendela saat ini yang masih dianggap valid.
• secret_size: panjang secret acak yang dihasilkan saat enrollment.

#skew: Ruang Toleransi Waktu

skew adalah jendela toleransi. Dengan nilai default 1, Authelia menerima kode dari tiga jendela waktu: sebelumnya, saat ini, dan sesudahnya. Rumus efektivitasnya period + (period x skew x 2) — dengan periode 30 dan skew 1, total 90 detik validitas. Skew yang besar memang nyaman, tapi memperpanjang masa hidup kode yang bisa disadap penyerang.

#Enrollment: QR Code dan Entri Manual

Alur enrollment TOTP dimulai dari portal Authelia: pengguna login dengan password (faktor pertama), memilih metode TOTP, lalu klik "register device". Authelia akan menampilkan QR code yang berisi URL otpauth — memuat issuer, username, dan secret. Pengguna memindainya dengan aplikasi authenticator:

1. Buka aplikasi authenticator di ponsel.
2. Pilih scan QR code, arahkan ke layar Authelia.
3. Aplikasi menyimpan secret dan mulai menghasilkan kode 6 digit.
4. Masukkan kode pertama di portal untuk memverifikasi; enrollment selesai.

Bagi pengguna yang tidak bisa memindai QR, Authelia juga menyediakan entri manual: secret ditampilkan sebagai teks base32 untuk diketik langsung ke aplikasi. Kedua jalur menghasilkan hal yang sama — secret yang tersimpan di aplikasi dan di storage Authelia.

#Peran Backup: Kenapa Satu Perangkat Tidak Cukup

TOTP secret hidup di satu ponsel. Jika ponsel hilang, rusak, atau ter-reset, pengguna kehilangan satu-satunya cara masuk — kecuali ada jalur pemulihan. Dua strategi yang umum:

• Enroll lebih dari satu perangkat: beberapa aplikasi authenticator, atau satu di ponsel dan satu di perangkat cadangan.
• Simpan salinan secret: saat enrollment, simpan secret base32 di lokasi aman (misalnya vault) sebagai jalur pemulihan manual.

#Enrollment lewat CLI

Tidak selalu harus lewat portal. Authelia menyediakan perintah CLI untuk membuat konfigurasi TOTP bagi pengguna tertentu, bahkan bisa langsung menghasilkan file gambar QR:

authelia storage user totp generate john
authelia storage user totp generate john --path john-qr.png
authelia storage user totp generate john --digits 8 --period 60

• generate john: membuat konfigurasi TOTP baru untuk user john dan menampilkan URI-nya.
• --path john-qr.png: menyimpan QR code ke file agar bisa dikirim ke pengguna.
• --digits 8 --period 60: mengganti parameter jika ingin memakai konfigurasi non-default.

Perintah ini juga berguna untuk restore: jika kalian punya cadangan secret, parameter --secret bisa mengembalikan konfigurasi yang pernah ada.

#Keamanan Secret TOTP

Secret TOTP adalah setara digital dari kunci rumah kalian — siapa pun yang memegangnya bisa memproduksi kode yang sah. Beberapa prinsip yang menjaga secret tetap aman:

• Enkripsi di storage: aktifkan encryption_key di storage MySQL atau PostgreSQL seperti dibahas di episode 8, agar secret tersimpan terenkripsi di database.
• Jangan sebarkan QR code: QR code yang bocor di screenshot atau log chat sama saja dengan membocorkan secret. Suruh pengguna memindai langsung dari layar.
• Ganti secret saat mencurigakan: jika ada indikasi kompromi, buat ulang konfigurasi TOTP pengguna dan minta mereka mendaftar ulang perangkat.
• Sinkronkan jam: perangkat yang jamnya melenceng membuat TOTP gagal berulang kali. Pastikan NTP aktif di ponsel dan server.

Authelia juga memunyai kebijakan disable_reuse_security_policy: secara default, kode yang pernah dipakai tidak bisa dipakai ulang, menutup celah kecil tempat penyerang memanfaatkan kode yang bocor namun belum kedaluwarsa.

#Penutup

Poin kunci episode ini:

• TOTP adalah RFC 6238: HMAC dari secret bersama dan counter waktu, menghasilkan kode 6 digit yang valid selama satu periode.
• Konfigurasi inti: issuer, algorithm, digits, period, dan skew.
• Enrollment berlangsung lewat QR code atau entri manual; secret tersimpan di aplikasi dan di storage Authelia.
• Authelia tidak punya backup codes built-in; gantinya, daftarkan beberapa perangkat atau simpan salinan secret.
• CLI authelia storage user totp generate memungkinkan enrollment dan restore tanpa portal.

TOTP sudah melindungi kalian dari password yang bocor, tapi masih ada satu kelemahan mendasar: kode 6 digit bisa dikelabui oleh situs phishing yang menyalin halaman login. Di episode 10, kalian akan naik kelas dengan WebAuthn/FIDO2 — kredensial yang terikat pada domain asli, sehingga phishing nyaris tidak mempan — dari konsep passkey hingga enrollment YubiKey.