design-mfa-system

name	design-mfa-system
description	Use when adding multi-factor authentication to an application — implementing TOTP, WebAuthn/passkeys, recovery codes, and phishing-resistant options for high-value accounts.
source	OWASP MFA Cheat Sheet (owasp.org/www-project-cheat-sheets); NIST SP 800-63B (Digital Identity Guidelines); WebAuthn Level 2 specification (W3C); FIDO Alliance implementation guidance
tags	["security","owasp","mfa","totp","webauthn","authentication","identity","developer"]

Design MFA System

Implement TOTP as baseline MFA, WebAuthn/passkeys as phishing-resistant option, secure recovery codes, and account lockout — protecting accounts even when passwords are compromised.

Why This Is Best Practice

Adopted by: OWASP MFA Cheat Sheet and NIST SP 800-63B (AAL2/AAL3 requirements) are the authoritative references. Google, GitHub, Stripe, and all major financial institutions mandate MFA for administrative accounts. WebAuthn (FIDO2) is supported by all major browsers and operating systems since 2019. NIST SP 800-63B mandates MFA for any system at Authenticator Assurance Level 2 or 3, which includes most financial, healthcare, and government systems. Impact: Microsoft's 2019 analysis of 1.2 million compromised accounts found that 99.9% could have been prevented by MFA. Verizon DBIR 2023 found that stolen credentials account for 49% of breaches — MFA prevents credential-stuffing and password spray attacks from succeeding even with valid credentials. The 2022 Twilio breach compromised SMS MFA codes via phishing — illustrating why TOTP and WebAuthn are more secure than SMS, which is susceptible to SIM swapping and phishing relay attacks. Why best: SMS OTP (the alternative) is susceptible to SIM swapping attacks (real-time account takeover) and phishing relay attacks where an attacker proxies a live login. TOTP is significantly more resistant than SMS. WebAuthn/passkeys bind the authenticator to the origin (domain), making phishing impossible — the credential only works on the legitimate site. Combining TOTP baseline with WebAuthn option provides both broad coverage and maximum security for high-value accounts.

Sources: OWASP MFA Cheat Sheet; NIST SP 800-63B; WebAuthn Level 2 W3C specification; FIDO Alliance implementation guide; Microsoft Identity Security (2019)

Steps

1. Implement TOTP (Time-based One-Time Password) as baseline MFA:

   import pyotp
   import qrcode
   import io
   import base64
   from cryptography.fernet import Fernet
   
   class TOTPManager:
       def __init__(self, encryption_key: bytes):
           self.fernet = Fernet(encryption_key)
   
       def generate_totp_secret(self) -> str:
           # 160-bit secret (base32 encoded) — NIST SP 800-63B requirement
           return pyotp.random_base32()
   
       def get_provisioning_qr(self, user_email: str, secret: str, issuer: str) -> str:
           totp = pyotp.TOTP(secret)
           uri = totp.provisioning_uri(name=user_email, issuer_name=issuer)
           # Return QR code as base64 PNG
           qr = qrcode.make(uri)
           buffer = io.BytesIO()
           qr.save(buffer, format="PNG")
           return base64.b64encode(buffer.getvalue()).decode()
   
       def verify_totp(self, secret: str, token: str) -> bool:
           totp = pyotp.TOTP(secret)
           # valid_window=1 allows ±30 seconds clock drift
           return totp.verify(token, valid_window=1)
   
       def encrypt_secret_for_storage(self, secret: ) -> :
            .fernet.encrypt(secret.encode())
   
        () -> :
            .fernet.decrypt(encrypted).decode()
   
   
   
   

Rules

• SMS OTP must not be used as sole MFA factor — it's vulnerable to SIM swapping; offer TOTP or WebAuthn as alternatives.
• Recovery codes must be single-use and hashed in storage — displaying them again after initial setup allows an attacker who gains database access to use them.
• MFA bypass tokens (device-remember cookies) must be scoped to a specific device, expire in ≤30 days, and be invalidated on password change.
• WebAuthn challenges must be cryptographically random, at least 16 bytes, and expire within 5 minutes — stale challenges allow replay attacks.

Common Mistakes

• Implementing MFA as client-side validation only — MFA verification must happen server-side; client-side JavaScript checks are trivially bypassed.
• TOTP with valid_window > 2 — allowing more than ±60 seconds of clock drift significantly widens the brute-force window.
• Storing recovery codes in plaintext — recovery codes are as sensitive as passwords; hash with bcrypt before storage.
• Not invalidating existing sessions after MFA enrollment — a session created before MFA was enabled should require re-authentication.