MFA Cho Developer: Vì Sao Cần, Hoạt Động Thế Nào, Implement Ra Sao

email + password đúng -> full session -> account takeover

email + password đúng -> pending MFA -> attacker thiếu factor -> login bị chặn

users
  id
  email
  password_hash
  mfa_required_at
  created_at

mfa_factors
  id
  user_id
  type: totp | webauthn | backup_code | sms | email
  name
  status: pending | active | disabled
  secret_encrypted
  credential_id
  public_key
  sign_count
  transports
  created_at
  confirmed_at
  last_used_at

mfa_challenges
  id
  user_id
  factor_type
  status: pending | passed | failed | expired
  purpose: login | step_up | recovery
  expires_at
  attempt_count
  created_at

backup_codes
  id
  user_id
  code_hash
  used_at
  created_at

security_events
  id
  user_id
  event_type
  ip
  user_agent
  metadata_json
  created_at

shared secret + current time window -> 6 digit code

TOTP verify:

1. Server và authenticator app cùng giữ shared secret.
2. Cả hai lấy mốc thời gian hiện tại, thường là block 30 giây.
3. App tính ra mã 6 số và user nhập mã đó.
4. Server tự tính lại mã từ secret + time window.
5. Nếu mã khớp trong window cho phép, challenge được pass.

1. User chọn Enable MFA.
2. Server generate random TOTP secret.
3. Server lưu secret ở trạng thái pending, đã encrypt.
4. Server trả otpauth:// URL hoặc QR code.
5. User scan QR bằng authenticator app.
6. User nhập mã đầu tiên.
7. Server verify đúng thì chuyển factor sang active.
8. Server cấp backup codes và ghi audit log.

npm install otpauth qrcode

import { TOTP, Secret } from "otpauth";
import QRCode from "qrcode";

const issuer = "Jerry Notes";

export async function startTotpEnrollment(user) {
  const secret = new Secret({ size: 20 });

  const totp = new TOTP({
    issuer,
    label: user.email,
    algorithm: "SHA1",
    digits: 6,
    period: 30,
    secret,
  });

  await db.mfaFactors.insert({
    userId: user.id,
    type: "totp",
    status: "pending",
    secretEncrypted: await encrypt(secret.base32),
    createdAt: new Date(),
  });

  return {
    otpauthUrl: totp.toString(),
    qrDataUrl: await QRCode.toDataURL(totp.toString()),
  };
}

export async function confirmTotpEnrollment(userId, submittedCode) {
  await rateLimit.assertAllowed(`totp-confirm:${userId}`);

  const factor = await db.mfaFactors.findPendingTotp(userId);
  if (!factor) throw new Error("TOTP enrollment not found");

  const secretBase32 = await decrypt(factor.secretEncrypted);
  const totp = new TOTP({
    issuer,
    label: factor.userEmail,
    secret: Secret.fromBase32(secretBase32),
  });

  const delta = totp.validate({ token: submittedCode, window: 1 });
  if (delta === null) {
    await rateLimit.bump(`totp-confirm:${userId}`);
    throw new Error("Invalid code");
  }

  await db.mfaFactors.activate(factor.id);
  await db.backupCodes.replaceForUser(userId, generateBackupCodeHashes());
  await audit.log(userId, "mfa.totp.enabled");
}

export async function verifyTotpLogin(userId, challengeId, submittedCode) {
  await rateLimit.assertAllowed(`totp-login:${userId}`);

  const challenge = await db.mfaChallenges.findPending(challengeId, userId);
  if (!challenge || challenge.expiresAt < new Date()) {
    throw new Error("Challenge expired");
  }

  const factor = await db.mfaFactors.findActiveTotp(userId);
  if (!factor) throw new Error("TOTP factor not found");

  const secretBase32 = await decrypt(factor.secretEncrypted);
  const totp = new TOTP({
    issuer,
    label: factor.userEmail,
    secret: Secret.fromBase32(secretBase32),
  });

  const delta = totp.validate({ token: submittedCode, window: 1 });
  if (delta === null) {
    await db.mfaChallenges.incrementAttempts(challenge.id);
    await rateLimit.bump(`totp-login:${userId}`);
    throw new Error("Invalid code");
  }

  await db.mfaChallenges.markPassed(challenge.id);
  await db.mfaFactors.markUsed(factor.id);
  await session.rotateAfterMfa(userId);
  await audit.log(userId, "mfa.totp.verified");
}

server challenge -> authenticator ký bằng private key -> server verify bằng public key

Registration:

1. Browser gọi server để lấy registration options.
2. Server tạo challenge, rpID, user handle và lưu challenge ngắn hạn.
3. Browser gọi navigator.credentials.create().
4. Authenticator tạo key pair, giữ private key, trả attestation.
5. Browser gửi attestation về server.
6. Server verify challenge/origin/rpID rồi lưu public key.

Authentication:

1. Browser gọi server để lấy authentication options.
2. Server tạo challenge mới và danh sách credential được phép dùng.
3. Browser gọi navigator.credentials.get().
4. Authenticator yêu cầu user presence/verification rồi ký challenge.
5. Browser gửi signed assertion về server.
6. Server verify signature/origin/rpID/counter rồi rotate session.

npm install @simplewebauthn/server

import {
  generateRegistrationOptions,
  verifyRegistrationResponse,
  generateAuthenticationOptions,
  verifyAuthenticationResponse,
} from "@simplewebauthn/server";

const rpName = "Jerry Notes";
const rpID = "thangvd2312.github.io";
const origin = "https://thangvd2312.github.io";

export async function createPasskeyRegistrationOptions(user) {
  const credentials = await db.webauthnCredentials.findByUserId(user.id);

  const options = await generateRegistrationOptions({
    rpName,
    rpID,
    userID: user.id,
    userName: user.email,
    attestationType: "none",
    excludeCredentials: credentials.map((credential) => ({
      id: credential.credentialID,
      type: "public-key",
      transports: credential.transports,
    })),
    authenticatorSelection: {
      residentKey: "preferred",
      userVerification: "preferred",
    },
  });

  await db.webAuthnChallenges.save({
    userId: user.id,
    challenge: options.challenge,
    type: "registration",
    expiresAt: new Date(Date.now() + 5 * 60 * 1000),
  });

  return options;
}

export async function verifyPasskeyRegistration(user, body) {
  const expectedChallenge = await db.webAuthnChallenges.consume(
    user.id,
    "registration",
  );

  const verification = await verifyRegistrationResponse({
    response: body,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID,
    requireUserVerification: false,
  });

  if (!verification.verified || !verification.registrationInfo) {
    throw new Error("Invalid passkey registration");
  }

  const { credential, credentialDeviceType, credentialBackedUp } =
    verification.registrationInfo;

  await db.webauthnCredentials.insert({
    userId: user.id,
    credentialID: credential.id,
    publicKey: credential.publicKey,
    counter: credential.counter,
    transports: body.response?.transports ?? [],
    deviceType: credentialDeviceType,
    backedUp: credentialBackedUp,
    createdAt: new Date(),
  });

  await audit.log(user.id, "mfa.passkey.registered");
}

export async function createPasskeyAuthenticationOptions(user) {
  const credentials = await db.webauthnCredentials.findByUserId(user.id);

  const options = await generateAuthenticationOptions({
    rpID,
    allowCredentials: credentials.map((credential) => ({
      id: credential.credentialID,
      type: "public-key",
      transports: credential.transports,
    })),
    userVerification: "preferred",
  });

  await db.webAuthnChallenges.save({
    userId: user.id,
    challenge: options.challenge,
    type: "authentication",
    expiresAt: new Date(Date.now() + 5 * 60 * 1000),
  });

  return options;
}

export async function verifyPasskeyAuthentication(user, body) {
  const expectedChallenge = await db.webAuthnChallenges.consume(
    user.id,
    "authentication",
  );

  const credential = await db.webauthnCredentials.findByCredentialId(body.id);
  if (!credential || credential.userId !== user.id) {
    throw new Error("Credential not found");
  }

  const verification = await verifyAuthenticationResponse({
    response: body,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID,
    credential: {
      id: credential.credentialID,
      publicKey: credential.publicKey,
      counter: credential.counter,
      transports: credential.transports,
    },
    requireUserVerification: false,
  });

  if (!verification.verified) {
    throw new Error("Invalid passkey assertion");
  }

  await db.webauthnCredentials.updateCounter(
    credential.id,
    verification.authenticationInfo.newCounter,
  );
  await db.webauthnCredentials.markUsed(credential.id);
  await session.rotateAfterMfa(user.id);
  await audit.log(user.id, "mfa.passkey.verified");
}

1. Generate 8-12 code random, đủ entropy.
2. Hiển thị plaintext đúng một lần.
3. Khuyến khích user lưu vào password manager.
4. Server chỉ lưu hash.
5. Mỗi code dùng một lần.
6. Regenerate thì revoke toàn bộ code cũ.

export async function verifyBackupCode(userId, submittedCode) {
  await rateLimit.assertAllowed(`backup-code:${userId}`);

  const code = normalizeBackupCode(submittedCode);
  const candidates = await db.backupCodes.findUnusedByUserId(userId);
  const matched = await findMatchingHash(candidates, code);

  if (!matched) {
    await rateLimit.bump(`backup-code:${userId}`);
    throw new Error("Invalid backup code");
  }

  await db.backupCodes.markUsed(matched.id);
  await session.rotateAfterMfa(userId);
  await audit.log(userId, "mfa.backup_code.used");
  await notify.security(userId, "A backup code was used");
}

password ok           -> pending_mfa token
mfa ok                -> full session mới
password changed      -> revoke old sessions
mfa reset             -> revoke old sessions
high-risk action      -> require recent MFA