Skip to content

virocean/fossbilling-2fa-email

BranchesTags

Repository files navigation

FOSSBilling Two-Factor Authentication Extension

License FOSSBilling PHP

Email-based Two-Factor Authentication (2FA) extension for FOSSBilling. Adds an extra layer of security to your billing system by requiring users to verify their identity with a code sent to their email after entering their password.

🔐 Features

  • Email-Based Verification: Sends 6-digit codes via email
  • Branded Emails: Uses FOSSBilling's template system with company logo and signature
  • Login Interception: Seamlessly integrates into existing login workflow
  • Rate Limiting: Maximum 3 verification attempts to prevent brute-force attacks
  • Code Expiration: Codes automatically expire after 10 minutes
  • User Control: Clients can enable/disable 2FA for their own accounts
  • Admin Management: Administrators can manage 2FA for all users
  • Enforcement Policies: Optional mandatory 2FA for admins and/or clients
  • Statistics Dashboard: Track 2FA usage and successful verifications
  • Session Security: Partial authentication state prevents session hijacking
  • Database Cleanup: Automatic cleanup of expired codes via cron

📋 Requirements

  • FOSSBilling: Version 0.6 or higher
  • PHP: Version 7.4 or higher
  • PHP Extensions: cURL, PDO, mbstring
  • Database: MySQL 5.7+ or MariaDB 10.3+
  • SMTP: Configured email system in FOSSBilling
  • Email Access: Users must have access to their email accounts

📦 Installation

Method 1: Manual Installation

  1. Download the extension

    cd /var/www/fossbilling/bb-modules/
git clone https://github.com/AXYNUK/fossbilling-2fa-email.git Twofactor

  2. Set permissions

    chown -R www-data:www-data Twofactor
chmod -R 755 Twofactor

  3. Activate extension

    • Login to FOSSBilling admin panel
    • Navigate to Extensions → Available Extensions
    • Find "Two-Factor Authentication (Email)"
    • Click Activate

  4. Verify installation

    • Database tables twofactor_codes, twofactor_settings, and extension_meta should be created
    • Navigate to System → Two-Factor Authentication to configure

Method 2: FOSSBilling Extension Directory

  1. Navigate to Extensions → Extension Directory
  2. Search for "Two-Factor Authentication"
  3. Click Install
  4. Click Activate

⚙️ Configuration

Admin Settings

Navigate to Admin Panel → System → Two-Factor Authentication

Basic Settings

  • Enable Extension: Master switch for 2FA functionality
  • Code Expiry Time: How long codes remain valid (default: 10 minutes)
  • Maximum Attempts: Number of code entry attempts before lockout (default: 3)

Enforcement Policies

  • Require 2FA for Admins: Makes 2FA mandatory for all administrators
  • Require 2FA for Clients: Makes 2FA mandatory for all clients

⚠️ Warning: Enabling enforcement may lock out users without email access. Test thoroughly before enabling in production.

Client Settings

Clients can manage their own 2FA:

  1. Login to client area
  2. Navigate to Account → Two-Factor Authentication
  3. Click Enable 2FA to activate
  4. Click Disable 2FA to deactivate

🔄 How It Works

Login Flow

┌─────────────────┐
│ Enter Username  │
│   & Password    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Credentials   │
│    Validated    │
└────────┬────────┘
         │
         ▼
   ┌─────────────┐
   │ 2FA Enabled?│
   └──────┬──────┘
          │
    YES───┴───NO
     │         │
     ▼         ▼
┌─────────┐ ┌──────────┐
│ Send    │ │ Direct   │
│ Code    │ │ Access   │
│ Email   │ │ Dashboard│
└────┬────┘ └──────────┘
     │
     ▼
┌─────────────────┐
│ Verification    │
│     Page        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Code     │
│  from Email     │
└────────┬────────┘
         │
         ▼
   ┌──────────┐
   │ Valid?   │
   └────┬─────┘
        │
   YES──┴──NO
    │       │
    ▼       ▼
┌────────┐ ┌────────┐
│Access  │ │ Error  │
│Granted │ │Try Again│
└────────┘ └───┬────┘
               │
               ▼
        ┌──────────────┐
        │Max 3 Attempts│
        │Then Re-login │
        └──────────────┘

Email Template

The 2FA email automatically includes:

  • Company logo (from FOSSBilling settings)
  • Company name
  • 6-digit verification code (prominently displayed)
  • Expiration warning (10 minutes)
  • Security instructions
  • Company signature (if configured)

Example:

┌─────────────────────────────────────┐
│        [COMPANY LOGO]               │
│                                     │
│  Two-Factor Authentication          │
│                                     │
│  Hello John Doe,                    │
│                                     │
│  Your verification code:            │
│                                     │
│  ┌─────────────┐                   │
│  │   123456    │                   │
│  └─────────────┘                   │
│                                     │
│  ⚠️ Expires in 10 minutes           │
│                                     │
│  Didn't request this?               │
│  Contact support immediately.       │
└─────────────────────────────────────┘

🔒 Security Features

Cryptographic Code Generation

Codes are generated using PHP's random_int() function, which provides cryptographically secure random numbers:

$code = random_int(100000, 999999); // 6-digit secure code

Rate Limiting

The system implements strict rate limiting:

  • Maximum 3 attempts per verification session
  • After 3 failed attempts, user must re-login
  • Attempt counter stored in database
  • Session cleared on max attempts

Code Expiration

  • Codes expire 10 minutes after generation (configurable)
  • Expiration time stored in database
  • Expired codes automatically rejected
  • Cleanup cron removes old codes

Session Security

During 2FA verification:

  • No session established until code verified
  • Temporary session variables:
    • twofactor_pending: Boolean flag
    • twofactor_user_id: User ID (not username)
    • twofactor_user_type: 'admin' or 'client'
    • twofactor_attempts: Attempt counter
  • Full session only granted after successful verification

Email Privacy

Email addresses are masked in UI:

  • john.doe@example.com → jo****e@example.com
  • Prevents email address leakage

📊 Admin Dashboard

Statistics Panel

Track 2FA usage:

  • Codes Sent Today: Number of 2FA codes sent
  • Successful Logins Today: Completed 2FA verifications
  • Admins with 2FA: Count of admins using 2FA
  • Clients with 2FA: Count of clients using 2FA

Admin Management

  • View all administrators with 2FA status
  • Enable/disable 2FA for specific admins
  • Override user preferences with enforcement policies

Maintenance

  • Cleanup Expired Codes: Manually trigger database cleanup
  • Automatic cleanup runs daily via cron

🧪 Testing

Automated Test Suite

Run the comprehensive test suite:

cd /var/www/fossbilling/bb-modules/Twofactor/
php test_twofactor.php

Expected output:

========================================
FOSSBilling 2FA Extension Test Suite
========================================

Running: Test 1: Generate 6-digit verification code
  ✓ PASSED

[... 15 tests ...]

========================================
TEST RESULTS
========================================
Total Tests: 15
Passed: 15
Failed: 0
Success Rate: 100.00%
========================================

✓ ALL TESTS PASSED!

Extension is ready for production use.

Manual Testing

See TEST_PLAN.md for comprehensive integration test cases.

🐛 Troubleshooting

Email Not Received

  1. Check SMTP Settings

    • Navigate to Admin → Settings → Email
    • Verify SMTP credentials are correct
    • Test email sending

  2. Check Spam Folder

    • 2FA emails may be flagged as spam
    • Add sender to whitelist

  3. Check Email Logs

    • Review FOSSBilling email logs
    • Check for email sending errors

Code Not Accepted

  1. Check Expiration

    • Codes expire after 10 minutes
    • Request a new code if expired

  2. Check Attempts

    • Maximum 3 attempts per session
    • Re-login if attempts exceeded

  3. Check Code Entry

    • Ensure all 6 digits entered
    • No spaces or special characters

Cannot Login (2FA Locked Out)

For Admins:

  1. Access database directly
  2. Disable 2FA for user: 
    UPDATE twofactor_settings 
SET enabled = 0 
WHERE user_id = [USER_ID] AND user_type = 'admin';
  3. User can now login without 2FA

For Clients:

Contact support to disable 2FA from admin panel.

Extension Not Activating

  1. Check PHP Requirements

    php -v  # Should be 7.4+
php -m | grep -E 'curl|pdo|mbstring'

  2. Check Permissions

    ls -la /var/www/fossbilling/bb-modules/Twofactor
# Should be owned by web server user

  3. Check Error Logs

    tail -f /var/log/fossbilling/error.log

📚 API Reference

Guest API (No Authentication Required)

twofactor_verify

Verify a 2FA code.

Parameters:

  • code (string, required): 6-digit verification code

Returns:

{
  "success": true,
  "redirect": "/admin"
}

twofactor_resend

Resend verification code.

Parameters: None

Returns:

{
  "success": true,
  "message": "A new verification code has been sent to your email."
}

Client API (Client Authentication Required)

twofactor_is_enabled

Check if 2FA is enabled for current client.

Parameters: None

Returns:

{
  "enabled": true
}

twofactor_enable

Enable 2FA for current client.

Parameters: None

Returns: true

twofactor_disable

Disable 2FA for current client.

Parameters: None

Returns: true

Admin API (Admin Authentication Required)

twofactor_get_settings

Get extension settings.

Parameters: None

Returns:

{
  "enabled": "1",
  "code_expiry_minutes": "10",
  "max_attempts": "3",
  "enforce_for_admins": "0",
  "enforce_for_clients": "0"
}

twofactor_update_settings

Update extension settings.

Parameters:

  • enabled (string): "1" or "0"
  • code_expiry_minutes (string): Minutes (1-60)
  • max_attempts (string): Attempts (1-10)
  • enforce_for_admins (string): "1" or "0"
  • enforce_for_clients (string): "1" or "0"

Returns: true

twofactor_enable_for_admin

Enable 2FA for a specific admin.

Parameters:

  • admin_id (int, required): Admin ID

Returns: true

twofactor_disable_for_admin

Disable 2FA for a specific admin.

Parameters:

  • admin_id (int, required): Admin ID

Returns: true

twofactor_get_admin_statuses

Get 2FA status for all admins.

Parameters: None

Returns:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "twofactor_enabled": 1
  }
]

twofactor_get_statistics

Get 2FA statistics.

Parameters: None

Returns:

{
  "codes_sent_today": 15,
  "successful_verifications_today": 12,
  "clients_with_2fa": 45,
  "admins_with_2fa": 3
}

twofactor_cleanup_expired_codes

Cleanup expired verification codes.

Parameters: None

Returns:

{
  "success": true,
  "deleted_count": 23
}

🔧 Development

Architecture

Twofactor/
├── Api/
│   ├── Admin.php       # Admin API endpoints
│   ├── Client.php      # Client API endpoints
│   └── Guest.php       # Public API endpoints
├── Controller/
│   ├── Admin.php       # Admin verification controller
│   └── Client.php      # Client verification controller
├── html_admin/
│   └── mod_twofactor_admin_index.html.twig
├── html_client/
│   ├── mod_twofactor_client_index.html.twig
│   └── mod_twofactor_verify.html.twig
├── html_email/
│   ├── mod_twofactor_verification.html.twig
│   └── mod_twofactor_verification.txt.twig
├── bootstrap.php       # Event hook registration
├── EventListener.php   # Login interception hooks
├── Service.php         # Core 2FA logic
├── install.php         # Database installation
├── uninstall.php       # Database cleanup
└── manifest.json       # Extension metadata

Database Schema

twofactor_codes

Stores temporary verification codes.

Column Type Description
id INT(11) Primary key
user_id INT(11) User ID
user_type ENUM('client','admin') User type
code VARCHAR(6) Verification code
attempts INT(2) Verification attempts
created_at DATETIME Creation timestamp
expires_at DATETIME Expiration timestamp
verified_at DATETIME Verification timestamp
ip_address VARCHAR(45) Client IP address

twofactor_settings

Stores per-user 2FA preferences.

Column Type Description
id INT(11) Primary key
user_id INT(11) User ID
user_type ENUM('client','admin') User type
enabled TINYINT(1) 2FA enabled flag
created_at DATETIME Creation timestamp
updated_at DATETIME Update timestamp

extension_meta

Stores extension configuration.

Column Type Description
id INT(11) Primary key
extension VARCHAR(255) Extension name
meta_key VARCHAR(255) Setting key
meta_value TEXT Setting value
created_at DATETIME Creation timestamp
updated_at DATETIME Update timestamp

📄 License

This extension is licensed under the Apache License 2.0.

Copyright 2025 AXYNUK

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

See LICENSE file for full text.

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Code Style

  • Follow PSR-12 coding standards
  • Add PHPDoc comments to all methods
  • Write unit tests for new features
  • Update documentation

🆘 Support

🏆 Credits

Developed by: AXYNUK
For: FOSSBilling Community
Year: 2025

📝 Changelog

Version 1.0.0 (2025-11-24)

Initial release:

  • ✅ Email-based 2FA with branded templates
  • ✅ Login interception for admin and client
  • ✅ Rate limiting (3 attempts max)
  • ✅ Code expiration (10 minutes)
  • ✅ Admin management dashboard
  • ✅ Client self-service settings
  • ✅ Enforcement policies
  • ✅ Statistics tracking
  • ✅ Comprehensive test suite
  • ✅ Full documentation

🔮 Roadmap

Future enhancements planned:

  • SMS verification option
  • TOTP (Google Authenticator) support
  • Backup codes
  • Trusted device remembering
  • IP-based 2FA bypass
  • Webhook notifications
  • Advanced analytics
  • Multi-language support

Made with ❤️ by AXYNUK for the FOSSBilling community

About

Email-based Two-Factor Authentication extension for FOSSBilling. Adds an extra layer of security by requiring users to enter a verification code sent to their email after login.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages