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. for Time-Based Tokens
  • The second factor you supplied was incorrect. Please try again. You have 2 attempts remaining. (WHMCS 8.9 and later) or The second factor you supplied was incorrect. Please try again. (WHMCS 8.8 and earlier) for Duo Security
You can view the current server time in the PHP configuration information at Utilities > System > PHP Info. For more information and steps to resolve timezone issues, see System Timezone Issues.
two-factor-authentication authentication duo-security

Last modified: December 4, 2024