Multi-Factor Authentication Implementation Guide

Introduction

Multi-Factor Authentication (MFA) has evolved from a luxury security feature to an essential requirement for protecting user accounts and sensitive data. With credential stuffing attacks and password breaches on the rise, implementing robust MFA is critical for modern applications.

This comprehensive guide explores implementing MFA in production applications, covering TOTP-based authentication, SMS verification, biometric options, backup codes, and recovery mechanisms to ensure both security and usability.

Understanding MFA Fundamentals

The Three Authentication Factors

MFA combines two or more independent factors:

const AuthenticationFactors = {
  // Something you know
  KNOWLEDGE: ['password', 'PIN', 'security question'],

  // Something you have
  POSSESSION: ['phone', 'hardware token', 'smart card', 'authenticator app'],

  // Something you are
  INHERENCE: ['fingerprint', 'face recognition', 'voice recognition', 'iris scan']
};

// True MFA requires factors from different categories
function validateMFA(factors) {
  const categories = new Set(factors.map(f => f.category));
  return categories.size >= 2;
}

Implementing TOTP-Based Authentication

TOTP Overview

Time-based One-Time Password (TOTP) is the most common MFA method:

const speakeasy = require('speakeasy');
const QRCode = require('qrcode');

class TOTPService {
  generateSecret(userId, email) {
    const secret = speakeasy.generateSecret({
      name: `YourApp (${email})`,
      issuer: 'YourApp',
      length: 32
    });

    return {
      secret: secret.base32,
      otpauth_url: secret.otpauth_url
    };
  }

  async generateQRCode(otpauth_url) {
    try {
      return await QRCode.toDataURL(otpauth_url);
    } catch (error) {
      throw new Error('Failed to generate QR code');
    }
  }

  verifyToken(token, secret) {
    return speakeasy.totp.verify({
      secret: secret,
      encoding: 'base32',
      token: token,
      window: 2 // Allow 2 time steps before/after for clock skew
    });
  }

  // Generate current token (for testing)
  generateToken(secret) {
    return speakeasy.totp({
      secret: secret,
      encoding: 'base32'
    });
  }
}

Database Schema for MFA

// User MFA configuration schema
const MFAConfigSchema = {
  userId: {
    type: String,
    required: true,
    index: true
  },
  totpSecret: {
    type: String,
    encrypted: true // Encrypt at rest
  },
  totpEnabled: {
    type: Boolean,
    default: false
  },
  backupCodes: [{
    code: String,
    used: Boolean,
    usedAt: Date
  }],
  smsEnabled: {
    type: Boolean,
    default: false
  },
  phoneNumber: {
    type: String,
    encrypted: true
  },
  recoveryEmail: {
    type: String,
    encrypted: true
  },
  trustedDevices: [{
    deviceId: String,
    name: String,
    lastUsed: Date,
    createdAt: Date
  }],
  mfaEnrolledAt: Date,
  lastMfaVerification: Date
};

TOTP Enrollment Flow

Backend Implementation

const express = require('express');
const router = express.Router();

class MFAEnrollmentService {
  async initiateEnrollment(userId, email) {
    // Generate TOTP secret
    const totpService = new TOTPService();
    const { secret, otpauth_url } = totpService.generateSecret(userId, email);

    // Generate QR code
    const qrCode = await totpService.generateQRCode(otpauth_url);

    // Store secret temporarily (not yet enabled)
    await this.storePendingMFA(userId, secret);

    return {
      secret, // Show to user for manual entry
      qrCode,
      backupCodes: await this.generateBackupCodes(userId)
    };
  }

  async verifyEnrollment(userId, token) {
    const config = await this.getPendingMFA(userId);

    if (!config || !config.totpSecret) {
      throw new Error('No pending MFA enrollment found');
    }

    const totpService = new TOTPService();
    const verified = totpService.verifyToken(token, config.totpSecret);

    if (!verified) {
      throw new Error('Invalid verification code');
    }

    // Enable TOTP for user
    await this.enableTOTP(userId, config.totpSecret);

    return { success: true };
  }

  async generateBackupCodes(userId, count = 10) {
    const crypto = require('crypto');
    const codes = [];

    for (let i = 0; i < count; i++) {
      const code = crypto.randomBytes(4).toString('hex').toUpperCase();
      codes.push({
        code,
        used: false
      });
    }

    await this.storeBackupCodes(userId, codes);

    return codes.map(c => c.code);
  }

  async enableTOTP(userId, secret) {
    await MFAConfig.findOneAndUpdate(
      { userId },
      {
        totpSecret: secret,
        totpEnabled: true,
        mfaEnrolledAt: new Date()
      },
      { upsert: true }
    );
  }
}

// Routes
router.post('/mfa/enroll/start', authenticateUser, async (req, res) => {
  try {
    const service = new MFAEnrollmentService();
    const enrollment = await service.initiateEnrollment(
      req.user.id,
      req.user.email
    );

    res.json({
      qrCode: enrollment.qrCode,
      secret: enrollment.secret,
      backupCodes: enrollment.backupCodes
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

router.post('/mfa/enroll/verify', authenticateUser, async (req, res) => {
  try {
    const { token } = req.body;
    const service = new MFAEnrollmentService();

    await service.verifyEnrollment(req.user.id, token);

    res.json({ message: 'MFA enabled successfully' });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

MFA Verification Flow

Login with MFA

class MFAAuthenticationService {
  async authenticateWithMFA(userId, password, mfaToken) {
    // Step 1: Verify password
    const user = await User.findById(userId);
    if (!user || !await user.verifyPassword(password)) {
      throw new Error('Invalid credentials');
    }

    // Step 2: Check if MFA is enabled
    const mfaConfig = await MFAConfig.findOne({ userId });
    if (!mfaConfig || !mfaConfig.totpEnabled) {
      // MFA not enabled, complete login
      return this.generateSession(user);
    }

    // Step 3: Verify MFA token
    if (!mfaToken) {
      return {
        requiresMFA: true,
        userId: user.id
      };
    }

    // Verify TOTP token
    const totpService = new TOTPService();
    const verified = totpService.verifyToken(
      mfaToken,
      mfaConfig.totpSecret
    );

    if (!verified) {
      // Check if it's a backup code
      if (await this.verifyBackupCode(userId, mfaToken)) {
        return this.generateSession(user);
      }

      throw new Error('Invalid MFA token');
    }

    // Update last verification time
    await MFAConfig.findOneAndUpdate(
      { userId },
      { lastMfaVerification: new Date() }
    );

    return this.generateSession(user);
  }

  async verifyBackupCode(userId, code) {
    const mfaConfig = await MFAConfig.findOne({ userId });

    const backupCode = mfaConfig.backupCodes.find(
      bc => bc.code === code.toUpperCase() && !bc.used
    );

    if (!backupCode) {
      return false;
    }

    // Mark backup code as used
    backupCode.used = true;
    backupCode.usedAt = new Date();
    await mfaConfig.save();

    // Alert user that backup code was used
    await this.sendBackupCodeUsedAlert(userId);

    return true;
  }

  generateSession(user) {
    const jwt = require('jsonwebtoken');

    return {
      accessToken: jwt.sign(
        { sub: user.id, mfaVerified: true },
        process.env.JWT_SECRET,
        { expiresIn: '15m' }
      ),
      refreshToken: jwt.sign(
        { sub: user.id },
        process.env.REFRESH_SECRET,
        { expiresIn: '7d' }
      )
    };
  }
}

// Login route with MFA
router.post('/auth/login', async (req, res) => {
  try {
    const { email, password, mfaToken } = req.body;

    const user = await User.findOne({ email });
    if (!user) {
      return res.status(401).json({ error: 'Invalid credentials' });
    }

    const service = new MFAAuthenticationService();
    const result = await service.authenticateWithMFA(
      user.id,
      password,
      mfaToken
    );

    if (result.requiresMFA) {
      return res.json({
        requiresMFA: true,
        message: 'MFA token required'
      });
    }

    res.json({
      accessToken: result.accessToken,
      refreshToken: result.refreshToken
    });
  } catch (error) {
    res.status(401).json({ error: error.message });
  }
});

SMS-Based MFA

Implementing SMS Verification

const twilio = require('twilio');

class SMSMFAService {
  constructor() {
    this.client = twilio(
      process.env.TWILIO_ACCOUNT_SID,
      process.env.TWILIO_AUTH_TOKEN
    );
    this.verificationCodes = new Map(); // Use Redis in production
  }

  async sendVerificationCode(userId, phoneNumber) {
    // Generate 6-digit code
    const code = Math.floor(100000 + Math.random() * 900000).toString();

    // Store code with expiration (5 minutes)
    const expiration = Date.now() + (5 * 60 * 1000);
    this.verificationCodes.set(userId, {
      code,
      phoneNumber,
      expiration,
      attempts: 0
    });

    // Send SMS
    try {
      await this.client.messages.create({
        body: `Your verification code is: ${code}. Valid for 5 minutes.`,
        to: phoneNumber,
        from: process.env.TWILIO_PHONE_NUMBER
      });

      return { success: true };
    } catch (error) {
      throw new Error('Failed to send SMS');
    }
  }

  async verifyCode(userId, code) {
    const stored = this.verificationCodes.get(userId);

    if (!stored) {
      throw new Error('No verification code found');
    }

    // Check expiration
    if (Date.now() > stored.expiration) {
      this.verificationCodes.delete(userId);
      throw new Error('Verification code expired');
    }

    // Check attempts (rate limiting)
    if (stored.attempts >= 3) {
      this.verificationCodes.delete(userId);
      throw new Error('Too many failed attempts');
    }

    // Verify code
    if (stored.code !== code) {
      stored.attempts++;
      throw new Error('Invalid verification code');
    }

    // Success - clean up
    this.verificationCodes.delete(userId);
    return { success: true };
  }
}

Trusted Device Management

Remember This Device

const crypto = require('crypto');

class TrustedDeviceService {
  async trustDevice(userId, deviceInfo) {
    const deviceId = this.generateDeviceId(deviceInfo);

    const device = {
      deviceId,
      name: deviceInfo.name || 'Unknown Device',
      userAgent: deviceInfo.userAgent,
      lastUsed: new Date(),
      createdAt: new Date()
    };

    await MFAConfig.findOneAndUpdate(
      { userId },
      { $push: { trustedDevices: device } }
    );

    // Generate device token
    const deviceToken = this.generateDeviceToken(userId, deviceId);

    return { deviceId, deviceToken };
  }

  async isDeviceTrusted(userId, deviceToken) {
    try {
      const jwt = require('jsonwebtoken');
      const decoded = jwt.verify(deviceToken, process.env.DEVICE_SECRET);

      if (decoded.userId !== userId) {
        return false;
      }

      const mfaConfig = await MFAConfig.findOne({ userId });
      const device = mfaConfig.trustedDevices.find(
        d => d.deviceId === decoded.deviceId
      );

      if (!device) {
        return false;
      }

      // Check if device token is still valid (e.g., 30 days)
      const daysSinceTrust = (Date.now() - device.lastUsed) / (1000 * 60 * 60 * 24);
      if (daysSinceTrust > 30) {
        return false;
      }

      // Update last used
      device.lastUsed = new Date();
      await mfaConfig.save();

      return true;
    } catch (error) {
      return false;
    }
  }

  generateDeviceId(deviceInfo) {
    const hash = crypto.createHash('sha256');
    hash.update(deviceInfo.userAgent || '');
    hash.update(deviceInfo.ip || '');
    return hash.digest('hex');
  }

  generateDeviceToken(userId, deviceId) {
    const jwt = require('jsonwebtoken');
    return jwt.sign(
      { userId, deviceId },
      process.env.DEVICE_SECRET,
      { expiresIn: '30d' }
    );
  }

  async removeTrustedDevice(userId, deviceId) {
    await MFAConfig.findOneAndUpdate(
      { userId },
      { $pull: { trustedDevices: { deviceId } } }
    );
  }
}

// Middleware to check trusted device
async function checkTrustedDevice(req, res, next) {
  const deviceToken = req.cookies.deviceToken;

  if (!deviceToken) {
    return next();
  }

  const service = new TrustedDeviceService();
  const trusted = await service.isDeviceTrusted(req.user.id, deviceToken);

  req.trustedDevice = trusted;
  next();
}

Recovery Mechanisms

Account Recovery Without MFA Access

class MFARecoveryService {
  async initiateRecovery(email) {
    const user = await User.findOne({ email });
    if (!user) {
      // Don't reveal if user exists
      return { message: 'If account exists, recovery email sent' };
    }

    const mfaConfig = await MFAConfig.findOne({ userId: user.id });
    if (!mfaConfig || !mfaConfig.totpEnabled) {
      throw new Error('MFA not enabled for this account');
    }

    // Generate recovery token
    const recoveryToken = crypto.randomBytes(32).toString('hex');
    const expiration = Date.now() + (1 * 60 * 60 * 1000); // 1 hour

    // Store recovery token
    await RecoveryToken.create({
      userId: user.id,
      token: recoveryToken,
      expiresAt: expiration,
      used: false
    });

    // Send recovery email
    await this.sendRecoveryEmail(user.email, recoveryToken);

    return { message: 'Recovery email sent' };
  }

  async verifyRecoveryToken(token, newPassword) {
    const recoveryToken = await RecoveryToken.findOne({
      token,
      used: false
    });

    if (!recoveryToken) {
      throw new Error('Invalid or expired recovery token');
    }

    if (Date.now() > recoveryToken.expiresAt) {
      throw new Error('Recovery token expired');
    }

    // Reset password and disable MFA
    const user = await User.findById(recoveryToken.userId);
    await user.setPassword(newPassword);

    // Disable MFA - user must re-enroll
    await MFAConfig.findOneAndUpdate(
      { userId: recoveryToken.userId },
      {
        totpEnabled: false,
        totpSecret: null,
        $set: { backupCodes: [] }
      }
    );

    // Mark token as used
    recoveryToken.used = true;
    await recoveryToken.save();

    // Send security alert
    await this.sendMFADisabledAlert(user.email);

    return { success: true };
  }

  async sendRecoveryEmail(email, token) {
    const nodemailer = require('nodemailer');
    const transporter = nodemailer.createTransport({
      // Configure your email service
    });

    const recoveryUrl = `https://yourapp.com/recover-mfa?token=${token}`;

    await transporter.sendMail({
      from: 'security@yourapp.com',
      to: email,
      subject: 'MFA Recovery Request',
      html: `
        <p>You requested to recover your account.</p>
        <p>Click the link below to reset your password and disable MFA:</p>
        <a href="${recoveryUrl}">${recoveryUrl}</a>
        <p>This link expires in 1 hour.</p>
        <p>If you didn't request this, please ignore this email.</p>
      `
    });
  }
}

WebAuthn/FIDO2 Support

Implementing Biometric Authentication

const { Fido2Lib } = require('fido2-lib');

class WebAuthnService {
  constructor() {
    this.f2l = new Fido2Lib({
      timeout: 60000,
      rpId: 'yourapp.com',
      rpName: 'YourApp',
      challengeSize: 128,
      attestation: 'none',
      cryptoParams: [-7, -257],
      authenticatorAttachment: 'platform',
      authenticatorRequireResidentKey: false,
      authenticatorUserVerification: 'required'
    });
  }

  async generateRegistrationOptions(userId, username) {
    const registrationOptions = await this.f2l.attestationOptions();

    // Store challenge for verification
    await this.storeChallenge(userId, registrationOptions.challenge);

    return {
      ...registrationOptions,
      user: {
        id: Buffer.from(userId).toString('base64'),
        name: username,
        displayName: username
      }
    };
  }

  async verifyRegistration(userId, credential) {
    const challenge = await this.getChallenge(userId);

    const attestationExpectations = {
      challenge,
      origin: 'https://yourapp.com',
      factor: 'either'
    };

    const regResult = await this.f2l.attestationResult(
      credential,
      attestationExpectations
    );

    // Store credential
    await this.storeCredential(userId, {
      credentialId: regResult.authnrData.get('credId'),
      publicKey: regResult.authnrData.get('credentialPublicKeyPem'),
      counter: regResult.authnrData.get('counter')
    });

    return { success: true };
  }

  async generateAuthenticationOptions(userId) {
    const credentials = await this.getUserCredentials(userId);

    const authenticationOptions = await this.f2l.assertionOptions();

    await this.storeChallenge(userId, authenticationOptions.challenge);

    return {
      ...authenticationOptions,
      allowCredentials: credentials.map(cred => ({
        type: 'public-key',
        id: cred.credentialId
      }))
    };
  }

  async verifyAuthentication(userId, credential) {
    const challenge = await this.getChallenge(userId);
    const storedCredential = await this.getCredential(
      userId,
      credential.rawId
    );

    const assertionExpectations = {
      challenge,
      origin: 'https://yourapp.com',
      factor: 'either',
      publicKey: storedCredential.publicKey,
      prevCounter: storedCredential.counter,
      userHandle: Buffer.from(userId).toString('base64')
    };

    const authnResult = await this.f2l.assertionResult(
      credential,
      assertionExpectations
    );

    // Update counter
    await this.updateCounter(
      userId,
      credential.rawId,
      authnResult.authnrData.get('counter')
    );

    return { success: true };
  }
}

Best Practices and Security Considerations

MFA Implementation Checklist

const MFABestPractices = {
  enrollment: [
    'Require email verification before MFA enrollment',
    'Generate and display backup codes during enrollment',
    'Show QR code and manual entry option',
    'Require verification of TOTP before enabling',
    'Send confirmation email after MFA is enabled'
  ],

  verification: [
    'Allow clock skew tolerance (±1-2 time steps)',
    'Implement rate limiting on verification attempts',
    'Support backup codes for account recovery',
    'Log all MFA verification attempts',
    'Send alerts on suspicious MFA activity'
  ],

  storage: [
    'Encrypt TOTP secrets at rest',
    'Hash backup codes before storage',
    'Store phone numbers encrypted',
    'Use secure key management system',
    'Implement audit logging'
  ],

  recovery: [
    'Provide multiple recovery options',
    'Require identity verification for recovery',
    'Time-limit recovery tokens',
    'Send security alerts on recovery usage',
    'Force MFA re-enrollment after recovery'
  ],

  userExperience: [
    'Support "Remember this device" option',
    'Provide clear enrollment instructions',
    'Allow users to manage trusted devices',
    'Show recent authentication history',
    'Enable MFA setup during registration'
  ]
};

Testing MFA Implementation

const request = require('supertest');

describe('MFA Implementation', () => {
  let app;
  let user;
  let totpService;

  beforeEach(async () => {
    app = createApp();
    user = await createTestUser();
    totpService = new TOTPService();
  });

  describe('TOTP Enrollment', () => {
    it('should generate valid QR code and secret', async () => {
      const response = await request(app)
        .post('/mfa/enroll/start')
        .set('Authorization', `Bearer ${user.token}`)
        .expect(200);

      expect(response.body.qrCode).toBeDefined();
      expect(response.body.secret).toBeDefined();
      expect(response.body.backupCodes).toHaveLength(10);
    });

    it('should verify TOTP token and enable MFA', async () => {
      // Start enrollment
      const enrollResponse = await request(app)
        .post('/mfa/enroll/start')
        .set('Authorization', `Bearer ${user.token}`);

      const { secret } = enrollResponse.body;

      // Generate valid token
      const token = totpService.generateToken(secret);

      // Verify enrollment
      const verifyResponse = await request(app)
        .post('/mfa/enroll/verify')
        .set('Authorization', `Bearer ${user.token}`)
        .send({ token })
        .expect(200);

      expect(verifyResponse.body.message).toBe('MFA enabled successfully');
    });

    it('should reject invalid TOTP token', async () => {
      await request(app)
        .post('/mfa/enroll/verify')
        .set('Authorization', `Bearer ${user.token}`)
        .send({ token: '000000' })
        .expect(400);
    });
  });

  describe('MFA Authentication', () => {
    beforeEach(async () => {
      await enableMFAForUser(user);
    });

    it('should require MFA token after password', async () => {
      const response = await request(app)
        .post('/auth/login')
        .send({
          email: user.email,
          password: 'password123'
        })
        .expect(200);

      expect(response.body.requiresMFA).toBe(true);
    });

    it('should authenticate with valid MFA token', async () => {
      const mfaConfig = await getMFAConfig(user.id);
      const token = totpService.generateToken(mfaConfig.totpSecret);

      const response = await request(app)
        .post('/auth/login')
        .send({
          email: user.email,
          password: 'password123',
          mfaToken: token
        })
        .expect(200);

      expect(response.body.accessToken).toBeDefined();
    });

    it('should authenticate with backup code', async () => {
      const mfaConfig = await getMFAConfig(user.id);
      const backupCode = mfaConfig.backupCodes[0].code;

      const response = await request(app)
        .post('/auth/login')
        .send({
          email: user.email,
          password: 'password123',
          mfaToken: backupCode
        })
        .expect(200);

      expect(response.body.accessToken).toBeDefined();

      // Verify backup code is marked as used
      const updatedConfig = await getMFAConfig(user.id);
      expect(updatedConfig.backupCodes[0].used).toBe(true);
    });
  });

  describe('Trusted Devices', () => {
    it('should trust device and skip MFA', async () => {
      const deviceService = new TrustedDeviceService();
      const { deviceToken } = await deviceService.trustDevice(user.id, {
        name: 'Test Device',
        userAgent: 'Mozilla/5.0...'
      });

      const response = await request(app)
        .post('/auth/login')
        .set('Cookie', [`deviceToken=${deviceToken}`])
        .send({
          email: user.email,
          password: 'password123'
        })
        .expect(200);

      expect(response.body.accessToken).toBeDefined();
      expect(response.body.requiresMFA).toBeUndefined();
    });
  });
});

Conclusion

Implementing Multi-Factor Authentication is essential for protecting user accounts in modern applications. By following the patterns and best practices outlined in this guide, you can build a secure, user-friendly MFA system that significantly enhances account security.

Key takeaways:

• TOTP-based authentication provides strong security without SMS costs
• Always provide backup codes for account recovery
• Implement trusted device management for better UX
• Support multiple MFA methods (TOTP, SMS, WebAuthn)
• Encrypt sensitive MFA data at rest
• Provide clear recovery mechanisms
• Rate-limit verification attempts
• Send security alerts for suspicious activity

Remember that MFA security must be balanced with usability. Users should never feel locked out of their accounts, but security should never be compromised. Regular testing, monitoring, and user feedback will help you maintain this balance as your application evolves.

By implementing MFA properly, you protect not only user accounts but also build trust and demonstrate your commitment to security best practices.