Two-Factor Authentication

This feature is available for all self-hosted WHMCS installations and for WHMCS Cloud’s Growth and Expansion plans.

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 Tokens	With 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 Security	With 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 2024-03-30. We recommend activating Duo Universal Prompt in your Duo customer portal to ensure continued functionality. For more information, see Duo Security.
YubiKey	YubiKey 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. 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.

Troubleshooting

For more information, see Troubleshooting Authentication.

You may encounter the following common issues:

Error or Issue	Cause	More Information
`Secure your Two-Factor Authentication storage. Click the "Begin Migration" below to get started. Migration will continue in background.` or `Two-Factor Authentication is being migrated to a secure storage format. When the migration is complete, this message will disappear.`	These messages display when WHMCS detects that your Two-Factor Authentication storage format is not encrypted.	2FA Storage Migration Messages
You see errors or experience problems while attempting to use Duo® Security for two-factor authentication. For example: `Client Duo® Security Login Failed: invalid_client: Integration type does not support frameless access.`	You need to update your Duo Security credentials to use Duo’s Universal Prompt system.	Duo Security Login Failures
You experience timezone-related issues in WHMCS or while running WHMCS automation.	There is a timezone misconfiguration or a mismatch between the webserver’s PHP configuration and the cron engine’s PHP configuration.	System Timezone Issues

Last modified: 2026 September 9