DuoSecurity

< Back to Two-Factor Authentication

What is Duo Security

Duo Security increases security by adding a second identity verification to logins. By requiring both a password and a unique one-time code, it protects your WHMCS installation and accounts against unauthorized access.

Why Duo Security?

Duo Security is free up to 10 users, which makes it a perfect solution for securing administrator logins.

The Duo Mobile app is free and available on all major smartphone platforms, and lets users easily generate passcodes without the cost and hassle of hardware tokens.

iPhone®, Android™, BlackBerry®, and Windows® Phone users can also use Duo Push. This “pushes” login or transaction details to your phone, allowing for immediate one-tap approval.

You will require a Duo Security account with an account level of Duo MFA or higher in order to access the Duo API. Click here to sign up.

Configuring Duo Security

Protect an Application

Protect Auth API

To configure Duo Security in WHMCS, follow the steps below:

1. Log in to your account at Duo Security.
2. Click Applications in the left sidebar.
3. Click Protect an Application.
4. Under Auth API, click Protect this Application. If you don't see this option, contact Duo support.
5. Retrieve the following values:
   • Integration Key
   • Secret Key
   • API hostname
6. Log in to the WHMCS Admin Area as an admin with Full Administrator privileges.
   

   Complete configuration in WHMCS
7. Navigate to Configuration () > System Settings > Two Factor Authentication or, prior to WHMCS 8.0, Setup > Staff Management > Two-Factor Authentication.
8. Click Activate next to Duo Security.
9. To enable Duo Security as a two-factor option for staff, check Enable for Staff.
10. To enable Duo Security for customers, check Enable for Clients.
11. Enter the Integration Key, Secret Key, and API Hostname you retrieved.
12. Click Save Changes.

Enabling Duo Security as an Admin User

To enable Duo Security for an admin:

1. Perform the steps above to configure Duo Security.
2. Navigate to the My Account page within the WHMCS Admin Area.
3. Click Enable Two-Factor Authentication.
4. Follow the instructions to complete the setup process.

Enabling Duo Security as a Client

To enable Duo Security as a client:

1. Log in to the WHMCS Client Area.
2. Go to Account > My Account > Security Settings or, prior to WHMCS 8.0, My Account > Security Settings.
3. Click Enable Two-Factor Authentication.
4. Follow the instructions to complete the setup process.

On all future login attempts, the client will be asked to complete the Two-Factor Authentication process.

Troubleshooting

The second factor you supplied was incorrect. Please try again

Seeing this error when activating the DuoSecurity method for the first time indicates that the code does not match what DuoSecurity expects. This is caused by the time on your server not matching DuoSecurity's clocks.

You can see the time in the top-right corner of your WHMCS Admin Area. WHMCS retrieves this directly from your server's PHP configuration and you must ensure that the server time is synced exactly with UTC. For example, if the server time is 00:01 and the time at DuoSecurity is 00:00, you will see this error. Syncing the server with NTP to verify the time will resolve this.

Different timezones are taken into account, ensuring that these differences won't cause a problem.

Invalid Integration

An Invalid Integration error is displayed on the Duo authentication screen when the keys/hostname used in Duo module configuration are incorrect. Please reconfigure the module settings by following the steps above.