Bayangkan Anda menyimpan uang di bank yang memakai token. Password internet banking ibarat kunci rumah: sekali orang lain menggandakannya, ia bisa masuk kapan saja. Namun, transaksi tetap meminta angka dari token yang berganti setiap 30 detik, dan token itu ada di saku Anda. Prinsip yang sama berlaku untuk 2FA Google Authenticator: walaupun password bocor, penyerang tetap tertahan karena tidak memegang HP Anda.
Pada tutorial ini kita membangun 2FA dengan PHP murni, tanpa Composer dan tanpa library pihak ketiga. Kodenya kami ambil dari fitur yang sudah berjalan di dua sistem produksi kami, yaitu aplikasi billing ISP dan panel admin sebuah situs. Selain itu, setiap baris kode di artikel ini sudah kami uji terhadap test vector resmi RFC 6238 dan terhadap oathtool, lalu kami jalankan alur login lengkapnya lewat HTTP di server uji.
Apa Itu 2FA Google Authenticator dan TOTP?
Google Authenticator, Microsoft Authenticator, dan Authy sama-sama memakai standar TOTP (Time-based One-Time Password) dari RFC 6238. Saat setup, server dan HP berbagi satu secret acak. Setelah itu, keduanya menghitung kode 6 digit sendiri-sendiri dari secret tersebut dan jam saat ini. Akibatnya, aplikasi Authenticator tetap bekerja walaupun HP sedang offline.

Beberapa versi Google Authenticator mengabaikan parameter selain nilai bawaan. Oleh karena itu, kita memakai nilai default berikut agar semua aplikasi Authenticator kompatibel.
| Parameter | Nilai | Keterangan |
|---|---|---|
| Algoritma | SHA1 | HMAC-SHA1, sesuai RFC 4226 (HOTP) |
| Digit | 6 | Kode 000000 sampai 999999 |
| Periode | 30 detik | Satu “langkah waktu” = floor(unix / 30) |
| Secret | 20 byte, Base32 | 160 bit acak, tampil 32 karakter A–Z dan 2–7 |
Struktur Proyek dan Tabel Database
Proyek contoh ini sengaja kecil. Folder public menjadi document root, sedangkan config.php dan kode inti berada di luar jangkauan browser.
app/
├── config.php # DSN database + key enkripsi (di luar public)
├── bootstrap.php # session, PDO, CSRF, helper
├── schema.sql
├── src/
│ ├── Totp.php # algoritma TOTP
│ ├── crypto.php # enkripsi secret
│ └── twofa.php # setup, aktivasi, cek login
└── public/ # document root web server
├── login.php
├── verify.php
├── setup.php
└── assets/vendor/qrcodejs/qrcode.min.js
Selanjutnya, kita membuat tiga tabel. Tabel users menyimpan hash password, user_2fa menyimpan secret terenkripsi, dan user_2fa_backup menyimpan kode cadangan.
CREATE TABLE users (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(190) NOT NULL UNIQUE,
password_hash VARCHAR(255) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- Satu baris per user: secret terenkripsi dan status aktif
CREATE TABLE user_2fa (
user_id INT UNSIGNED NOT NULL PRIMARY KEY,
secret_enc VARCHAR(255) NOT NULL, -- secret Base32 terenkripsi
enabled_at DATETIME NULL DEFAULT NULL, -- NULL = setup belum selesai
last_step BIGINT UNSIGNED NOT NULL DEFAULT 0, -- anti pakai-ulang kode
CONSTRAINT fk_2fa_user FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE user_2fa_backup (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
user_id INT UNSIGNED NOT NULL,
code_hash VARCHAR(255) NOT NULL, -- password_hash() kode cadangan
used_at DATETIME NULL DEFAULT NULL,
KEY idx_user (user_id),
CONSTRAINT fk_backup_user FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
Kolom enabled_at bernilai NULL selama user belum menyelesaikan setup. Kolom last_step mencatat langkah waktu terakhir yang lolos, sehingga server menolak kode yang sama pada percobaan kedua. Sementara itu, kode cadangan menempati baris sendiri dengan used_at, jadi penandaan “sudah terpakai” cukup dengan satu UPDATE bersyarat.
Membuat Class TOTP dari Nol
Semua logika TOTP ada di satu file src/Totp.php. Kita membahasnya dalam empat bagian. Simpan keempat bagian ini berurutan dalam satu file.
Bagian 1: Secret Acak dan Base32
<?php
// src/Totp.php — TOTP (RFC 6238) tanpa library, cocok dengan Google Authenticator
declare(strict_types=1);
final class Totp
{
private const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
public function __construct(
private int $period = 30,
private int $digits = 6,
private string $algo = 'sha1'
) {}
// Secret acak untuk user baru, dikodekan Base32
public static function generateSecret(int $bytes = 20): string
{
return self::base32Encode(random_bytes($bytes)); // 20 byte = 160 bit
}
public static function base32Encode(string $data): string
{
$bits = '';
foreach (str_split($data) as $c) {
$bits .= str_pad(decbin(ord($c)), 8, '0', STR_PAD_LEFT);
}
$out = '';
foreach (str_split($bits, 5) as $chunk) {
$out .= self::B32[bindec(str_pad($chunk, 5, '0'))];
}
return $out;
}
// Kebalikan base32Encode(): teks Base32 menjadi byte mentah
public static function base32Decode(string $b32): string
{
$b32 = strtoupper(preg_replace('/[^A-Za-z2-7]/', '', $b32));
$bits = '';
foreach (str_split($b32) as $c) {
$bits .= str_pad(decbin(strpos(self::B32, $c)), 5, '0', STR_PAD_LEFT);
}
$out = '';
foreach (str_split($bits, 8) as $byte) {
if (strlen($byte) === 8) {
$out .= chr(bindec($byte));
}
}
return $out;
}
Pertama, generateSecret() mengambil 20 byte dari random_bytes(), sumber acak kriptografis bawaan PHP. Jangan pernah memakai rand() atau uniqid() untuk secret. Kemudian, Base32 mengubah byte mentah menjadi huruf A–Z dan angka 2–7 yang mudah user ketik manual. Caranya, fungsi encode memecah deretan bit menjadi potongan 5 bit, lalu tiap potongan menjadi satu karakter. Sebaliknya, fungsi decode membuang spasi dan tanda =, sehingga secret yang user salin dengan spasi tetap terbaca.
Bagian 2: Menghitung Kode 6 Digit
public function code(string $secret, int $step): string
{
$hash = hash_hmac($this->algo, pack('J', $step), self::base32Decode($secret), true);
$offset = ord($hash[strlen($hash) - 1]) & 0x0F;
$num = ((ord($hash[$offset]) & 0x7F) << 24)
| (ord($hash[$offset + 1]) << 16)
| (ord($hash[$offset + 2]) << 8)
| ord($hash[$offset + 3]);
$code = $num % (10 ** $this->digits);
return str_pad((string) $code, $this->digits, '0', STR_PAD_LEFT);
}
Inilah inti RFC 6238. Pertama, pack('J', $step) mengubah langkah waktu menjadi 8 byte big-endian, persis seperti permintaan standar. Kemudian, hash_hmac() menghasilkan 20 byte HMAC-SHA1. Setelah itu, dynamic truncation memakai 4 bit terbawah byte terakhir sebagai offset, mengambil 4 byte dari posisi tersebut, dan membuang bit tanda dengan & 0x7F. Terakhir, operasi modulo memotong angka menjadi 6 digit, lalu str_pad() menambah nol di depan, misalnya 7081 menjadi 007081.
Bagian 3: Verifikasi dengan Toleransi Waktu
/** Langkah yang cocok (int) atau false. Langkah <= $lastStep ditolak. */
public function verify(string $secret, string $code, int $lastStep = 0, int $window = 1, ?int $now = null): int|false
{
$code = preg_replace('/\D/', '', $code);
if (strlen($code) !== $this->digits) {
return false;
}
$current = intdiv($now ?? time(), $this->period);
for ($i = -$window; $i <= $window; $i++) {
$step = $current + $i;
if ($step <= $lastStep) {
continue; // kode lama atau sudah pernah dipakai
}
if (hash_equals($this->code($secret, $step), $code)) {
return $step;
}
}
return false;
}
Jam HP jarang tepat sama dengan jam server. Karena itu, verify() memeriksa langkah sebelumnya, langkah sekarang, dan langkah berikutnya ($window = 1), atau sekitar ±30 detik. Selain itu, parameter $lastStep menolak langkah yang sudah pernah lolos, sehingga penyerang tidak bisa memakai ulang kode yang ia intip. Fungsi ini juga membandingkan kode dengan hash_equals() agar waktu respons tidak membocorkan digit yang benar.
Bagian 4: URI otpauth untuk QR
public function uri(string $secret, string $account, string $issuer): string
{
return 'otpauth://totp/' . rawurlencode($issuer) . ':' . rawurlencode($account)
. '?secret=' . $secret
. '&issuer=' . rawurlencode($issuer)
. '&algorithm=' . strtoupper($this->algo)
. '&digits=' . $this->digits
. '&period=' . $this->period;
}
}
Aplikasi Authenticator membaca QR berisi URI otpauth://totp/Issuer:akun?secret=.... Parameter issuer menentukan nama yang tampil di aplikasi, misalnya “Contoh App”. Kita menyandikan nama dan email dengan rawurlencode(), sehingga spasi menjadi %20 dan @ menjadi %40.
Uji dengan Test Vector RFC 6238
Algoritma kriptografi buatan sendiri wajib lolos uji resmi sebelum menyentuh login sungguhan. Untungnya, Appendix B RFC 6238 menyediakan tabel jawaban. Secret uji untuk SHA1 adalah teks ASCII 12345678901234567890, sedangkan SHA256 dan SHA512 memakai versi yang lebih panjang. Skrip berikut menghitung 18 kode 8 digit dan membandingkannya dengan tabel tersebut.
<?php
// test-vector.php — cocokkan Totp dengan Appendix B RFC 6238 (8 digit)
require __DIR__.'/src/Totp.php';
$seeds = [
'sha1' => '12345678901234567890',
'sha256' => '12345678901234567890123456789012',
'sha512' => '1234567890123456789012345678901234567890123456789012345678901234',
];
$expected = [
59 => ['sha1' => '94287082', 'sha256' => '46119246', 'sha512' => '90693936'],
1111111109 => ['sha1' => '07081804', 'sha256' => '68084774', 'sha512' => '25091201'],
1111111111 => ['sha1' => '14050471', 'sha256' => '67062674', 'sha512' => '99943326'],
1234567890 => ['sha1' => '89005924', 'sha256' => '91819424', 'sha512' => '93441116'],
2000000000 => ['sha1' => '69279037', 'sha256' => '90698825', 'sha512' => '38618901'],
20000000000 => ['sha1' => '65353130', 'sha256' => '77737706', 'sha512' => '47863826'],
];
$fail = 0;
foreach ($expected as $time => $row) {
foreach ($row as $algo => $want) {
$secret = Totp::base32Encode($seeds[$algo]);
$got = (new Totp(30, 8, $algo))->code($secret, intdiv($time, 30));
$ok = $got === $want;
$fail += $ok ? 0 : 1;
printf("%-12d %-7s %s %s\n", $time, $algo, $got, $ok ? 'OK' : "GAGAL (harus $want)");
}
}
echo 'secret SHA1 Base32: ', Totp::base32Encode($seeds['sha1']), "\n";
echo $fail === 0 ? "Semua 18 vektor cocok\n" : "$fail vektor gagal\n";
Jalankan dengan php test-vector.php. Jika satu baris saja menampilkan GAGAL, berarti ada kesalahan di Base32, pack(), atau offset truncation. Perhatikan juga bahwa kita menguji 8 digit, karena RFC menulis jawabannya dalam 8 digit. Kode 6 digit hanyalah 6 angka terakhirnya.
Bandingkan dengan oathtool
Sebagai pembanding kedua, kita memakai oathtool, alat TOTP dari proyek OATH Toolkit. Pasang dengan sudo apt install oathtool, lalu jalankan skrip ini dari folder app.
#!/bin/bash # compare.sh — bandingkan kode Totp.php dengan oathtool untuk secret acak cd "$(dirname "$0")" SECRET=$(php -r 'require "src/Totp.php"; echo Totp::generateSecret();') echo "secret acak: $SECRET" for t in 59 1111111109 1234567890 2000000000 $(date +%s); do a=$(php -r 'require "src/Totp.php"; echo (new Totp())->code($argv[1], intdiv((int)$argv[2], 30));' "$SECRET" "$t") b=$(oathtool --totp -b -N "@$t" "$SECRET") [ "$a" = "$b" ] && hasil=SAMA || hasil=BEDA printf "%-11s php=%s oathtool=%s %s\n" "$t" "$a" "$b" "$hasil" done
Skrip ini membuat secret acak baru, lalu meminta PHP dan oathtool menghitung kode untuk lima waktu yang sama, termasuk waktu sekarang. Hasilnya harus SAMA di semua baris.

Uji Toleransi Waktu dan Pemakaian Ulang
<?php
// window-test.php — uji toleransi waktu dan penolakan kode yang dipakai ulang
require __DIR__.'/src/Totp.php';
$totp = new Totp();
$secret = Totp::generateSecret();
$now = time();
$step = intdiv($now, 30);
foreach ([-90, -60, -30, 0, 30, 60] as $geser) {
$kode = $totp->code($secret, intdiv($now + $geser, 30)); // jam HP meleset $geser detik
$hasil = $totp->verify($secret, $kode, 0, 1, $now);
printf("HP meleset %+4d detik -> %s\n", $geser, $hasil === false ? 'DITOLAK' : 'diterima');
}
$kode = $totp->code($secret, $step);
$first = $totp->verify($secret, $kode, 0, 1, $now); // login pertama
$again = $totp->verify($secret, $kode, (int) $first, 1, $now); // kode sama, last_step sudah naik
echo 'pakai pertama: ', $first === false ? 'DITOLAK' : 'diterima', "\n";
echo 'pakai ulang : ', $again === false ? 'DITOLAK' : 'diterima', "\n";
Skrip ini meniru HP yang jamnya meleset. Hasil di laptop kami: verify() menerima selisih −30, 0, dan +30 detik, tetapi menolak −60, −90, dan +60 detik. Selain itu, fungsi langsung menolak kode yang sama pada pemakaian kedua karena last_step sudah naik.
QR Code Lokal, Bukan Layanan Pihak Ketiga
Banyak tutorial lama membuat QR dengan memanggil layanan seperti Google Charts atau api.qrserver.com. Masalahnya, URI otpauth berisi secret. Jadi, setiap kali halaman setup terbuka, secret user ikut terkirim ke server orang lain dan tercatat di log mereka. Selain itu, Google sudah lama menghentikan dukungan Image Charts, jadi halaman yang bergantung padanya bisa rusak sewaktu-waktu.
| Cara membuat QR | Secret keluar dari server? | Catatan |
|---|---|---|
| Google Charts / api.qrserver.com | Ya, lewat URL | Bocor ke pihak ketiga dan bergantung layanan luar |
| CDN publik untuk library JS | Tidak, tetapi JS dari luar | Jika CDN berubah, skrip asing membaca secret |
| qrcode.js self-host | Tidak | Browser menggambar QR dari file di server sendiri |
Kami memakai qrcode.min.js (qrcodejs, lisensi MIT) yang kami simpan di public/assets/vendor/qrcodejs/. Dengan begitu, browser menggambar QR langsung dari URI tanpa memanggil server lain.
Enkripsi Secret di Database
Secret TOTP setara dengan password kedua. Jika database bocor dan secret tersimpan polos, penyerang bisa membuat kode 6 digit untuk semua user. Berbeda dengan password, kita tidak bisa menyimpan secret sebagai hash, karena server harus membaca nilai aslinya untuk menghitung kode. Solusinya adalah enkripsi simetris dengan key yang tersimpan di luar database.
<?php
// src/crypto.php — enkripsi secret TOTP sebelum masuk database (libsodium)
declare(strict_types=1);
function secret_encrypt(string $plain, string $key): string
{
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); // 24 byte, baru setiap kali
return base64_encode($nonce . sodium_crypto_secretbox($plain, $nonce, $key));
}
function secret_decrypt(string $stored, string $key): ?string
{
$raw = base64_decode($stored, true);
$min = SODIUM_CRYPTO_SECRETBOX_NONCEBYTES + SODIUM_CRYPTO_SECRETBOX_MACBYTES;
if ($raw === false || strlen($raw) < $min) {
return null;
}
$nonce = substr($raw, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$box = substr($raw, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$plain = sodium_crypto_secretbox_open($box, $nonce, $key);
return $plain === false ? null : $plain; // false = key salah atau data diubah
}
Fungsi ini memakai libsodium yang sudah ada di PHP 7.2 ke atas. sodium_crypto_secretbox() mengenkripsi sekaligus menambahkan MAC. Akibatnya, ciphertext yang berubah sedikit saja atau key yang salah akan membuat secret_decrypt() mengembalikan null, bukan secret ngawur. Setiap enkripsi juga memakai nonce acak baru, jadi dua user dengan secret sama pun menghasilkan ciphertext berbeda.
Membuat Key dan File Konfigurasi
php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'
Perintah ini mencetak key 32 byte dalam Base64. Salin hasilnya ke config.php, file yang berada di luar folder public.
<?php
return [
'dsn' => 'mysql:host=127.0.0.1;dbname=app2fa;charset=utf8mb4',
'db_user' => 'app2fa',
'db_pass' => 'ganti-password-database',
'totp_key' => base64_decode('ISI-DENGAN-KEY-BASE64-ANDA'),
'issuer' => 'Contoh App',
];
Simpan key ini di backup yang aman, terpisah dari dump database. Jika key hilang, semua secret tidak bisa terbaca lagi dan setiap user harus memasang ulang 2FA.
Bootstrap: Session, PDO, dan CSRF
Setiap halaman memuat bootstrap.php. File ini menyiapkan session yang aman, koneksi PDO, dan helper kecil. Kita membaginya menjadi dua bagian, dan keduanya tersimpan berurutan dalam satu file.
<?php
// bootstrap.php — dimuat di awal setiap halaman
declare(strict_types=1);
session_set_cookie_params([
'httponly' => true,
'secure' => !empty($_SERVER['HTTPS']),
'samesite' => 'Lax',
]);
session_start();
header('Cache-Control: no-store'); // halaman setup memuat secret, jangan sampai tersimpan di cache
$config = require __DIR__.'/config.php'; // di luar folder public
require __DIR__.'/src/Totp.php';
require __DIR__.'/src/crypto.php';
require __DIR__.'/src/twofa.php';
function db(): PDO
{
static $pdo = null;
global $config;
return $pdo ??= new PDO($config['dsn'], $config['db_user'], $config['db_pass'], [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::ATTR_EMULATE_PREPARES => false,
]);
}
Cookie session memakai httponly dan samesite, sedangkan header Cache-Control: no-store mencegah browser atau proxy menyimpan halaman yang memuat secret. Kemudian, PDO memakai ATTR_EMULATE_PREPARES = false agar prepared statement benar-benar berjalan di sisi MySQL.
function h(string $s): string
{
return htmlspecialchars($s, ENT_QUOTES, 'UTF-8');
}
// Token CSRF disimpan di session, dicek di setiap POST
function csrf_field(): string
{
$_SESSION['csrf'] ??= bin2hex(random_bytes(32));
return '<input type="hidden" name="csrf" value="' . $_SESSION['csrf'] . '">';
}
function csrf_check(): void
{
if (!hash_equals($_SESSION['csrf'] ?? '', (string) ($_POST['csrf'] ?? ''))) {
http_response_code(400);
exit('Token form tidak valid, muat ulang halaman.');
}
}
function redirect(string $to): never
{
header('Location: ' . $to);
exit;
}
Helper h() meng-escape output HTML. Lalu, csrf_field() dan csrf_check() menjaga form dari CSRF, sedangkan redirect() menghentikan skrip setelah mengirim header Location.
Fungsi 2FA: Setup, Aktivasi, dan Kode Cadangan
File src/twofa.php berisi semua query 2FA. Kita membahasnya dalam tiga bagian yang tersimpan berurutan.
Membaca Baris dan Memulai Setup
<?php
// src/twofa.php — fungsi 2FA: setup, aktivasi, kode cadangan, cek login
declare(strict_types=1);
function twofa_row(int $uid): ?array
{
$st = db()->prepare('SELECT * FROM user_2fa WHERE user_id = ?');
$st->execute([$uid]);
return $st->fetch() ?: null;
}
// 2FA dianggap aktif setelah kode pertama terverifikasi
function twofa_enabled(int $uid): bool
{
$row = twofa_row($uid);
return $row !== null && $row['enabled_at'] !== null;
}
function twofa_secret(array $row): string
{
global $config;
$secret = secret_decrypt($row['secret_enc'], $config['totp_key']);
if ($secret === null) {
throw new RuntimeException('Secret 2FA gagal didekripsi, periksa totp_key.');
}
return $secret;
}
/** Buat secret baru yang belum aktif. Mengembalikan secret Base32. */
function twofa_start_setup(int $uid): string
{
global $config;
$secret = Totp::generateSecret();
$enc = secret_encrypt($secret, $config['totp_key']);
db()->prepare('DELETE FROM user_2fa WHERE user_id = ? AND enabled_at IS NULL')->execute([$uid]);
db()->prepare('INSERT INTO user_2fa (user_id, secret_enc) VALUES (?, ?)')->execute([$uid, $enc]);
return $secret;
}
twofa_start_setup() membuat secret baru, mengenkripsinya, lalu menyimpannya dengan enabled_at NULL. Query DELETE di awal hanya menghapus setup yang belum selesai, sehingga 2FA yang sudah aktif tidak tertimpa diam-diam. Sementara itu, twofa_secret() melempar exception bila dekripsi gagal, karena kondisi itu hampir selalu berarti key berubah.
Aktivasi dan Kode Cadangan
/** Aktifkan 2FA dengan kode pertama. Mengembalikan 10 kode cadangan, atau null. */
function twofa_enable(int $uid, string $code): ?array
{
$row = twofa_row($uid);
if ($row === null || $row['enabled_at'] !== null) {
return null;
}
$step = (new Totp())->verify(twofa_secret($row), $code);
if ($step === false) {
return null;
}
$st = db()->prepare('UPDATE user_2fa SET enabled_at = NOW(), last_step = ? WHERE user_id = ? AND enabled_at IS NULL');
$st->execute([$step, $uid]);
return $st->rowCount() === 1 ? twofa_new_backup_codes($uid) : null;
}
function twofa_new_backup_codes(int $uid): array
{
db()->prepare('DELETE FROM user_2fa_backup WHERE user_id = ?')->execute([$uid]);
$ins = db()->prepare('INSERT INTO user_2fa_backup (user_id, code_hash) VALUES (?, ?)');
$plain = [];
for ($i = 0; $i < 10; $i++) {
$code = strtoupper(bin2hex(random_bytes(2)) . '-' . bin2hex(random_bytes(2))); // mis. 9F3A-07C2
$plain[] = $code;
$ins->execute([$uid, password_hash($code, PASSWORD_DEFAULT)]);
}
return $plain; // tampilkan SEKALI ke user, jangan disimpan polos
}
User baru resmi memakai 2FA setelah memasukkan kode pertama yang benar. Langkah ini membuktikan bahwa QR sudah terbaca dan jam HP cocok. Kemudian, fungsi membuat 10 kode cadangan berformat 9F3A-07C2. Kita menyimpan kode cadangan dengan password_hash(), sama seperti password, karena server cukup mencocokkan kode tanpa perlu membaca nilai aslinya.
Memeriksa Kode Saat Login
/** Cek kode saat login. Mengembalikan 'totp', 'backup', atau false. */
function twofa_check(int $uid, string $input): string|false
{
$row = twofa_row($uid);
if ($row === null || $row['enabled_at'] === null) {
return false;
}
$code = strtoupper(preg_replace('/\s+/', '', $input));
if (preg_match('/^\d{6}$/', $code)) {
$step = (new Totp())->verify(twofa_secret($row), $code, (int) $row['last_step']);
if ($step === false) {
return false;
}
// bersyarat pada last_step lama: dua request kembar, hanya satu yang lolos
$st = db()->prepare('UPDATE user_2fa SET last_step = ? WHERE user_id = ? AND last_step = ?');
$st->execute([$step, $uid, $row['last_step']]);
return $st->rowCount() === 1 ? 'totp' : false;
}
$st = db()->prepare('SELECT id, code_hash FROM user_2fa_backup WHERE user_id = ? AND used_at IS NULL');
$st->execute([$uid]);
foreach ($st->fetchAll() as $b) {
if (password_verify($code, $b['code_hash'])) {
$up = db()->prepare('UPDATE user_2fa_backup SET used_at = NOW() WHERE id = ? AND used_at IS NULL');
$up->execute([$b['id']]);
return $up->rowCount() === 1 ? 'backup' : false;
}
}
return false;
}
function twofa_backup_left(int $uid): int
{
$st = db()->prepare('SELECT COUNT(*) FROM user_2fa_backup WHERE user_id = ? AND used_at IS NULL');
$st->execute([$uid]);
return (int) $st->fetchColumn();
}
Fungsi twofa_check() membedakan dua jenis input. Enam digit angka berarti kode Authenticator, sedangkan format lain kita perlakukan sebagai kode cadangan. Bagian terpenting ada pada UPDATE bersyarat AND last_step = ?. Jika dua request membawa kode yang sama hampir bersamaan, hanya satu yang berhasil mengubah baris, dan yang lain gagal. Pola yang sama berlaku untuk kode cadangan dengan syarat used_at IS NULL.
Halaman Setup dengan QR Lokal
Hanya user yang sudah login yang bisa membuka halaman setup.php. Bagian PHP di atas menangani logika, sedangkan bagian HTML di bawahnya menampilkan QR.
<?php
// public/setup.php — pasang 2FA (user harus sudah login)
require __DIR__.'/../bootstrap.php';
$uid = $_SESSION['uid'] ?? null;
if (!$uid) {
redirect('login.php');
}
$st = db()->prepare('SELECT email FROM users WHERE id = ?');
$st->execute([$uid]);
$email = (string) $st->fetchColumn();
$error = '';
$backup = null;
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
csrf_check();
$backup = twofa_enable($uid, (string) ($_POST['code'] ?? ''));
if ($backup === null) {
$error = 'Kode tidak cocok. Pastikan jam HP otomatis, lalu coba lagi.';
}
}
$row = twofa_row($uid);
$enabled = $row !== null && $row['enabled_at'] !== null;
$secret = $enabled ? null : ($row ? twofa_secret($row) : twofa_start_setup($uid));
$uri = $secret ? (new Totp())->uri($secret, $email, $config['issuer']) : '';
?>
Saat halaman pertama kali terbuka, twofa_start_setup() membuat secret. Jika user memuat ulang halaman, kode membaca secret yang sama dari database, sehingga QR tidak berubah setiap refresh.
<!doctype html>
<html lang="id"><meta charset="utf-8"><title>Keamanan Akun</title>
<?php if ($backup): ?>
<h2>2FA aktif. Simpan 10 kode cadangan ini (hanya tampil sekali)</h2>
<pre><?= h(implode("\n", $backup)) ?></pre>
<?php elseif ($enabled): ?>
<p>Verifikasi 2 langkah sudah aktif untuk <?= h($email) ?>.</p>
<?php else: ?>
<p>Pindai QR ini dengan Google Authenticator:</p>
<div id="qr"></div>
<p>Atau ketik manual: <code><?= h(trim(chunk_split($secret, 4, ' '))) ?></code></p>
<form method="post" autocomplete="off">
<?= csrf_field() ?>
<p><?= h($error) ?></p>
<input name="code" inputmode="numeric" maxlength="6" placeholder="123456" required>
<button>Aktifkan</button>
</form>
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-wp-preserve="%3Cscript%20src%3D%22assets%2Fvendor%2Fqrcodejs%2Fqrcode.min.js%22%3E%3C%2Fscript%3E" data-mce-resize="false" data-mce-placeholder="1" class="mce-object mce-object-script" width="20" height="20" alt="<script>" />
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-wp-preserve="%3Cscript%3E%0A%0A%20%20%20%20new%20QRCode(document.getElementById('qr')%2C%20%7B%0A%20%20%20%20%20%20text%3A%20%3C%3F%3D%20json_encode(%24uri%2C%20JSON_HEX_TAG%20%7C%20JSON_HEX_AMP%20%7C%20JSON_UNESCAPED_SLASHES)%20%3F%3E%2C%0A%20%20%20%20%20%20width%3A%20200%2C%20height%3A%20200%2C%20correctLevel%3A%20QRCode.CorrectLevel.M%0A%20%20%20%20%7D)%3B%0A%20%20%3C%2Fscript%3E" data-mce-resize="false" data-mce-placeholder="1" class="mce-object mce-object-script" width="20" height="20" alt="<script>" />
<?php endif; ?>
</html>
QR muncul dari qrcode.min.js lokal. Perhatikan opsi JSON_HEX_TAG dan JSON_HEX_AMP pada json_encode(). Opsi ini membuat string aman di dalam tag script, karena tanda < dan & berubah menjadi escape Unicode. Selain itu, kode cadangan hanya tampil sekali, tepat setelah aktivasi berhasil.

Alur Login dengan Status pending_2fa
Kesalahan paling berbahaya dalam implementasi 2FA adalah membuat session login sebelum kode 2FA lolos. Karena itu, kita memakai status perantara pending_2fa. Password yang benar hanya menghasilkan “tiket” sementara, belum akses ke aplikasi.

Langkah 1: login.php
<?php
// public/login.php — langkah 1: email + password
require __DIR__.'/../bootstrap.php';
$error = '';
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
csrf_check();
$st = db()->prepare('SELECT id, password_hash FROM users WHERE email = ?');
$st->execute([trim((string) ($_POST['email'] ?? ''))]);
$user = $st->fetch();
if ($user && password_verify((string) ($_POST['password'] ?? ''), $user['password_hash'])) {
session_regenerate_id(true);
$uid = (int) $user['id'];
if (twofa_enabled($uid)) {
// password benar, tapi BELUM login: tunggu kode 2FA maksimal 5 menit
$_SESSION['pending_2fa'] = ['uid' => $uid, 'exp' => time() + 300, 'tries' => 0];
redirect('verify.php');
}
$_SESSION['uid'] = $uid;
redirect('setup.php');
}
$error = 'Email atau password salah.';
}
?>
<!doctype html>
<html lang="id"><meta charset="utf-8"><title>Login</title>
<form method="post">
<?= csrf_field() ?>
<p><?= h($error) ?></p>
<input type="email" name="email" placeholder="Email" required>
<input type="password" name="password" placeholder="Password" required>
<button>Masuk</button>
</form>
</html>
Query memakai prepared statement, lalu password_verify() memeriksa hash. Jika 2FA aktif, kode hanya mengisi pending_2fa berisi uid, batas waktu 300 detik, dan hitungan percobaan. Akibatnya, halaman lain yang memeriksa $_SESSION['uid'] tetap menolak user ini.
Langkah 2: verify.php
<?php
// public/verify.php — langkah 2: kode Authenticator atau kode cadangan
require __DIR__.'/../bootstrap.php';
$p = $_SESSION['pending_2fa'] ?? null;
if (!is_array($p) || $p['exp'] < time()) {
unset($_SESSION['pending_2fa']);
redirect('login.php');
}
$error = '';
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
csrf_check();
$how = twofa_check($p['uid'], (string) ($_POST['code'] ?? ''));
if ($how !== false) {
unset($_SESSION['pending_2fa']);
session_regenerate_id(true);
$_SESSION['uid'] = $p['uid']; // baru sekarang user benar-benar login
if ($how === 'backup') {
$_SESSION['flash'] = 'Anda masuk dengan kode cadangan. Sisa: ' . twofa_backup_left($p['uid']);
}
redirect('setup.php');
}
$_SESSION['pending_2fa']['tries']++;
if ($_SESSION['pending_2fa']['tries'] >= 5) {
unset($_SESSION['pending_2fa']);
redirect('login.php'); // terlalu banyak salah: ulangi dari password
}
$error = 'Kode salah atau sudah dipakai. Sisa percobaan: ' . (5 - $_SESSION['pending_2fa']['tries']);
}
?>
<!doctype html>
<html lang="id"><meta charset="utf-8"><title>Verifikasi 2 Langkah</title>
<form method="post" autocomplete="off">
<?= csrf_field() ?>
<p><?= h($error) ?></p>
<input name="code" inputmode="numeric" autocomplete="one-time-code" placeholder="123456 atau kode cadangan" required>
<button>Verifikasi</button>
</form>
</html>
Halaman ini menolak akses tanpa pending_2fa yang masih berlaku. Setelah kode lolos, kode menghapus tiket, memanggil session_regenerate_id(true) untuk mencegah session fixation, lalu mengisi $_SESSION['uid']. Sebaliknya, setelah 5 kali salah, tiket hilang dan user harus mengetik password lagi. Dengan demikian, penyerang tidak bisa menebak 1 juta kemungkinan kode dalam satu sesi.
Uji Alur Lengkap Lewat HTTP
Terakhir, kami menjalankan seluruh alur dengan curl di server uji: login, setup, aktivasi, login ulang, kode salah, kode bekas, kode cadangan, dan batas 5 percobaan. Kode untuk aktivasi dan login berasal dari oathtool, jadi pengujian ini meniru HP sungguhan.

Hasilnya sesuai harapan. Server menolak kode aktivasi saat kami mencobanya lagi untuk login, karena langkah waktunya sudah tercatat di last_step. Kode cadangan hanya berlaku sekali. Kolom secret_enc berisi ciphertext 96 karakter, dan dekripsi dengan key lain menghasilkan NULL.
Contoh Kasus dari Sistem Produksi Kami
Contoh Kasus 1: Dua Aplikasi, Satu Database
Aplikasi billing ISP kami punya dua frontend, yaitu versi web dan versi PWA, yang membaca database yang sama. Kami memasang 2FA opsional untuk semua admin dengan pola persis seperti artikel ini, termasuk pending_2fa 5 menit dan maksimal 5 percobaan. Namun, ada satu syarat yang mudah terlewat: key enkripsi kedua aplikasi harus sama. Jika berbeda, admin yang mengaktifkan 2FA lewat web akan gagal login lewat PWA, karena PWA tidak bisa mendekripsi secret-nya. Hal serupa terjadi di server development yang memakai salinan database produksi dengan key berbeda. Akibatnya, semua akun ber-2FA tidak bisa login di sana. Kami mencatat aturan ini di dokumentasi internal agar tidak ada yang mengganti key sembarangan.
Selain itu, admin pemilik akun bisa mereset 2FA anggota tim yang kehilangan HP. Fitur ini cukup menghapus baris user_2fa milik anggota tersebut, lalu anggota itu memasang ulang dari awal.
Contoh Kasus 2: Satu Admin dan Pintu Darurat
Panel admin situs kami hanya punya satu akun administrator. Kami memindahkan kode 2FA dari billing ke panel ini, lengkap dengan kode cadangan dan opsi “percayai perangkat” selama 30 hari. Masalahnya, jika HP hilang dan kode cadangan tidak tersedia, tidak ada admin lain yang bisa mereset. Oleh karena itu, kami menyiapkan pintu darurat lewat SSH ke server, yaitu satu query yang menghapus baris 2FA milik admin tersebut.
DELETE FROM user_2fa WHERE user_id = 1;
Pintu darurat ini aman karena hanya orang yang sudah memegang akses SSH yang bisa menjalankannya. Setelah itu, admin login dengan password saja, lalu langsung mengaktifkan 2FA lagi.
Contoh Kasus 3: Jam Laptop Meleset 41 Detik
Saat menyalin file uji ke server, tar memperingatkan bahwa timestamp file “41 detik di masa depan”. Ternyata jam laptop kami lebih cepat 41 detik daripada server yang tersinkron NTP. Selisih ini kurang lebih satu langkah TOTP, jadi $window = 1 masih menolongnya. Namun, HP dengan selisih lebih dari satu menit akan selalu gagal. Karena itu, pastikan server memakai NTP (cek dengan timedatectl) dan minta user menyalakan “waktu otomatis” di HP.
Kesalahan Umum
- Membuat session login sebelum kode 2FA lolos. Jika
$_SESSION['uid']terisi di login.php, penyerang cukup melompati verify.php. Pakai statuspending_2fa. - Membuat QR lewat layanan luar. URI otpauth memuat secret, jadi secret ikut tercatat di log layanan tersebut.
- Menyimpan secret polos di database. Dump database yang bocor langsung memberi penyerang semua faktor kedua. Enkripsi dengan key di luar database.
- Tidak mencatat last_step. Tanpa kolom ini, kode yang sama tetap berlaku sampai sekitar 60 detik, cukup lama untuk serangan phishing real-time.
- Window terlalu lebar. Toleransi ±5 langkah memang mengurangi keluhan, tetapi memperluas peluang tebakan. Cukup ±1 dan perbaiki jam server.
- Tanpa batas percobaan. Kode 6 digit hanya punya 1 juta kemungkinan. Batasi 5 percobaan per tiket dan catat kegagalan di log.
- Memakai
==untuk membandingkan kode. Pakaihash_equals()agar perbandingan berjalan dalam waktu konstan. - Menyimpan kode cadangan polos. Perlakukan seperti password:
password_hash()lalu tandai sekali pakai. - Mengganti key enkripsi tanpa migrasi. Semua secret lama langsung tidak terbaca dan semua user ber-2FA terkunci.
Kesimpulan
2FA Google Authenticator ternyata tidak butuh library. Inti TOTP hanya HMAC-SHA1, pack('J'), dynamic truncation, dan modulo, semuanya fungsi bawaan PHP. Kuncinya ada pada pengujian: kode kita cocok dengan 18 test vector RFC 6238 dan dengan oathtool sebelum menyentuh login sungguhan.
Namun, algoritma yang benar baru separuh pekerjaan. Bagian lain yang sama penting adalah QR buatan lokal, secret terenkripsi, status pending_2fa dengan batas waktu dan batas percobaan, anti pemakaian ulang lewat last_step, serta kode cadangan yang tersimpan sebagai hash. Terakhir, siapkan pintu darurat dan simpan key enkripsi dengan baik, karena 2FA yang membuat admin sendiri terkunci juga merupakan masalah keamanan.
Baca Juga
- Cara Hash Password yang Aman di PHP (password_hash)
- Keamanan Server Linux: Tutorial Hardening SSH, Firewall UFW, CrowdSec, dan Alarm Telegram
- Cara Mencegah SQL Injection di PHP (Panduan Lengkap)
Referensi: RFC 6238: TOTP, RFC 4226: HOTP, Google Authenticator Key Uri Format, PHP: hash_hmac, PHP: sodium_crypto_secretbox.

