Skip to main content

Two-Factor Authentication

Two-Factor Authentication module for enhanced security.

Overview​

The Two-Factor Authentication (2FA) module adds an extra layer of security to user accounts by requiring a second form of verification during login. Using Time-based One-Time Passwords (TOTP), users must provide a code from their authenticator app in addition to their password.

Features​

  • TOTP-Based Authentication: Industry-standard Time-based One-Time Passwords
  • Authenticator App Support: Compatible with Google Authenticator, Authy, Microsoft Authenticator, and other TOTP apps
  • Backup Codes: Generate one-time use backup codes for account recovery
  • 2FA Enforcement Options: Require 2FA for all users, specific roles, or optional per-user
  • QR Code Setup: Easy setup via QR code scanning
  • Grace Period: Allow users time to set up 2FA after enforcement
  • Trusted Devices: Option to remember devices for a set period

Requirements​

  • Open Core Business Suite (Base System)
  • No additional dependencies

Installation​

  1. Enable the module in your module configuration:
// config/modules.php or via admin panel
'TwoFactorAuth' => true,
  1. Run the module migrations:
php artisan module:migrate TwoFactorAuth
  1. Publish the module assets (if applicable):
php artisan module:publish TwoFactorAuth

Configuration​

Module Settings​

Access the 2FA settings through the admin panel under Settings > Two-Factor Authentication:

SettingDescriptionDefault
Enable 2FAEnable/disable 2FA functionalityEnabled
Enforcement ModeNone, Optional, Required for roles, Required for allOptional
Backup Codes CountNumber of backup codes to generate10
Grace PeriodDays to allow setup before enforcement7
Trusted Device DurationDays to remember trusted devices30

Enforcement Options​

Configure 2FA enforcement based on your security requirements:

  • Optional: Users can choose to enable 2FA
  • Required for Admins: Only admin users must enable 2FA
  • Required for All: All users must set up 2FA

Usage​

User Setup​

  1. Navigate to Profile > Security or Settings > Two-Factor Authentication
  2. Click Enable Two-Factor Authentication
  3. Scan the QR code with your authenticator app
  4. Enter the 6-digit verification code to confirm setup
  5. Save the backup codes in a secure location

Login Process​

When 2FA is enabled:

  1. Enter username and password as usual
  2. System prompts for 2FA verification code
  3. Open authenticator app and enter the current 6-digit code
  4. Access granted upon successful verification

Using Backup Codes​

If you lose access to your authenticator app:

  1. Click "Use backup code" on the 2FA verification screen
  2. Enter one of your saved backup codes
  3. Each backup code can only be used once
  4. Generate new backup codes after logging in

Admin Management​

Administrators can:

  • View 2FA status for all users
  • Reset user's 2FA (requires re-setup)
  • Generate new backup codes for users
  • Enforce 2FA for specific roles or departments
  • View 2FA enrollment statistics

API Endpoints​

Enable 2FA​

POST /api/V1/2fa/enable

Returns QR code data and secret for setup.

Verify 2FA Setup​

POST /api/V1/2fa/verify
Content-Type: application/json

{
    "code": "123456"
}

Generate Backup Codes​

POST /api/V1/2fa/backup-codes

Returns a new set of backup codes.

Disable 2FA​

POST /api/V1/2fa/disable
Content-Type: application/json

{
    "password": "current_password"
}

Security Best Practices​

  1. Encourage Adoption: Promote 2FA enrollment through security awareness
  2. Secure Backup Codes: Instruct users to store backup codes safely
  3. Regular Audits: Review 2FA enrollment rates and compliance
  4. Incident Response: Have a process for account recovery
  5. Time Synchronization: Ensure server time is accurate for TOTP

Troubleshooting​

Invalid Code Errors​

  • Ensure device time is synchronized
  • Verify correct account in authenticator app
  • Try the next code if timing is on the edge

Lost Authenticator Access​

  1. Use a backup code to log in
  2. Disable and re-enable 2FA with new device
  3. Contact administrator for reset if no backup codes

2FA Not Appearing​

  • Verify module is enabled
  • Check user has permission to access 2FA settings
  • Clear browser cache and retry
Last updated on