Skip to content

Two-Factor Authentication Setup

Guide to setting up 2FA (TOTP) for administrator accounts.

Overview

Two-factor authentication adds security by requiring: 1. Something you know - Password 2. Something you have - Phone with authenticator app

Supported: TOTP (Time-based One-Time Password) Compatible apps: Google Authenticator, Authy, Microsoft Authenticator, 1Password

Enabling 2FA

Via Web Interface

  1. Navigate: Profile → Security → Two-Factor Authentication
  2. Click "Enable 2FA"
  3. Scan QR code with authenticator app
  4. Enter test code from app (6 digits)
  5. Save backup codes (important!)
  6. Click "Activate"

2FA now required for all future logins.

Via Command Line (Admin)

Enable for user: 

sudo mb-2fa-enable --email user@example.com

Displays: - QR code (ASCII art) - Secret key (manual entry) - Backup codes

User must scan QR code and verify.

Using 2FA

Login flow: 1. Enter email and password 2. Click "Login" 3. Enter 6-digit code from authenticator app 4. Click "Verify" 5. Access granted

Code refreshes every 30 seconds - use current code.

Backup Codes

Purpose: Access if phone lost/broken

When enabled: - 10 backup codes generated - Each code single-use - Save in secure location

Using backup code: 1. Login with email/password 2. Click "Use backup code" 3. Enter one backup code 4. Access granted 5. Code is consumed

Regenerate codes: Profile → Security → 2FA → Generate New Backup Codes

Disabling 2FA

Via web interface: 1. Profile → Security → 2FA 2. Click "Disable 2FA" 3. Enter current password 4. Enter current 2FA code 5. Confirm disable

Via CLI (admin emergency): 

sudo mb-2fa-disable --email user@example.com

Security

Only disable 2FA in emergencies. Re-enable immediately after access restored.

Troubleshooting

Invalid Code

Common causes: 1. Time sync issue - Authenticator app and server must have accurate time - Check phone time settings - Enable auto-sync

  1. Old code
  2. Codes refresh every 30 seconds

  3. Wait for new code

  4. Wrong account

  5. Multiple accounts in authenticator?
  6. Verify correct account selected

Lost Phone

Use backup code: 1. Click "Use backup code" at login 2. Enter one of your backup codes

If no backup codes: - Contact another admin to disable your 2FA - Or use CLI access: sudo mb-2fa-disable --email user@example.com

Time Sync Issues

Verify server time: 

date
timedatectl

Sync time: 

sudo timedatectl set-ntp true
sudo systemctl restart systemd-timesyncd

Check phone time: - Settings → Date & Time - Enable "Automatic date & time"

Best Practices

Setup

  1. Use reputable authenticator app
  2. Google Authenticator
  3. Authy (with cloud backup)
  4. Microsoft Authenticator

  5. 1Password

  6. Save backup codes securely

  7. Print and store in safe
  8. Password manager

  9. Encrypted file

  10. Label accounts clearly

  11. Add label in authenticator app
  12. Include "Mailborder - example.com"

Usage

  1. Enable for all admin accounts
  2. Require for super admins (mandatory)
  3. Test backup codes after setup
  4. Regenerate backup codes if used

Recovery

  1. Keep backup codes accessible
  2. Document recovery procedure
  3. Maintain list of admin contacts
  4. Have CLI access method

Enforcing 2FA

Require for all users:

Settings → Authentication → Two-Factor Authentication - Check "Require 2FA for all users" - Set grace period: 7 days

Users without 2FA: - Prompted to set up on next login - Cannot access system after grace period

Exceptions: - Service accounts (API keys instead) - Emergency break-glass account (document carefully)

CLI Commands

Enable: 

sudo mb-2fa-enable --email user@example.com

Disable: 

sudo mb-2fa-disable --email user@example.com

Verify code: 

sudo mb-2fa-verify --email user@example.com --code 123456

Generate backup codes: 

sudo mb-2fa-backup-codes --email user@example.com

List users with 2FA: 

sudo mb-2fa-list

See Also