Host Modules Two-Factor Authentication for WHMCS
HM Two-Factor Authentication adds a second layer of login security to your WHMCS
client area — and, separately, to your own WHMCS admin logins. Clients can protect
their accounts using a TOTP authenticator app (Google Authenticator, Authy,
Microsoft Authenticator), a passkey (Face ID, Touch ID, Windows Hello, or a
hardware security key), or a one-time email code — whichever suits them. Backup
recovery codes ensure they are never locked out permanently.
A passkey can also replace the password outright. With passwordless sign-in,
a client opens your login page, their browser offers the passkey it holds, they
touch the sensor, and they are in — no password, and no second step, because the
passkey already provided both. The same is available for your own administrators,
on a separate switch.
Unlike alternatives that only cover the client portal, HM 2FA also protects your
own WHMCS staff logins with a dedicated Admin Security system — enrolment and
enforcement are deliberately separate steps, so turning on enforcement can never
lock out an admin who hasn't opted in yet. Add QR code setup, trusted device
management, forced 2FA with an announced grace period, brute-force lockout
protection, one-setting brand-colour theming, and a detailed security audit log —
all managed from a clean admin panel with no IonCube Loader required.
─────────────────────────────────────
HOW THIS COMPARES TO WHMCS'S BUILT-IN 2FA
─────────────────────────────────────
WHMCS already ships two-factor authentication. Here's what's different —
sourced against WHMCS's own documentation, not just our word for it.
─────────────────────────────────────
AUTHENTICATION METHODS
─────────────────────────────────────
- Authenticator App (TOTP) — works with Google Authenticator, Authy,
Microsoft Authenticator, and any RFC 6238-compliant app
- Passkeys — Face ID, Touch ID, Windows Hello, or any WebAuthn hardware
security key. Phishing-resistant by design: a passkey will not respond
on a domain it wasn't registered on, even a pixel-perfect fake
- Email Code — a one-time code (4–8 digits, configurable) sent to the
client's registered email address
- Backup Recovery Codes — a configurable set (default 10, up to 20)
of single-use emergency codes generated at setup, regeneratable at
any time from the client's 2FA management page
- QR Code Setup — scan a QR code to add the account to an authenticator
app instantly; manual secret key entry also available
- Passwordless Sign-in — a passkey instead of the password, not just
instead of the code. Offered in the login form's own autofill, so a
visitor without one on that device simply types their password as
usual. Still two factors: the device, plus the fingerprint, face or PIN
that unlocks it — and the addon verifies that the authenticator
actually performed that check rather than merely being asked to
─────────────────────────────────────
ADMIN SECURITY (protects your WHMCS staff, separately from clients)
─────────────────────────────────────
A completely independent 2FA system for administrators, with its own
top-level menu, its own enrolment and backup codes, and admin-side
passkey support.
- Enrolling and enforcing are two separate, deliberate steps — enrolling
never arms anything by itself, so it's always safe to try
- Enforcement only ever challenges admins who have already completed
enrolment — it cannot lock out an admin who hasn't opted in
- Admin-side passkeys, managed the same way as client passkeys
- Passwordless sign-in for administrators too, on a switch of its own —
an admin session is a far bigger prize than a client one, so enabling
it for your customers never quietly enables it for your staff. The
session is created through WHMCS's own authentication and the sign-in
is written to the WHMCS admin log exactly as a password login is
- One line has to be added to WHMCS's
admin/templates/login.tpl for the
admin passkey button, because WHMCS provides no hook on that page. The
addon adds it for you at the press of a button and keeps a backup; a
WHMCS update replaces that file, and the step then reappears in your
setup checklist so you know to re-apply it
- Its own single-use backup codes, shown once at enrolment
- Three documented recovery paths, including an emergency filesystem
bypass file, in case an admin is ever locked out
─────────────────────────────────────
CLIENT SETUP & MANAGEMENT
─────────────────────────────────────
A guided, numbered-step setup wizard walks clients through enabling 2FA
in minutes, with the QR code generating automatically. After setup, a
dedicated Manage 2FA page — laid out like the account-security pages on
Google and GitHub — gives full control over their configuration.
- Enable or disable 2FA at any time from the management page
- Configure any combination of authenticator app, passkeys, and email
code side by side
- Add, name, and remove individual passkey devices
- Regenerate backup recovery codes on demand
- View remaining backup code count at a glance
- "Remember this device" — trusted devices skip 2FA for a configurable
number of days, so clients are not prompted on every login from the
same browser
- Automatic code submission on 6-digit entry — no button click needed
- 2FA status card injected directly into the WHMCS Security Settings page
─────────────────────────────────────
NAVIGATION INTEGRATION
─────────────────────────────────────
- 2FA management link added to the WHMCS client area navigation
- Configurable position: shortcuts bar, account dropdown, or both
─────────────────────────────────────
BRAND-COLOUR THEMING
─────────────────────────────────────
One colour setting drives the accent across every admin and client
page — buttons, active tabs, toggle switches, badges, and focus rings —
so the addon can match your brand instead of looking bolted on.
- Live preview updates as you pick a colour, before saving
- Hover shade, light tint, and readable button text are all derived
automatically — nothing else to configure
- Applies to both the admin panel and every client-facing page at once
─────────────────────────────────────
ADMIN DASHBOARD
─────────────────────────────────────
Adapts automatically: a setup checklist while you're getting
configured, live statistics once you are.
- Total active clients vs 2FA-enabled clients
- 2FA adoption rate percentage at a glance
- Successful verifications today
- Failed verification attempts today
- Active verified sessions count
- Total exempt clients
─────────────────────────────────────
ADMIN CLIENT MANAGEMENT
─────────────────────────────────────
A searchable, paginated client list showing the 2FA status, exemption
state, and lockout state of every client — with per-row admin actions.
- Reset a client's 2FA setup (forces them to re-enrol) — the fast path
for a client locked out of both their authenticator and backup codes
- Exempt a client from 2FA with a reason note
- Manually unlock accounts locked due to failed attempts
- 2FA status badge visible on every WHMCS admin client profile page
─────────────────────────────────────
SECURITY AUDIT LOG
─────────────────────────────────────
A full per-attempt log of every 2FA verification event — successful and
failed, client and admin — with the detail needed to investigate
suspicious activity.
- IP address, browser/user agent, and 2FA method (TOTP / passkey /
email / backup code) per attempt
- Failure reason recorded (wrong code, expired, too many attempts)
- Filter by client, outcome (success / failure), and date range
- Export to CSV, with optional email masking in both the view and export
- Admin email notifications on suspicious failure patterns
─────────────────────────────────────
SECURITY ARCHITECTURE
─────────────────────────────────────
- RFC 6238 TOTP compliance with time-sync tolerance (±1 window)
- Full WebAuthn implementation for passkeys — origin-bound, phishing
resistant by construction, not by user vigilance
- Passwordless sign-in requires user verification and checks the flag the
authenticator returned, rather than trusting that it was asked for — so
a one-touch login can never quietly degrade into a single factor
- A client's passkey cannot create an admin session, or the reverse;
each sign-in challenge is single-use, and failures are throttled per IP
with clients and admins counted separately
- Cryptographically secure secret and code generation (random_bytes)
- Timing-safe code comparison (hash_equals) — prevents timing attacks
- TOTP secrets and backup codes encrypted at rest (AES-256-GCM)
- Account lockout after configurable failed attempts (default: 5), with
exponential backoff on repeat lockouts
- Session-bound verification with IP address and user agent tracking
- Daily automatic cleanup of expired sessions, codes, and old log entries
─────────────────────────────────────
ENFORCEMENT & POLICY
─────────────────────────────────────
- Force 2FA for all clients — requires every client to enrol within a
configurable grace period (default: 7 days), so you can announce the
change before it becomes unavoidable rather than locking everyone out
on their next login
- Require verified email before 2FA setup can begin
- Per-client exemptions with reason notes for staff accounts, resellers,
or accessibility cases
- Detects and clears WHMCS's native client 2FA per account at login, and
hides the native 2FA panel from the client Security page — no
conflicting double prompts
─────────────────────────────────────
CONFIGURATION
─────────────────────────────────────
- Customise the application/issuer name shown in authenticator apps
- Configurable session timeout, backup code count, email code length
and expiry, and remember-device duration
- Anti-phishing phrase included in every 2FA code email, so its absence
is a trained client's tell for a forgery
- Enable or disable 2FA globally with a single toggle
- All settings managed from the admin panel. The one exception is the
passkey button on the WHMCS admin login page, which needs a single
line in a WHMCS core template — the addon writes it for you from the
Installation page, and shows you the line if the file is read-only
─────────────────────────────────────
LANGUAGE MANAGER
─────────────────────────────────────
Override any text string on the 2FA setup, verification, and management
pages directly from the admin panel without editing any template files.
Customise headings, button labels, and instructions for your audience.
─────────────────────────────────────
REQUIREMENTS
─────────────────────────────────────
- WHMCS 8.0 or newer
- PHP 8.1 or newer (checked and enforced at activation)
- Passkeys and passwordless sign-in require HTTPS in production
(localhost is allowed for testing)
- Passwordless sign-in for administrators needs one line added to
WHMCS's own admin login template — a button in the addon does it
- No IonCube Loader required
- Works with any WHMCS client theme
