ADR-006: Pelaksanaan Pengesahan Dua Faktor

StatusDicadangkan## KonteksXOOPS memerlukan keselamatan yang dipertingkatkan untuk pengesahan pengguna. Pengesahan dua faktor (2FA) menyediakan lapisan keselamatan tambahan di luar kata laluan, melindungi akaun walaupun kata laluan terjejas.Pertimbangan utama:

• Keserasian ke belakang dengan pengesahan sedia ada
• Sokongan untuk pelbagai kaedah 2FA
• Pengalaman pengguna semasa persediaan dan log masuk
• Mekanisme pemulihan untuk peranti yang hilang
• Integrasi dengan sistem kebenaran sedia ada## KeputusanKami akan melaksanakan TOTP (Kata Laluan Satu Masa Berasaskan Masa) sebagai kaedah 2FA utama dengan sokongan untuk kod sandaran.### Pendekatan Pelaksanaan

mermaid
sequenceDiagram
    participant U as User
    participant X as XOOPS
    participant T as TOTP Library
    participant D as Database

    U->>X: Login with password
    X->>D: Validate password
    D-->>X: Password valid
    X->>D: Check 2FA enabled
    D-->>X: 2FA required
    X->>U: Request 2FA code
    U->>X: Submit TOTP code
    X->>T: Validate code
    T-->>X: Code valid
    X->>U: Login successful

Skema Pangkalan Data

sql
CREATE TABLE `{PREFIX}_users_2fa` (
    `user_id` INT(11) NOT NULL,
    `secret` VARCHAR(32) NOT NULL,
    `enabled` TINYINT(1) DEFAULT 0,
    `backup_codes` TEXT,
    `last_used` INT(11),
    `created` INT(11) NOT NULL,
    PRIMARY KEY (`user_id`),
    FOREIGN KEY (`user_id`) REFERENCES `{PREFIX}_users`(`uid`)
);

Antara Muka Perkhidmatan

php
interface TwoFactorAuthInterface
{
    public function enable(int $userId): TwoFactorSetup;
    public function disable(int $userId): void;
    public function verify(int $userId, string $code): bool;
    public function generateBackupCodes(int $userId): array;
    public function isEnabled(int $userId): bool;
}

Integrasi Pertengahan

php
class TwoFactorMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        $session = $request->getAttribute('session');

        if ($session->has('pending_2fa_user_id')) {
            // User needs to complete 2FA
            if ($this->isVerificationRequest($request)) {
                return $handler->handle($request);
            }
            return new RedirectResponse('/2fa/verify');
        }

        return $handler->handle($request);
    }
}

Akibat### Positif- Keselamatan akaun dipertingkatkan dengan ketara

• Keserasian TOTP standard industri (Google Authenticator, Authy, dsb.)
• Kod sandaran menghalang penguncian akaun
• Pilihan setiap pengguna - tidak memaksa diterima pakai
• Perisian tengah PSR-15 membolehkan integrasi bersih### Negatif- Langkah log masuk tambahan memberi kesan kepada pengalaman pengguna
• Pengguna mesti mengurus apl pengesah
• Peranti yang hilang memerlukan proses pemulihan
• Storan pangkalan data tambahan dan pertanyaan
• Memerlukan pergantungan perpustakaan kriptografi### Laluan Migrasi1. Tambah jadual pangkalan data untuk data 2FA

2. Laksanakan perkhidmatan TOTP dengan pergantungan perpustakaan
3. Tambahkan perisian tengah pada rantaian pengesahan
4. Buat UI persediaan dan pengesahan
5. Pilihan pentadbir memerlukan 2FA untuk kumpulan tertentu## Alternatif Dipertimbangkan### OTP berasaskan SMSDitolak kerana:

• Kelemahan pertukaran SIM
• Kos gerbang SMS
• Kerumitan pengesahan nombor telefon
• Kebimbangan privasi### Kunci Keselamatan Perkakasan (WebAuthn)Ditunda untuk ADR masa hadapan:
• Pelaksanaan yang lebih kompleks
• Sokongan penyemak imbas terhad dari segi sejarah
• Kos pengguna yang lebih tinggi
• Boleh ditambah bersama TOTP kemudian### OTP berasaskan e-melDitolak kerana:
• Akaun e-mel kompromi mengalahkan tujuan
• Kelewatan penghantaran memberi kesan kepada UX
• Isu penapis spam## Rujukan- RFC 6238 - TOTP
• Format Kunci Pengesah Google
• ../../02-Core-Concepts/Security/Security-Best-Practices - Garis panduan keselamatan
• ../../02-Core-Concepts/Users-Permissions/Authentication - Dokumentasi sistem pengesahan