Skip to content

Two Factor Authentication

Jump to bottom
Marc Pope edited this page Feb 3, 2026 · 1 revision

Two-Factor Authentication

BBS supports TOTP-based two-factor authentication (2FA) for enhanced account security. Users can enable 2FA on their accounts, and admins can require all users to use 2FA.

What is 2FA?

Two-factor authentication adds an extra layer of security beyond just a password:

  1. Something you know: Your password
  2. Something you have: Your phone with an authenticator app

Even if someone obtains your password, they cannot log in without access to your authenticator app.

Supported Authenticator Apps

BBS uses the TOTP (Time-based One-Time Password) standard, compatible with:

  • Google Authenticator (iOS, Android)
  • Authy (iOS, Android, Desktop)
  • Microsoft Authenticator (iOS, Android)
  • 1Password (iOS, Android, Desktop)
  • LastPass Authenticator (iOS, Android)
  • Any TOTP-compatible app

Setting Up 2FA

Enabling 2FA on Your Account

  1. Log in to BBS
  2. Navigate to Profile (click username in top-right → Profile)
  3. Click the Two-Factor Authentication tab
  4. Click Enable 2FA button

Screenshot: Profile page showing 2FA tab with Enable button

Scanning the QR Code

  1. A QR code is displayed on screen
  2. Open your authenticator app (e.g., Google Authenticator)
  3. Tap Add Account or Scan QR Code
  4. Point your phone camera at the QR code
  5. Account is added to your authenticator app with name: BBS - {your_username}

Screenshot: 2FA setup page showing QR code

Alternative: Manual Entry

If you cannot scan the QR code:

  1. Click Can't scan the code? link
  2. Copy the secret key displayed
  3. In your authenticator app, choose Enter Key Manually
  4. Enter:
    • Account name: BBS - {your_username}
    • Secret key: (paste the copied key)
    • Type: Time-based
  5. Add the account

Verifying 2FA Setup

  1. Your authenticator app now shows a 6-digit code that changes every 30 seconds
  2. Enter the current 6-digit code in the Verification Code field
  3. Click Verify and Enable
  4. If correct, 2FA is enabled and recovery codes are displayed

Screenshot: 2FA verification code entry field

If verification fails:

  • Wait for the code to refresh (codes expire every 30 seconds)
  • Try the new code
  • Ensure your phone's time is accurate (TOTP requires synchronized clocks)

Saving Recovery Codes

After enabling 2FA, you are shown 10 recovery codes:

RECOVERY CODES (Save these in a safe place)

1. A3F9-2K7L-8M4N-P5Q6
2. B7C8-D9E1-F2G3-H4J5
3. K6L7-M8N9-P1Q2-R3S4
4. T5U6-V7W8-X9Y1-Z2A3
5. B4C5-D6E7-F8G9-H1J2
6. K3L4-M5N6-P7Q8-R9S1
7. T2U3-V4W5-X6Y7-Z8A9
8. B1C2-D3E4-F5G6-H7J8
9. K9L1-M2N3-P4Q5-R6S7
10. T8U9-V1W2-X3Y4-Z5A6

IMPORTANT:

  • Save these codes in a secure location (password manager, printed copy in safe)
  • Each code can only be used once
  • If you lose access to your authenticator app, these codes are the only way to log in
  • Without recovery codes, you will be locked out and require admin intervention

Screenshot: Recovery codes display with copy and download buttons

Saving Options:

  • Copy to Clipboard: Copy codes to paste into password manager
  • Download as Text: Download codes as a .txt file
  • Print: Print codes and store in secure location

2FA Setup Complete

Once verified, you see a confirmation message:

"Two-factor authentication is now enabled on your account. You will be prompted for a 6-digit code each time you log in."

Screenshot: 2FA enabled confirmation message

Logging In with 2FA

Login Process

When 2FA is enabled, the login process has an extra step:

  1. Navigate to BBS login page
  2. Enter Username and Password
  3. Click Log In
  4. 2FA Code Prompt appears
  5. Open your authenticator app
  6. Enter the current 6-digit code
  7. Click Verify
  8. If correct, you are logged in

Screenshot: 2FA code prompt after password entry

Code Requirements:

  • 6 digits
  • Valid for 30 seconds
  • New code generated every 30 seconds
  • Case-insensitive (numbers only)

If Code is Rejected:

  • Wait for next code (30-second window)
  • Try again with fresh code
  • Verify your phone's time is accurate
  • Use a recovery code if authenticator is unavailable

Using Recovery Codes

If you lose access to your authenticator app (lost phone, app deleted, etc.), use a recovery code to log in.

Login with Recovery Code

  1. Log in with username and password
  2. At the 2FA code prompt, click Use a recovery code
  3. Enter one of your saved recovery codes
  4. Click Verify
  5. You are logged in

Screenshot: Recovery code entry option on 2FA prompt

After Using a Recovery Code:

  • The recovery code is immediately invalidated (cannot be reused)
  • You have 9 codes remaining (or fewer if already used)
  • Consider regenerating recovery codes or re-enabling 2FA with a new device

Managing 2FA Settings

Viewing 2FA Status

  1. Go to Profile → Two-Factor Authentication tab
  2. Status shows:
    • Enabled with green badge
    • Date 2FA was enabled
    • Number of remaining recovery codes

Screenshot: Profile 2FA tab showing enabled status

Regenerating Recovery Codes

If you've used several recovery codes or lost the original list:

  1. Go to Profile → Two-Factor Authentication tab
  2. Click Regenerate Recovery Codes
  3. Confirm regeneration
  4. All old recovery codes are invalidated
  5. New set of 10 recovery codes is displayed
  6. Save the new codes securely

Screenshot: Regenerate recovery codes button and confirmation

When to Regenerate:

  • Lost the original recovery codes
  • Used most of your recovery codes
  • Security best practice (annually)
  • After a security incident

Disabling 2FA

To turn off 2FA on your account:

  1. Go to Profile → Two-Factor Authentication tab
  2. Click Disable 2FA
  3. Enter your current password (required for security)
  4. Confirm disabling
  5. 2FA is disabled, recovery codes are deleted

Screenshot: Disable 2FA button with password confirmation

Important:

  • Requires password confirmation (prevents unauthorized disabling)
  • All recovery codes are permanently deleted
  • You can re-enable 2FA at any time (new QR code and recovery codes will be generated)
  • If "Force 2FA" is enabled by admin, you cannot disable 2FA

Force 2FA (Admin)

Admins can require all users to enable 2FA.

Enabling Force 2FA

  1. Navigate to Settings → General tab
  2. Check Force Two-Factor Authentication
  3. Click Save

Screenshot: Settings → General tab with Force 2FA checkbox

Behavior When Enabled:

  • All users must enable 2FA on next login
  • Users without 2FA are redirected to 2FA setup page after password entry
  • Users cannot access BBS until 2FA is configured
  • Existing sessions remain valid (applies on next login)
  • Admins are also required to use 2FA (no exceptions)

Enforcement:

  • Users cannot skip or bypass 2FA setup
  • Users cannot disable 2FA while Force 2FA is enabled
  • To disable 2FA, admin must first uncheck Force 2FA in Settings

User Experience with Force 2FA

First Login After Force 2FA is Enabled:

  1. User logs in with username and password
  2. Instead of reaching the dashboard, they see: "Two-factor authentication is required. Please set it up now."
  3. QR code is displayed for scanning
  4. User follows normal 2FA setup process
  5. After verifying and saving recovery codes, user can access BBS

Screenshot: Forced 2FA setup page

Subsequent Logins:

  • Normal 2FA login process (password + 6-digit code)

Emergency 2FA Reset (Admin CLI)

If a user is locked out (lost authenticator and recovery codes), admins can reset 2FA via command line.

Resetting 2FA for a User

Command:

sudo /var/www/bbs/bin/bbs-2fa-reset <username>

Example:

sudo /var/www/bbs/bin/bbs-2fa-reset john.smith

Process:

  1. SSH to BBS server
  2. Run the command above (replace <username> with actual username)
  3. Script disables 2FA for the specified user
  4. Script deletes recovery codes
  5. User can now log in with password only

Output:

2FA has been disabled for user: john.smith
The user can now log in with their password.
They can re-enable 2FA from their Profile page.

After Reset:

  • User logs in with password only (no 2FA prompt)
  • User should immediately re-enable 2FA from Profile page
  • If Force 2FA is enabled, user will be prompted to set up 2FA on next login

Security Considerations:

  • Only use for genuine lockout situations
  • Verify user identity before resetting (phone call, email, in person)
  • User should re-enable 2FA immediately after regaining access
  • Log the emergency reset for audit purposes

Best Practices

For Users

  • Save Recovery Codes: Store in password manager or print and keep in secure location
  • Backup Authenticator: Use an app that supports cloud backup (Authy) or export codes to multiple devices
  • Accurate Time: Ensure your phone's clock is accurate (TOTP requires time synchronization)
  • Secure Authenticator: Use a passcode or biometric lock on your phone
  • Test Recovery: Verify you can access recovery codes before you need them

For Admins

  • Enable Force 2FA: Require 2FA for all users in production environments
  • Document Emergency Process: Define procedure for 2FA resets (who approves, how to verify identity)
  • Monitor Adoption: Check which users have enabled 2FA (admin user list shows 2FA status)
  • Lead by Example: Admins should enable 2FA on their own accounts first
  • Communicate: Notify users before enabling Force 2FA (give time to prepare)

Security

  • Never Share Codes: Never share your 6-digit codes or recovery codes with anyone
  • Beware Phishing: BBS will never ask for your 2FA code via email or support ticket
  • Regenerate Periodically: Regenerate recovery codes annually as a security practice
  • Rotate on Breach: If you suspect your account is compromised, disable and re-enable 2FA (generates new secret)

Troubleshooting

2FA Code Always Rejected

Possible Causes:

  • Phone clock is out of sync
  • Entering code after 30-second window expires
  • Wrong account in authenticator app

Solutions:

  • Sync Phone Clock:
    • iOS: Settings → General → Date & Time → Set Automatically
    • Android: Settings → Date & Time → Automatic date & time
  • Try Fresh Code: Wait for code to refresh, enter immediately
  • Verify Account: Ensure you're viewing the correct BBS account in authenticator

Lost Authenticator App

Solution: Use a recovery code

  1. Click "Use a recovery code" on login 2FA prompt
  2. Enter one of your saved recovery codes
  3. Log in
  4. Immediately go to Profile → 2FA → Disable 2FA (using password)
  5. Re-enable 2FA with new device/app
  6. Save new recovery codes

If Recovery Codes Also Lost:

  • Contact your BBS admin
  • Admin runs: sudo /var/www/bbs/bin/bbs-2fa-reset <your_username>
  • Log in with password only
  • Re-enable 2FA and save recovery codes

Cannot Scan QR Code

Solutions:

  1. Use Manual Entry:

    • Click "Can't scan the code?" link
    • Copy the secret key
    • Manually add to authenticator app

  2. Zoom In: If QR code is too small, zoom browser window

  3. Different Device: Open BBS on computer, scan with phone

  4. Screenshot: Take screenshot, display on different screen to scan

2FA Enabled But No Prompt on Login

Possible Causes:

  • Already logged in (active session)
  • 2FA not fully enabled (verification step incomplete)

Solutions:

  • Log out completely, log in again
  • Check Profile → 2FA tab to confirm 2FA is enabled
  • Clear browser cookies, try again

Force 2FA Enabled, Cannot Disable

Cause: Admin has enabled "Force 2FA" in settings

Solution:

  • Individual users cannot disable 2FA while Force 2FA is active
  • Admin must first disable Force 2FA in Settings → General
  • Then users can disable 2FA from their profiles

Emergency Reset Doesn't Work

Command Not Found:

sudo /var/www/bbs/bin/bbs-2fa-reset <username>

Solutions:

  • Verify file exists: ls -l /var/www/bbs/bin/bbs-2fa-reset
  • Ensure you're on the BBS server (not client machine)
  • Check file permissions: should be executable
  • If missing, update BBS: sudo /var/www/bbs/bin/bbs-update

User Not Found:

  • Verify username is correct (case-sensitive)
  • Check user exists: sudo mysql -e "SELECT username FROM bbs.users;"

Security Considerations

TOTP Algorithm

BBS uses industry-standard TOTP (RFC 6238):

  • Algorithm: HMAC-SHA1
  • Time Step: 30 seconds
  • Code Length: 6 digits
  • Secret Length: 160 bits (32 characters base32)

Secret Storage

  • 2FA secrets are stored in the database encrypted with the APP_KEY
  • Secrets are never displayed after initial setup
  • Disabling 2FA permanently deletes the secret

Recovery Code Storage

  • Recovery codes are hashed (bcrypt) before storage
  • Cannot be retrieved in plain text (like passwords)
  • Each code is single-use and invalidated after use

Brute Force Protection

  • Failed 2FA attempts count toward rate limiting (5 attempts → 10-minute lockout)
  • Separate counter from password login attempts
  • Both password and 2FA must succeed to bypass rate limit

Session Security

  • 2FA is checked only at login, not for every request
  • Sessions use secure, httponly cookies
  • Session hijacking protection via IP and user-agent checks

Related Documentation

📖 User Manual

Getting Started

Using BBS

Monitoring

Administration

Reference

Clone this wiki locally