Skip to content
BranchesTags

Repository files navigation

Dolibarr TOTP 2FA 🔐

Free & Open Source Two-Factor Authentication for Dolibarr

Dolibarr License PHP TOTP

Add enterprise-grade Two-Factor Authentication (2FA) to your Dolibarr installation - completely free and open source.

🎯 Features

  • TOTP Standard - RFC 6238 compliant Time-based One-Time Passwords
  • Universal Compatibility - Works with Google Authenticator, Apple Passwords, Authy, Microsoft Authenticator, etc.
  • QR Code Setup - Scan and configure in seconds
  • User Self-Service - Each user manages their own 2FA settings
  • Backup Codes - Emergency access codes for recovery
  • Trusted Devices - Skip 2FA on trusted devices for configurable days (1-90)
  • IP Blocking - Block suspicious IPs manually, view login attempts and statistics
  • Login Logging - Track all login attempts (success, failed 2FA, blocked)
  • Optional Enforcement - Admin can make 2FA mandatory for specific users or groups
  • Multi-Company Support - Works with Dolibarr Multi-Company module
  • Secure - Industry-standard TOTP with 30-second rotating codes

🔐 How It Works

  1. User enables 2FA in their profile settings
  2. Scan QR code with authenticator app (Google Auth, Apple Passwords, etc.)
  3. Enter 6-digit code after normal login
  4. Done! Account is now protected with 2FA

📦 Installation

# 1. Clone into custom modules directory
cd /var/www/dolibarr/htdocs/custom
git clone https://github.com/Gerrett84/dolibarr-totp-2fa.git totp2fa

# 2. Set permissions
chown -R www-data:www-data totp2fa
chmod -R 755 totp2fa

# 3. Activate in Dolibarr
# Setup → Modules → TOTP 2FA → Activate

Requirements: Dolibarr 21.0+, PHP 7.4+, MySQL/MariaDB

🚀 Quick Start

For Users

  1. Go to User Profile → 2FA
  2. Click Enable 2FA
  3. Scan QR code with your authenticator app
  4. Enter verification code
  5. Save backup codes in a safe place

For Administrators

  1. Activate the module in Setup → Modules
  2. Configure settings in Setup → TOTP 2FA
  3. Optionally enforce 2FA for specific users/groups

🔧 Compatible Authenticator Apps

  • ✅ Google Authenticator (iOS, Android)
  • ✅ Apple Passwords (iOS 15+, macOS Monterey+)
  • ✅ Microsoft Authenticator (iOS, Android)
  • ✅ Authy (iOS, Android, Desktop)
  • ✅ 1Password (iOS, Android, Desktop)
  • ✅ Bitwarden (iOS, Android, Desktop)
  • ✅ Any RFC 6238 compliant TOTP app

📋 Roadmap

v1.4.5 (Current Release) ✅

  • Fix: 2FA field misaligned on the login form – The input sat shifted to the left and rendered narrower than the username and password fields above it, on both mobile and desktop. Dolibarr's theme styles the login inputs by id (.login_table input#username, input#password, input#securitycode) rather than by class, so padding, margins and font-size were never inherited by a field with a different id. The theme's declarations are now mirrored onto #totp_code, and the 2FA row is cloned from the username row so it picks up every class and attribute the theme relies on.
  • Fix: shield icon clipped – fa-shield-alt is a wider glyph than fa-user/fa-key; it is now centred inside the theme's 14px icon box and allowed to render past it instead of being cut off on the right.

Note: The mirrored CSS in login_extension.php reproduces values from theme/eldy/global.inc.php. If a future Dolibarr release changes the login field spacing, that block needs to be updated to match.

v1.4.4 ✅

  • Fix: 2FA-Feld erscheint nicht auf HTTPS-Installationen – Login-Injektion von jQuery .clone() auf Vanilla-JS createElement umgeschrieben. Der Clone kopierte stillschweigend den eingebetteten <script nonce="..."> des Passwort-Toggle-Handlers mit; auf HTTPS-Seiten schlug die Injektion damit lautlos fehl. Das Feld erscheint nun immer korrekt.

v1.4.3 ✅

  • Security: Remaining XSS fixes – ip_address and user_agent values in Stats tab and Login Attempts tab now correctly escaped
  • Security: Trusted-device fingerprint – Device ID cookie (totp2fa_did) added as unforgeable component of device hash (HttpOnly, Secure, SameSite=Lax)
  • Security: Open redirect prevention – urlfrom parameter only accepts relative paths starting with /
  • Security: Debug pages access-restricted – debug_hooks.php and test_hook_call.php now require admin login (403 for non-admins)
  • Dolibarr v23 compatibility – isModEnabled() used instead of deprecated $conf->totp2fa->enabled

v1.4.2 ✅

  • Fix Dolibarr v23 Compatibility - 2FA tab now correctly appears in user profile on Dolibarr v23+

v1.4.1 ✅

  • Fix CSRF Token Error - Disable/Regenerate buttons now work with MAIN_SECURITY_CSRF_WITH_TOKEN=2 (fixes #4)

v1.4 ✅

  • IP Blocking - Manually block suspicious IP addresses
  • Login Attempt Logging - Track all login attempts with IP, browser, timestamp
  • IP Management Admin Page - Three tabs: Login Attempts, IP Blacklist, Statistics
  • Top Failing IPs - View and block top failing IPs with one click
  • Purge Old Logs - Clean up old login attempt records
  • Menu only visible in Setup section (not permanently)

v1.3.1 ✅

  • Dolibarr 21 Support - Lowered minimum version requirement
  • Multi-Company Support - Confirmed working with Multi-Company module (thanks @fefed22!)

v1.3 ✅

  • Trust Renewal - Enter code on trusted device to renew trust period
  • Show remaining trust days on login page
  • Skip button for trusted devices (proceed without code)
  • Improved UX for trusted device handling

v1.2 ✅

  • Trusted Devices - Skip 2FA for trusted devices (configurable 1-90 days)
  • Admin-only setting to enable/disable trusted devices
  • Detailed trusted devices overview in admin panel
  • Automatic device detection (Windows, Mac, Linux, iOS, Android)

v1.1 ✅

  • Email notifications (2FA enabled/disabled, 3 failed attempts warning)
  • Activity log for all 2FA events
  • Admin can disable 2FA for users (emergency)
  • Backup codes can be used at login

v1.0 ✅

  • Basic TOTP implementation (RFC 6238)
  • QR code generation for easy setup
  • User profile integration (tab in user settings)
  • Login page integration (2FA field on main login)
  • Backup codes (10 single-use codes)
  • Admin configuration panel with statistics
  • German and English translations
  • AES-256 encryption for stored secrets
  • Rate limiting (5 attempts/minute)

🛡️ Security

  • Standard Compliant - Implements RFC 6238 TOTP
  • Secure Secrets - 160-bit secrets, cryptographically random
  • Rate Limiting - Protection against brute-force attacks
  • Time-based Codes - 30-second validity window
  • Database Encryption - Secrets stored encrypted
  • No External Dependencies - All TOTP logic is self-contained

🆚 Why This Module?

Compared to commercial 2FA modules for Dolibarr:

Feature This Module Commercial Modules
Price Free (GPL-3.0) €30-50
Open Source ✅ Yes ❌ No
TOTP/RFC 6238 ✅ Yes ✅ Yes
QR Code Setup ✅ Yes ✅ Yes
Backup Codes ✅ Yes ⚠️ Some
Self-Service ✅ Yes ✅ Yes
Community Support ✅ Yes ❌ Paid only

🤝 Contributing

Contributions are welcome! This is a community project.

git checkout -b feature/NewFeature
git commit -m 'Add: Cool Feature'
git push origin feature/NewFeature
# → Create Pull Request

📄 License

GPL v3 or higher - Same as Dolibarr

👤 Author

Gerrett84 - GitHub

🙏 Acknowledgments

  • Dolibarr Community
  • RFC 6238 TOTP Standard
  • Open Source Security Community
  • @fefed22 - Multi-Company & Dolibarr 21 compatibility testing

Questions? → GitHub Issues

⚠️ Backup

Before upgrading, always backup your database:

# Backup 2FA tables
mysqldump -u root -p dolibarr llx_totp2fa_user_settings llx_totp2fa_backup_codes llx_totp2fa_activity_log llx_totp2fa_trusted_devices llx_totp2fa_login_attempts llx_totp2fa_ip_blacklist > totp2fa_backup.sql

Current Version: 1.4.5 Status: Stable Compatibility: Dolibarr 21.0+

About

TOTP-based Two-Factor Authentication module for Dolibarr ERP/CRM - Compatible with Google Authenticator and Apple Passwords

Resources

Readme
License

Contributing

Contributing
Activity

Stars

5 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages