Two-Factor Authentication
Contents
What is Two-Factor Authentication?
Two-factor authentication adds an additional layer of security by introducing a second step to your login. It takes something you know (i.e.: your password), and adds a second factor, typically something you physically have (such as your phone). Since both are required to log in, in the event an attacker obtains your password two-factor authentication would stop them from accessing your account.
Why do you need it?
Passwords are increasingly easy to compromise. They can often be guessed or leaked, they usually don’t change very often, and despite advice otherwise, many of us have favorite passwords that we use for more than one thing. So Two-factor authentication gives you additional security because your password alone no longer allows access to your account. How does it work?
There are many different options available, and in WHMCS we support more than one so you have the choice. Here's a brief overview of the different types:
DuoSecurity
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.
Detailed configuration instructions are located at http://docs.whmcs.com/Duo_Security
Time Based One-Time Passwords
Time Based One-Time passwords requires downloading an OATH application onto your smartphone or tablet, and optionally a bar-code reader.
Once activated a pop-up screen will present a QR code, with optional manual code to enter into your smartphone or tablet. Once scanned or entered, a time based one time password will appear within your OATH application providing the second form of verification used to log in.
Additionally, a backup code is presented which should be stored in the event that your smartphone or tablet is not accessible and you wish to gain access into WHMCS.
YubiKey
YubiKey creates a one time password stored within a USB drive that acts as a keyboard to your computer. These are physical devices that need to be purchased from Yubico directly. A purchase link is available inside WHMCS.
For more information on different types of two-factor authentication WHMCS supports, please refer to http://www.whmcs.com/two-factor/
Configuration
Begin by navigating to Setup > Staff Management > Two-Factor Authentication and click the "Activate" button next to the type of two-factor authentication you wish to use.
The Duo Security and TOTP options both require a subscription before they can be configured, so instead of an Activate button, you will see a Subscribe To Activate button. You can click this to be taken to the relevant signup page, once the purchase has been completed you can return to the Two-Factor Authentication page to continue the configuration process.
Once activated you will be presented with a number of options, please fill these in with the account details from your welcome email. Some options are common to all auth methods:
Enable for Clients
Ticking this option will allow clients to individually enable Two-Factor Authentication of their own accord via the client area. Once activated they will need to complete two-factor authentication each time they login.
Clients activate it via the My Details page of the client area, in the default template this is located under the "Security Settings" tab. They simply click the Click here to enable button beneath the "Two-Factor Authentication" heading and follow the on-screen instructions.
Should a client decide to disable two-factor authentication at a later date, they can simply click the Click here to disable button which will appear in the same location.
Enable for Staff
Ticking this option will allow staff to individually enable Two-Factor Authentication of their own accord via the admin area. Once activated they will need to complete two-factor authentication each time they login.
Staff activate it via the My Account page of the admin area (link in the top-left corner of every page). They simply click the Click here to enable button and follow the on-screen instructions.
Should a member of staff decide to disable two-factor authentication at a later date, they can simply click the Click here to disable button which will appear in the same location.
Force Settings
On the left hand side of the Two-Factor Authentication page are two Force Settings. Ticking these options will require clients and/or staff to configure two-factor authentication upon next login, they will be presented with a prompt showing them the two-factor authentication instructions and will not be able to proceed until registration is complete.
Licensing
If you have recently purchased Two Factor and your WHMCS system is not yet reflecting your purchase, you may find you need to force a license update which you can do by navigating to Help > Check for Updates and then you can try activating and using the Two Factor module again.
Common Errors
The code you entered did not match what was expected. Please try again
Seeing this error when activating the time based one time password method means that the 6 characters generated by your device do not match the 6 numbers WHMCS expected. This is caused by the time on your device (phone, tablet etc) and WHMCS installation being different.
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 correct, and the time on your device matches the server time. For example if the server time is 00:01 and the time on your device is 00:00 you will see this error, you must change the time on your device to 00:01 so they both match.
Different time-zones are taken into account, so time-zone differences won't cause a problem.
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.