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
• Recovery Codes: Generate one-time use recovery 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 configurable period
• Lockout Protection: Temporary lockout after too many failed verification attempts

Requirements

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

Installation

Enable via Admin Panel

1. Log in as administrator
2. Navigate to Settings > Addons
3. Find Two-Factor Authentication and click Enable
4. Run migrations if prompted

Enable via Command Line

php artisan module:enable TwoFactorAuth
php artisan migrate

Configuration

Module Settings

Access the 2FA settings at /twofactorauth/settings (admin or super_admin role required):

General Settings

Setting	Description	Default
Enable Two-Factor Authentication	Allow users to enable 2FA for their accounts	Enabled
Enforce Two-Factor Authentication	Require all users to enable 2FA (prompted on login)	Disabled
Enforce for Specific Roles	Require 2FA only for selected roles (leave empty to enforce for all)	None
Grace Period (Days)	Number of days to allow users to set up 2FA before enforcement	7

Security Settings

Setting	Description	Default
Maximum Failed Attempts	Lock account temporarily after this many failed 2FA attempts	5
Lockout Duration (Minutes)	How long to lock account after max failed attempts	15
Trust Device Duration (Days)	How long to remember trusted devices	30
Number of Recovery Codes	How many recovery codes to generate for users	10

Usage

User Setup

1. Navigate to /twofactorauth/setup
2. Scan the QR code with your authenticator app
3. Enter the 6-digit verification code to confirm setup
4. Save the recovery codes in a secure location

Login Process

When 2FA is enabled:

1. Enter username and password as usual
2. System redirects to the 2FA verification page
3. Open authenticator app and enter the current 6-digit code
4. Optionally check "Trust this device" to skip 2FA on future logins
5. Access granted upon successful verification

Using Recovery Codes

If you lose access to your authenticator app:

1. On the 2FA verification screen, enter a recovery code instead
2. Each recovery code can only be used once
3. Generate new recovery codes after logging in

Managing 2FA

Once 2FA is enabled, navigate to /twofactorauth/manage to:

• View trusted devices and remove them
• See remaining recovery code count
• Regenerate recovery codes (requires password confirmation)
• Disable 2FA (requires password confirmation)

Security Best Practices

1. Encourage Adoption: Promote 2FA enrollment through security awareness
2. Secure Recovery Codes: Instruct users to store recovery codes safely
3. 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 recovery code to log in
2. Disable and re-enable 2FA with new device
3. Contact administrator for reset if no recovery codes

Too Many Failed Attempts

• Account is temporarily locked after exceeding the maximum failed attempts
• Wait for the lockout duration to expire before trying again

---

Changelog: View version history