Multi-Factor Authentication (MFA) Guide

Overview

Multi-Factor Authentication (MFA), also known as Two-Factor Authentication (2FA), adds an extra layer of security to your account by requiring a second verification step in addition to your password.

Why Use MFA?

MFA significantly improves account security by:

• Protecting against password theft: Even if your password is compromised, attackers cannot access your account without the second factor
• Meeting compliance requirements: Many security standards (SOC 2, GDPR) recommend or require MFA for sensitive accounts
• Admin account protection: Especially important for administrators who have access to platform-wide data

Supported Methods

TOTP (Time-based One-Time Password)

Recommended Method

Uses authenticator apps to generate time-based codes:

• Apps Supported: Google Authenticator, Microsoft Authenticator, Authy, 1Password, and other TOTP-compatible apps
• How It Works: Generates a new 6-digit code every 30 seconds
• Advantages:
  • No phone number required
  • Works offline
  • More secure (not vulnerable to SIM swapping)
  • Industry standard (RFC 6238)

SMS

Receive verification codes via text message:

• Requirements: Phone number in E.164 format (e.g., +14165551234)
• System Requirements: System phone number must be configured by administrator
• How It Works: Receives a 6-digit code via SMS (valid for 10 minutes)
• Rate Limiting: Maximum 3 codes per 15 minutes per user

Enrollment Process

TOTP Enrollment

1. Navigate to Profile → Security Settings
2. Click Enable MFA → Use Authenticator App
3. Scan the QR code with your authenticator app
   • Alternative: Enter the manual entry key if you can't scan
4. Enter the 6-digit code from your app to verify
5. Save your backup codes (shown only once)
6. MFA is now enabled

SMS Enrollment

1. Navigate to Profile → Security Settings
2. Click Enable MFA → Use SMS
3. Enter your phone number in E.164 format (e.g., +14165551234)
4. Click Send Verification Code
5. Enter the 6-digit code received via SMS
6. Save your backup codes (shown only once)
7. MFA is now enabled

Backup Codes

What Are Backup Codes?

Backup codes are one-time use codes that allow you to access your account if you lose access to your MFA device.

Important Notes

• 10 codes generated when you enable MFA
• One-time use only - each code can only be used once
• Cannot be retrieved after enrollment (they're hashed before storage)
• Download or copy during enrollment - this is your only chance to see them
• Regenerate if needed - you can generate new codes (this invalidates old ones)

Using Backup Codes

1. During login, if you can't access your MFA device
2. Check the "Use backup code instead" option
3. Enter one of your saved backup codes
4. The code will be consumed and cannot be used again

Regenerating Backup Codes

1. Navigate to Profile → Security Settings
2. Enter your password
3. Click Regenerate Backup Codes
4. Save the new codes - old codes are now invalid

Login Flow with MFA

Standard Login (No MFA)

1. Enter email and password
2. Access granted immediately

Login with MFA Enabled

1. Enter email and password
2. System detects MFA is enabled
3. Prompted for verification code
4. Enter code from:
   • Authenticator app (TOTP)
   • SMS message
   • Backup code
5. Access granted after successful verification

Managing MFA

View MFA Status

Check your MFA status in Profile → Security Settings:

• Enabled/Disabled: Current MFA status
• Method: TOTP or SMS
• Enrolled Date: When MFA was first enabled
• Last Used: Most recent successful MFA verification

Disable MFA

1. Navigate to Profile → Security Settings
2. Enter your password to confirm
3. Click Disable MFA
4. MFA is immediately disabled

Security Note: Disabling MFA removes the extra security layer. Only disable if necessary.

Change MFA Method

To switch from SMS to TOTP (or vice versa):

1. Disable current MFA (requires password)
2. Enable MFA with new method
3. Complete enrollment process

Security Features

Rate Limiting

• MFA Verification: Maximum 5 attempts per 15 minutes
• SMS Code Requests: Maximum 3 codes per 15 minutes
• Account Lock: Account may be locked after too many failed attempts

Code Expiration

• SMS Codes: Valid for 10 minutes
• TOTP Codes: Valid for current 30-second window (with 2-window tolerance for clock drift)
• Backup Codes: No expiration (but one-time use only)

Encryption

• TOTP Secrets: Encrypted at rest using AES-256-GCM
• Backup Codes: Hashed before storage (SHA-256)
• Phone Numbers: Stored in database (for SMS MFA)

Troubleshooting

Can't Access Authenticator App

• Use Backup Code: Check the "Use backup code instead" option during login
• Regenerate Codes: If you've lost backup codes, you'll need to disable MFA (requires password) and re-enable

Not Receiving SMS Codes

• Check Phone Number: Verify it's in E.164 format (e.g., +14165551234)
• Check System Phone: Ensure administrator has configured system phone number
• Rate Limiting: Wait 15 minutes if you've requested too many codes
• Contact Support: If issues persist

Lost Backup Codes

• Regenerate: Use the "Regenerate Backup Codes" option (requires password)
• Disable MFA: If you can't access your account, contact support to disable MFA

Clock Sync Issues (TOTP)

• Check Device Time: Ensure your device's clock is synchronized
• Tolerance Window: System allows 2 time-step window (±60 seconds) for clock drift
• Manual Entry: Try entering the code manually if scanning QR code fails

Best Practices

1. Enable MFA: Especially important for admin accounts
2. Save Backup Codes: Store them securely (password manager, encrypted file)
3. Use Authenticator App: More secure than SMS (not vulnerable to SIM swapping)
4. Keep Codes Secure: Don't share backup codes or MFA secrets
5. Regular Review: Periodically check MFA status and regenerate codes if needed
6. Multiple Devices: Consider using a cloud-based authenticator (Authy, 1Password) for backup

Admin Configuration

System Phone Number

For SMS MFA to work, administrators must configure a system phone number:

1. Navigate to Admin Settings → General tab
2. Find System Phone Number field
3. Enter phone number in E.164 format (e.g., +14165551234)
4. Save configuration

Fallback: If not configured in admin settings, system uses TELNYX_PHONE_NUMBER environment variable.

API Endpoints

MFA Management

• GET /api/auth/mfa/status - Get current MFA status
• POST /api/auth/mfa/enroll/totp - Start TOTP enrollment
• POST /api/auth/mfa/enroll/totp/verify - Complete TOTP enrollment
• POST /api/auth/mfa/enroll/sms - Start SMS enrollment
• POST /api/auth/mfa/enroll/sms/verify - Complete SMS enrollment
• POST /api/auth/mfa/disable - Disable MFA (requires password)
• POST /api/auth/mfa/regenerate-backup-codes - Generate new backup codes

Login Flow

• POST /api/auth/login - Returns requiresMFA: true if MFA enabled
• POST /api/auth/mfa/verify - Verify MFA code during login

Related Documentation

• Profile Management - User profile settings
• Security Practices - Security docs overview
• Password Reset - Password reset functionality