Panduan Integrasi API TOTP: 2FA Aplikasi Autentikator untuk Aplikasi di AS (2026)

TOTP (Time-based One-Time Password) adalah faktor kedua yang secara diam-diam mendukung sebagian besar autentikasi perusahaan dan konsumen yang sadar keamanan pada tahun 2026. Dihasilkan di sisi klien dari rahasia bersama, berlaku selama 30 detik, gratis per penggunaan, kebal terhadap serangan SMS pumping dan SS7. Kekurangannya: pengguna harus menginstal aplikasi autentikator dan menyelesaikan pendaftaran satu kali. Jika dilakukan dengan baik, TOTP adalah faktor kedua yang tepat untuk pengguna kembali dengan volume tinggi dan peningkatan alami dari OTP SMS. Panduan ini mencakup integrasi API TOTP untuk aplikasi AS pada tahun 2026, standar, pustaka, UX pendaftaran, dan pola produksi.

Apa itu TOTP?

TOTP adalah kode 6-8 digit yang dihasilkan oleh aplikasi autentikator (Google Authenticator, Authy, 1Password, Microsoft Authenticator) dari rahasia bersama yang Anda atur saat pendaftaran, berlaku selama jendela 30 detik. Kode tersebut berputar setiap 30 detik. Baik aplikasi autentikator pengguna maupun server Anda menghitung kode yang sama dari rahasia yang sama, dan verifikasi membandingkannya.

Standarnya adalah RFC 6238, diterbitkan pada tahun 2011 dan stabil sejak saat itu. Implementasi tersedia di setiap bahasa utama. Verifikasi gratis per penggunaan karena tidak ada pesan yang dikirim; kedua belah pihak menghitung kode secara lokal.

TOTP vs SMS OTP: Kapan Menggunakan Masing-masing

DimensiSMS OTPTOTPSetup PenggunaTidak ada (setiap pengguna memiliki SMS)Pendaftaran satu kali dengan pemindaian kode QR (~30 detik)Waktu verifikasi penggunaBaca SMS, masukkan kode (10-30 detik)Buka aplikasi, baca kode, masukkan (10-15 detik)Biaya per penggunaan$0.01-0.04 di AS$0 (tidak ada pesan terkirim)Tingkat keamanan (NIST)"Terbatas""Diizinkan"Rentan SS7/SIM swapYaTidakKetahanan phishingRentan terhadap rekayasa sosialSedikit lebih baik tetapi tidak tahan phishingBekerja offlineTidak (membutuhkan SMS seluler)Ya (kode dihasilkan secara lokal)Pemulihan jika perangkat hilangMudah (masih memiliki nomor telepon)Membutuhkan kode pemulihan yang dihasilkan sebelumnya saat pendaftaranCakupan di AS~99% (universal)~30-40% pengguna konsumen memiliki aplikasi autentikator

Arsitektur yang tepat: OTP SMS saat pendaftaran untuk cakupan universal, dorong pendaftaran TOTP sebagai "peningkatan level" untuk pengguna yang kembali, gunakan TOTP secara default untuk pengguna yang sudah terdaftar. Tutorial 2FA kami mencakup pola berlapis.

Integrasi TOTP: Cara Kerjanya

Tiga langkah dari awal hingga akhir:

Langkah 1: Hasilkan Rahasia saat Pendaftaran

# Python dengan pustaka pyotp
import pyotp
secret = pyotp.random_base32()  # rahasia yang dikodekan base32 32 karakter

# Simpan rahasia dalam catatan pengguna Anda (dienkripsi saat tidak aktif)
user.totp_secret = encrypt(secret)
user.save()



Rahasia adalah kunci bersama. Baik server Anda maupun aplikasi autentikator pengguna membutuhkannya. Simpan dalam keadaan terenkripsi saat tidak aktif di database pengguna Anda.

Langkah 2: Buat URI Penyediaan dan Kode QR

# Hasilkan URI otpauth sesuai RFC 6238
uri = pyotp.totp.TOTP(secret).provisioning_uri(
   name=user.email,
   issuer_name='YourApp'
)
# Format: otpauth://totp/YourApp:user@example.com?secret=ABC...&issuer=YourApp

# Hasilkan kode QR yang dipindai pengguna dengan aplikasi autentikator mereka
import qrcode
qr_image = qrcode.make(uri)
return qr_image  # tampilkan kepada pengguna



Pengguna membuka aplikasi autentikator mereka, mengetuk "pindai kode QR," dan aplikasi membaca URI. Aplikasi mengekstrak rahasia dan mulai menghasilkan kode untuk akun tersebut.

Langkah 3: Verifikasi Kode yang Dimasukkan Pengguna

# Verifikasi kode saat login
def verify_totp(user, user_entered_code):
   secret = decrypt(user.totp_secret)
   totp = pyotp.TOTP(secret)
   # valid_window=1 berarti menerima jendela 30 detik sebelumnya dan berikutnya
   # jika terjadi perbedaan waktu antara server dan perangkat pengguna
   return totp.verify(user_entered_code, valid_window=1)



Server menghitung kode yang diharapkan dari rahasia yang tersimpan dan membandingkannya dengan kode yang dimasukkan pengguna. Verifikasi berhasil jika cocok dalam jendela validitas.

UX Pendaftaran yang Benar-benar Berhasil

Lima pola UX membedakan pendaftaran TOTP yang baik dari yang membuat frustrasi:

Tampilkan kode QR DAN rahasia sebagai teks

‍Pengguna di perangkat seluler tidak dapat dengan mudah memindai kode QR di layar yang sama. Tampilkan keduanya: kode QR untuk pengaturan desktop-ke-seluler, dan rahasia sebagai teks untuk pengguna yang memasukkannya secara manual di aplikasi autentikator mereka.

Verifikasi pendaftaran segera

‍Setelah pengguna memindai kode QR, minta mereka untuk memasukkan kode saat ini dari aplikasi autentikator mereka. Verifikasi sebelum menyimpan rahasia sebagai terdaftar. Ini menangkap kesalahan pengaturan saat pendaftaran, bukan saat login pertama.

Hasilkan kode pemulihan saat pendaftaran

‍Hasilkan 8-10 kode pemulihan sekali pakai yang disimpan pengguna sebelum menyelesaikan pendaftaran. Tanpa kode tersebut, pengguna yang kehilangan perangkat tidak dapat memulihkan akun mereka. Simpan kode pemulihan yang di-hash di database Anda; tandai setiap kode sebagai telah digunakan setelah konsumsi.

Izinkan beberapa aplikasi autentikator

‍Beberapa pengguna menggunakan Google Authenticator di ponsel dan Authy di desktop. Standar TOTP mendukung rahasia yang sama yang terdaftar di beberapa aplikasi secara bersamaan. Alur pendaftaran Anda harus menjelaskan hal ini.

Tunjukkan aplikasi apa yang harus diinstal

‍Sebagian besar pengguna belum pernah melihat TOTP sebelumnya. Tampilkan empat aplikasi paling populer (Google Authenticator, Microsoft Authenticator, Authy, 1Password) dengan tautan unduhan selama pendaftaran.

Referensi Pustaka: TOTP dalam Bahasa Utama

BahasaPustakaInstalNode.js / TypeScriptotplibnpm install otplibPythonpyotppip install pyotpJavajava-otpMaven: com.eatthepath:java-otpPHPotphpcomposer require spomky-labs/otphpGootpgo get github.com/pquerna/otpRubyrotpgem install rotpRusttotp-rsCargo: totp-rs.NETOtp.NETNuGet: Otp.NET

Semuanya mengimplementasikan RFC 6238 dengan cara yang sama. Pilih pustaka untuk bahasa Anda; permukaan API pada dasarnya identik (menghasilkan rahasia, membangun URI, memverifikasi kode).

Kesalahan Implementasi Umum

Menyimpan rahasia dalam bentuk teks biasa

‍Rahasia adalah kunci bersama; siapa pun yang memilikinya dapat menghitung kode pengguna. Enkripsi saat tidak aktif dengan kunci yang dikelola penyedia atau dikelola pelanggan.

Melewatkan langkah kode pemulihan

‍Pengguna yang kehilangan perangkat tanpa kode pemulihan harus melalui verifikasi identitas manual dengan tim dukungan Anda. Kode pemulihan yang dihasilkan saat pendaftaran tidak memerlukan biaya dan menghemat jam waktu dukungan per pengguna yang terkunci.

Tidak ada toleransi perbedaan waktu

‍Jika jam server Anda dan jam perangkat pengguna bergeser lebih dari 30 detik, verifikasi akan gagal. Gunakan valid_window=1 (menerima jendela sebelumnya dan berikutnya) untuk mentoleransi pergeseran kecil. Untuk toleransi yang lebih tinggi, gunakan valid_window=2.

Membiarkan kode yang sama diverifikasi dua kali

‍Setelah kode digunakan, tandai ID verifikasi sebagai sudah terpakai. Jika tidak, penyerang yang mengintip kode tersebut dapat menggunakannya dalam jendela 30 detik.

Tidak membatasi laju percobaan verifikasi

‍Membobol kode 6 digit secara paksa (brute-force) dapat dilakukan tanpa batasan laju. Batasi hingga 5 percobaan per sesi, dengan penundaan eksponensial setelahnya.

Kapan Harus Beralih dari TOTP ke Passkey

TOTP secara signifikan lebih kuat daripada SMS OTP tetapi lebih lemah dari passkey. Alur kematangan yang umum:

1. SMS OTP saat pendaftaran untuk jangkauan universal (semua orang memiliki SMS).
2. Dorong pendaftaran TOTP selama 30-90 hari pertama untuk pengguna yang sadar keamanan.
3. Setelah TOTP menjadi umum di basis pengguna Anda, dorong pendaftaran passkey sebagai peningkatan berikutnya.
4. Untuk tindakan admin berisiko tinggi, wajibkan kunci perangkat keras FIDO2 terlepas dari faktor lain.

FIDO Alliance menerbitkan panduan migrasi passkey multi-tahun. Panduan passkey vs OTP kami mencakup pertimbangan untung-rugi.

Pertanyaan Umum

Mengapa menggunakan TOTP jika passkey lebih baik?‍

TOTP memiliki adopsi pengguna yang lebih luas saat ini daripada passkey (pengguna dengan Google Authenticator atau Authy terinstal adalah umum; pengguna dengan passkey terdaftar di layanan Anda lebih jarang pada tahun 2026). TOTP juga merupakan langkah perantara alami antara SMS OTP dan passkey untuk pengguna yang belum percaya passkey atau perangkatnya tidak mendukungnya. Pola: dukung ketiganya.

Apakah TOTP memerlukan API OTP sama sekali?‍

Bukan untuk verifikasi itu sendiri — kode dihitung di sisi klien dan diverifikasi di sisi server menggunakan pustaka standar. Namun, Anda biasanya menggunakan API OTP bersama TOTP untuk: (a) faktor SMS OTP awal saat pendaftaran (verifikasi pengguna memiliki ponsel sebelum mengizinkan pendaftaran TOTP), (b) pemulihan akun melalui SMS ketika pengguna kehilangan perangkat TOTP mereka, (c) faktor cadangan pada perangkat di mana TOTP tidak tersedia.

Berapa panjang kode TOTP seharusnya?‍

RFC 6238 mendukung 6, 7, atau 8 digit. Enam digit adalah standar universal — setiap aplikasi autentikator menampilkan kode 6 digit, setiap pengguna mengharapkannya. Delapan digit menambah keamanan marjinal dengan biaya UX yang signifikan. Tetap gunakan 6 digit.

Tambahkan TOTP sebagai Lapisan Keamanan Tinggi dalam Tumpukan Anda

TOTP gratis per verifikasi, tahan phishing, dan merupakan faktor kedua yang tepat untuk pengguna kembali yang sadar keamanan. Tambahkan ini di samping integrasi SMS OTP Anda yang sudah ada sebagai opsi "peningkatan" untuk pengguna yang menginginkan keamanan yang lebih kuat. VerifyNow for USA menangani lapisan SMS dengan rute 10DLC dan ID pengirim yang sudah disetujui (mulai mengirim dalam waktu kurang dari 5 menit); pasangkan dengan pustaka TOTP pilihan Anda untuk lapisan keamanan tinggi. Kredit uji coba gratis, tidak perlu kartu kredit.