DuoSecurity

< Back to Two-Factor Authentication

This page describes a feature available in version 7.0 and above

What is DuoSecurity

Duo Security enables your users to secure their logins and transactions using their smartphones. The Duo Mobile smartphone application 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 use Duo Push which “pushes” login or transaction details to the phone, allowing for immediate, one-tap approval.

Older devices like cellphones and landlines are also fully supported. Duo can send passcodes via text message, or place a phone call - users just press a button on their keypad to authenticate. DuoSecurity will prompt you for a phone number and option to receive a text or phone call. After the text or phone call is received, input the authentication code to proceed.

A second optional page at initial login will prompt to download the DuoSecurity mobile application which performs push notifications allowing you to restrict or allow access under your user from your phone.

You will require your own Duo Security account. A 'Duo MFA' or higher level account is required to access the necessary API: Signup Here.

Configuration

Protect an Application

Protect Auth API

First Login to your account on the DuoSecurity website:

1. Click Applications in the left sidebar
2. Click Protect an Application
3. Locate the Auth API option
4. Beneath it click Protect this Application
5. Take note of following values:

• Integration Key
• Secret Key
• API hostname

Now login to your WHMCS Admin area as a Full Administrator user:

Complete configuration in WHMCS

1. Navigate to Setup > Staff Management > Two-Factor Authentication
2. Click the "Activate" button next to Duo Security
3. To enable Duo Security as a two-factor option for staff and/or clients, tick the corresponding Enable for checkboxes.
4. Enter the Integration Key, Secret Key and API Hostname you noted down earlier into the corresponding fields.
5. Click Save Changes

Once a member of staff or client has activated Two Factor Authentication on their account, upon the next login they will be prompted to complete the DuoSecurity registration process.

WHMCS DuoSecurity Account Migration

Prior to WHMCS 7.0, users wanting to use DuoSecurity could pay for their DuoSecurity subscription as part of the WHMCS monthly license fee. In WHMCS 7.0, this is changing and users must now signup directly with DuoSecurity for their service.

A phased approach has been implemented for the transition.

Beginning with the upgrade to WHMCS 7.0, existing users of DuoSecurity will be able to continue using the Duo service uninterrupted. However, users will be required to have signed up with DuoSecurity and provided their own DuoSecurity API credentials by November 30th, 2016 to continue using the service.

Warning notices will be displayed to all Full Administrator level users upon login to the admin area, as well as included in the daily system cron notification email, until your own DuoSecurity API Credentials have been configured.

Failure to create and enter your own DuoSecurity API Credentials by 30th November 2016 may result in DuoSecurity Two-Factor Authentication no longer being performed upon login until your own DuoSecurity API Credentials are provided.

Configuring your own DuoSecurity API Credentials

1. Signup for an account with DuoSecurity
2. Login to your DuoSecurity account
3. Click Applications in the left sidebar
4. Click Protect an Application
5. Locate the Auth API option
6. Beneath it click Protect this Application
7. Take note of following values: Integration Key, Secret Key & API hostname
8. Now login to your WHMCS Admin area as a Full Administrator user:
9. Navigate to Setup > Staff Management > Two-Factor Authentication
10. Enter the Integration Key, Secret Key and API Hostname you noted down earlier into the corresponding fields.
11. Click Save Changes

The warning notices should immediately disappear and upon the next login, users for which DuoSecurity was previously active will be prompted to perform the DuoSecurity setup again under the new account. From this point onwards, the DuoSecurity protection will continue to work exactly as before.

Common Errors

The second factor you supplied was incorrect. Please try again

Seeing this error when activating the DuoSecurity method for the first time means that the code being entered does not match that which 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, it's taken directly from your server's PHP configuration. So you must ensure 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 ensure the time is exactly right will resolve this.

Different time-zones are taken into account, so time-zone differences won't cause a problem.