Two Factor Authentication - TFA / Passwordless Login
Adds a second layer of authentication (2FA/MFA) to secure Drupal user accounts with multiple authentication methods including TOTP, OTP, Push Notifications, and WebAuthn.
miniorange_2fa
Install
composer require 'drupal/miniorange_2fa:^5.3'
Overview
miniOrange Two Factor Authentication (2FA/TFA) module provides enterprise-grade multi-factor authentication for Drupal sites. It protects your site from hacks, unauthorized login attempts, and phishing attacks by adding a second layer of security beyond passwords.
The module supports various authentication methods including OTP via SMS, Email, and Phone calls, TOTP authenticators (Google, Microsoft, Authy, LastPass, Duo, Okta, 2FAS, Zoho OneAuth), Push Notifications, QR Code Authentication, Security Questions (KBA), Hardware Tokens (YubiKey), and WebAuthn/FIDO2. It also supports passwordless login where users can authenticate using only their second factor without a password.
Advanced features include role-based and domain-based 2FA enforcement, trusted IP whitelisting, Remember My Device functionality, inline registration for end users, custom login form labels, and comprehensive audit logging. The module integrates with SSO solutions and provides a Headless/API mode for decoupled architectures.
Features
- Multiple 2FA methods: OTP over SMS, Email, Phone Call, TOTP authenticators, Push Notifications, QR Code, Security Questions (KBA), Hardware Tokens (YubiKey), WebAuthn/FIDO2
- Passwordless login allowing authentication with only the second factor (no password required)
- Role-based 2FA enforcement to require 2FA for specific user roles
- Domain-based 2FA enforcement to require 2FA for specific email domains
- Trusted IP whitelisting to skip 2FA for specific IP addresses or ranges
- Remember My Device (Risk-Based Authentication) to remember trusted devices for a configurable duration
- Inline registration flow for end users to set up 2FA during their first login
- Password length restriction to enforce 2FA for users with weak passwords
- Backdoor login URL for emergency access without 2FA
- Custom redirect URL after successful login
- Enable login with email address or phone number in addition to username
- Override login form username title and description
- Custom organization branding for authentication screens
- Customizable Email and SMS templates via miniOrange dashboard
- Customizable OTP length and validity
- Admin dashboard for managing all users' 2FA configurations
- Comprehensive audit logging of authentication attempts
- Headless/Decoupled 2FA API support for frontend frameworks
- Integration with SSO modules (CILogon, etc.)
- Backup authentication method (KBA) when primary method is unavailable
- WebAuthn submodule for passwordless biometric authentication
Use Cases
Securing Admin Accounts
The primary use case is protecting administrator accounts from unauthorized access. After installation, the admin can immediately configure 2FA for their account using any supported method like Google Authenticator or Email OTP, ensuring that even if the password is compromised, the account remains secure.
Enterprise-Wide 2FA Enforcement
Organizations can enforce 2FA for all users or specific roles using the role-based restriction feature. For example, require 2FA for all users with 'editor' or 'administrator' roles while allowing 'authenticated' users to optionally use 2FA.
Domain-Based Security Policies
Companies with multiple email domains can enforce 2FA only for specific domains. For instance, require 2FA for @company.com emails while exempting @contractor.com addresses.
Headless/Decoupled Drupal
For sites using a decoupled architecture with a separate frontend (React, Vue, etc.), the headless 2FA API endpoints allow integrating 2FA verification into the custom frontend authentication flow.
Trusted Network Access
Organizations can configure trusted IP ranges (office networks, VPNs) where 2FA is skipped, reducing friction for users connecting from secure locations while maintaining security for external access.
Passwordless Authentication
Enable passwordless login where users authenticate using only their second factor (TOTP code, biometrics via WebAuthn, or push notification), eliminating password-related vulnerabilities entirely.
SSO Integration
When used alongside SSO modules, 2FA provides an additional security layer after SSO authentication, ensuring users are verified through multiple factors even when using federated identity.
Tips
- Enable the backdoor URL immediately after activating the module as an emergency recovery option
- Use Email OTP or TOTP authenticators for testing before deploying other methods
- The free version supports 1 user with limited methods - ideal for protecting the main admin account
- Run Drupal cron regularly to keep license and transaction information up to date
- Use role-based 2FA to phase in deployment - start with admins, then expand to other roles
- Configure KBA (Security Questions) as a backup method so users can recover if they lose access to their primary method
- Test the 2FA flow in a staging environment before enabling for all users
- Export user configurations before uninstalling - check 'Preserve configured 2FA settings' during uninstall to keep data
Technical Details
Admin Pages 9
/admin/config/people/miniorange_2fa/customer_setup
Register or login with your miniOrange account to activate the module. After registration, view your profile details including customer ID, license information, remaining SMS/Email/IVR transactions, and license expiry dates. You can also remove your account from this page.
/admin/config/people/miniorange_2fa/setup_twofactor
Configure Two-Factor Authentication for the primary admin user who activated the module. View all available 2FA methods organized by type (OTP, TOTP, Other), see which methods are active or configured, and set up new authentication methods.
/admin/config/people/miniorange_2fa/login_settings
Configure Two-Factor Authentication policies for end users including enabling/disabling 2FA, inline registration, role-based and domain-based enforcement, trusted IPs, Remember My Device, and customization options.
/admin/config/people/miniorange_2fa/user_management
Manage 2FA configurations for all users on the site. View user details, 2FA status, configured methods, and perform actions like reset, enable, or disable 2FA for individual users or in bulk.
/admin/config/people/miniorange_2fa/report
View authentication logs including login attempts, 2FA challenges, setup events, and reset actions. Filter logs by username, event type, and status.
/admin/config/people/miniorange_2fa/headlesSsetup
Configure Two-Factor Authentication for headless/decoupled Drupal architectures. Enable the headless 2FA API and get documentation for integrating 2FA into frontend applications.
/admin/config/people/miniorange_2fa/licensing
View available license plans and upgrade options. Compare features between free and premium versions.
/admin/config/people/miniorange_2fa/addons
View and enable additional features and addons for the 2FA module.
/mfa_setup/{user}/settings
User profile tab allowing end users to view and manage their own 2FA configurations. Available only when 2FA is enabled and the user has configured 2FA.
Permissions 5
Hooks 2
hook_invoke_alter_login_flow_details
Allows modules to alter the 2FA login flow details including messages, descriptions, and allowed attempts for each authentication type.
hook_invoke_miniorange_2fa_before_login
Hook called by SSO modules before completing user login to invoke 2FA. Used for integrating 2FA with Single Sign-On solutions.
Troubleshooting 6
Use the backdoor URL (/user/login?skip_2fa=YOUR_API_KEY) to bypass 2FA. The API key is shown on the Login Settings page. If you don't have the key, access the database directly and set mo_auth_enable_two_factor to FALSE in the config table.
Verify that 'Activate Two-Factor Authentication' is enabled on the 2FA Policy tab. Check if the user is connecting from a trusted IP that bypasses 2FA. Verify that role-based or domain-based restrictions include the user.
Check your remaining transactions on the Register/Login tab. SMS and Email OTPs consume transaction credits. Contact miniOrange to purchase additional transactions if depleted.
Ensure the time on your phone is synchronized. TOTP codes are time-sensitive with a 30-second window. Try refreshing the code and entering immediately.
Ensure the PHP cURL extension is enabled on your server. The module requires cURL to communicate with miniOrange servers.
Ensure the SSO module is calling the hook_invoke_miniorange_2fa_before_login() hook with the user account object after SSO authentication.
Security Notes 7
- The backdoor URL provides emergency access without 2FA - keep the API key confidential and only share with trusted administrators
- SMS-based OTP is considered less secure than TOTP or WebAuthn due to SIM-swapping attacks - consider using TOTP methods for high-security accounts
- The module communicates with miniOrange cloud servers for license validation and some 2FA methods (SMS, Push) - review your organization's data handling policies
- Store the miniOrange account credentials securely - they provide access to your license and can be used to manage your 2FA configuration
- WebAuthn/FIDO2 provides the highest security level and is resistant to phishing attacks
- Trusted IP configuration should be reviewed regularly to ensure only legitimate IP ranges are whitelisted
- The module logs authentication attempts - review logs periodically for suspicious activity