Panellicense

WHM two-factor authentication: enforce TOTP for root and resellers

Turn on WHM two-factor authentication, enrol root and reseller accounts, audit who has it active, and close the gaps cPanel's built-in 2FA leaves behind — API tokens, SSH, and lost devices.

8 min readUpdated 2026-05-17cpanel · whm · 2fa · totp
schema: HowToschema: FAQPageschema: BreadcrumbList

WHM ships with TOTP-based two-factor authentication, but the default install leaves it switched off and there is no "require 2FA for every account" toggle. You enable the feature server-wide, then each user has to opt in from their own panel — which means a fresh server with five resellers can sit with zero of them enrolled for weeks if nobody chases it.

This walks through the actual mechanics: turning on the server-side feature, enrolling root and admin users without locking yourself out, getting resellers across the line, and the four gaps you should know about — API tokens, SSH, recovery, and the WHM "Manage Two-Factor Authentication" interface.

Turn on 2FA at the server level

WHM 2FA is one of the security features that ships disabled. Enable it before you enrol anyone, otherwise the enrolment UI won't show.

In WHM, go to Home » Security Center » Two-Factor Authentication, click the Manage My Account tab, then flip the master switch to On. If you prefer the CLI:

whmapi1 twofactorauth_policy is_enabled=1

Confirm it took:

whmapi1 twofactorauth_policy

You should see is_enabled: 1 in the YAML output. The setting is global — once on, the Two-Factor Authentication entry appears in the left sidebar of every cPanel and WHM user.

Enrol root and admin users

In WHM as root, go to Home » Security Center » Two-Factor Authentication » Manage My Account » Set Up Two-Factor Authentication. WHM shows a QR code and the underlying base32 secret.

Scan it with any TOTP app — Google Authenticator, Aegis, 1Password, Bitwarden, or oathtool for scripted environments. Avoid SMS-based apps; this is RFC 6238 TOTP, not push-based.

Enter the six-digit code WHM displays and submit. The feature is now active on root.

For each additional admin-level WHM account, log in as that user and repeat. There is no "enrol a different user" flow — every WHM and cPanel user enrols themselves. If you want to push it for a reseller, the cleanest path is to email them a one-line link and the QR-app of their choice; see the reseller section below.

Configure 2FA for reseller accounts

Resellers see the same Two-Factor Authentication menu in WHM as root, scoped to their own account. The friction is that nobody enforces enrolment — you can flip the global switch, send the announcement, and discover three months later that two-thirds of your resellers never set it up.

There are three practical ways to push enrolment:

  1. Manual audit + chase. Use the WHM 2FA admin interface (see "Auditing" below) to list who is enrolled, then email everyone who isn't. Works at small scale.
  2. Disable WHM access for resellers without 2FA. Suspend the account or restrict its IP list until they enrol. Heavy-handed but effective on new servers.
  3. Wrap it in a feature list. Resellers using your branded interface can be gated through a custom landing page that pushes them into the 2FA setup wizard on first login. This needs a small bit of glue in your reseller onboarding, not built-in.

cPanel does not currently expose a "force enrolment on next login" flag. It has been a feature request since 2018 and shows up in nearly every WHM security thread; treat it as a hosting-process problem, not a software one.

What WHM 2FA does not cover

Four common assumptions that are wrong:

  • API tokens bypass 2FA entirely. This is by design — automation can't prompt a human for a code. If you issue WHM or cPanel API tokens, you have given out a credential that ignores the second factor. Treat token issuance with the same care as handing out a root key. See scoping WHM API tokens to least privilege for how to limit the blast radius.
  • SSH is unaffected. WHM 2FA only guards the web panels (WHM, cPanel, Webmail). SSH on port 22 (or whatever you moved it to) still authenticates via password or key. If you want 2FA on SSH, install google-authenticator-pam and configure PAM separately — it's a different system.
  • DAV, FTP, and email logins are unaffected. Same reason. The 2FA token lives in a browser session.
  • Recovery codes don't exist. WHM does not generate backup codes the way GitHub or Google do. If a user loses their device, root has to clear their 2FA from WHM (see next section). For root itself, the recovery path is the server console.

Recovery when a user loses their device

For a regular cPanel or reseller user, root clears their 2FA from Home » Security Center » Two-Factor Authentication » Manage Users. Tick the user, click Disable 2FA on Account, and the user can re-enrol on next login.

CLI equivalent (useful in scripts):

whmapi1 twofactorauth_remove_user user=bob

For root itself, the only recovery path is a console session on the server — SSH if you still have a key, KVM/IPMI if you don't:

whmapi1 twofactorauth_policy is_enabled=0

This switches 2FA off server-wide, so do it only as a last resort and re-enable immediately after you've re-enrolled. There is no "disable for root only" command — the master switch is global.

Auditing who has 2FA enabled

The WHM UI at Two-Factor Authentication » Manage Users shows enrolment status for every account. For a scriptable view:

whmapi1 twofactorauth_get_user_configs | grep -A1 user:

The output lists each account and whether is_enabled is 1. Pipe that into a weekly cron that emails you the unenrolled accounts and you have closed-loop tracking without buying another tool.

For a 30-server fleet, the same call works against each WHM node via API token (--header 'Authorization: whm root:TOKEN'); collect the results centrally and you have a single "who is unprotected" dashboard.

Common failures

Code is rejected after a successful scan. Server clock drift. TOTP windows are 30 seconds and most validators accept ±1 step, so a clock more than 90 seconds off fails silently. Run chronyc tracking and fix NTP before troubleshooting anything else.

QR code won't display. Usually a missing Perl module after a partial cPanel update. Re-run /scripts/check_cpanel_rpms --fix and reload WHM.

Reseller sees the menu greyed out. Their package or feature list explicitly disables 2FA. Edit the feature list under Home » Packages » Feature Manager and ensure Two-Factor Authentication is ticked.

2FA prompt loops forever. Almost always a reverse proxy stripping the session cookie. If WHM sits behind Cloudflare or a custom Nginx, confirm the proxy is preserving Cookie and Set-Cookie headers for /cpsess* paths.

FAQ

Does WHM 2FA work with hardware keys like YubiKey?+
Not directly. WHM only speaks TOTP. You can chain a YubiKey by storing the TOTP secret in the YubiKey's OATH applet using Yubico Authenticator — the key then generates the codes — but FIDO2/WebAuthn is not supported by WHM as of cPanel 124.
Can I force every cPanel user to use 2FA?+
Not with a built-in toggle. You can audit who isn't enrolled via whmapi1 twofactorauth_get_user_configs and suspend or contact them, but cPanel has no enforce-on-next-login flag. It's a process problem.
Do API tokens require 2FA?+
No, by design. API tokens are an alternative credential intended for automation and bypass the second factor entirely. Treat token creation with the same scrutiny as 2FA enrolment, and scope each token to the minimum required calls.
What happens to existing browser sessions when I enable 2FA?+
Existing sessions are not invalidated. The 2FA prompt appears on the next login. Force a re-auth by clearing /var/cpanel/sessions/raw/ if you want to make sure nothing slips through.
Will enabling 2FA break my WHMCS or Blesta provisioning module?+
No. Both WHMCS and Blesta authenticate via API token, which bypasses 2FA. Provisioning, account creation, and password resets continue to work normally — assuming the token has the right ACLs.
Can the same TOTP secret work on multiple devices?+
Yes, RFC 6238 secrets are not bound to a device. Scan the same QR with your phone, tablet, and a desktop authenticator if you want redundancy. The server only validates the resulting code.

Next steps

Combine WHM 2FA with tuned cPHulk brute-force thresholds and scoped WHM API tokens and you've closed the three biggest credential-attack surfaces on a public WHM host. If you're standing up a new server, do it before the first reseller logs in — retroactive enrolment is the hard part. For licensing or fleet pricing on shared-hosting cPanel plans, see cPanel license tiers explained or grab a cPanel license directly.

Related articles

All tutorials & how-tos →
how to
Set up JetBackup 5 deduplication backups to cut storage cost
JetBackup 5.4 added a deduplication backup structure that fingerprints data in chunks and stores each unique chunk once — here's how it works, where it pays off, and how to turn it on.
6 min read
how to
Plesk 360 setup guide for centralized licenses and monitoring
Plesk 360 is the SaaS control plane for everyone running more than one Plesk box — license management, uptime monitoring, and SSO into every panel from one dashboard.
7 min read
how to
Use the Plesk REST API with reseller and customer accounts
Plesk Obsidian 18.0.79 opens the REST API to reseller and customer accounts and adds file, log, and impersonation endpoints — how to authenticate and use them.
7 min read
Switch in an afternoon

Switch from your current reseller — free.

We migrate active cPanel, Plesk, LiteSpeed and CloudLinux licenses from any reseller. We prorate the first month so you never pay twice, and your customers see zero downtime during the swap.