Two-Factor Authentication

Two-Factor Authentication (2FA) enhances security by adding a second step to the login process. It combines something that you know (for example, your password) with a second factor, typically from something that you have (for example, your phone). Requiring both to log in decreases the threat of a leaked password.

You can access this feature at Configuration () > System Settings > Two Factor Authentication.

2FA Services

WHMCS includes several 2FA services:

Time-Based TokensWith Time-Based Tokens, you enter a 6-digit code that regenerates every 30 seconds in addition to your regular username and password. Only your token device (typically a mobile smartphone app) will have your secret key and be able to generate valid one-time passwords for your account.
We recommend enabling Time-Based Tokens, and WHMCS enables this by default.
Duo SecurityWith Duo® Security, the system will prompt you for a phone number. It will then prompt you to verify your identity using a push notification on your mobile device.
Duo has announced that support for the previous iframe-based Duo Prompt will end on March 30, 2024. Duo Security will not function in WHMCS 8.8 and earlier after this date. After you upgrade to WHMCS 8.9 or later, we recommend activating Duo Universal Prompt in your Duo customer portal to ensure continued functionality.
For more information, see Duo Security.
YubiKeyYubiKey creates a one-time password in a USB drive that acts as a keyboard to your computer. These are physical devices that you must purchase from Yubico directly.

Enabling 2FA Globally

To enable 2FA, click Activate under the desired service, configure the desired service settings, and click Save.

You can also use the settings under Global Two-Factor Authentication Settings to force users and admins to enable 2FA on their next login.
For steps and more information about enabling 2FA globally, see Enable 2FA Globally.

Enabling 2FA for Individual Accounts

Users and admins can begin to use 2FA after you have activated at least one service and configured the installation.

  • Clients can configure 2FA in the Client Area at Hello, Name! > Security Settings.
  • Admins can disable (but not enable) 2FA for individual clients in the Admin Area at Clients > Manage Users.
  • Admins can configure 2FA for themselves in the Admin Area at Account () > My Account.

For steps and more information about enabling 2FA for users and admins, see:

Lost or Unavailable Devices

2FA requires a secondary device in order to log in. Because of this, some users will inevitably need help when their device is missing or otherwise unavailable.

For steps to log in without the necessary device, see:

Server Time

Using 2FA requires that your WHMCS server clock matches the expected time on your chosen device or in DuoSecurity’s system. For example, if the server time is 00:01 and the time on your device or DuoSecurity’s clock is 00:00, two-factor authentication may fail.

If the times do not match, you will see one of the following errors:

  • The code you entered did not match what was expected. Please try again. (Time-Based Tokens)
  • The second factor you supplied was incorrect. Please try again. (DuoSecurity)

You can check the current time on your WHMCS server’s clock by viewing the time in the top-right corner of the Admin Area. WHMCS retrieves this time directly from your server’s PHP configuration.

This provides support for time zone differences, so they are unlikely to cause problems.

To resolve this issue, you must reset your server clock to ensure that the times match. You can sync your server clock with a NTP server to ensure it is completely accurate.

To do this using Google’s NTP server, run the following command on your server:

ntpdate time.google.com

Last modified: May 28, 2024