Difference between revisions of "Two-Factor Authentication"

From WHMCS Documentation

m (→‎Licensing)
Line 1: Line 1:
−
==What is Two-Factor Authentication?==
+
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.
+
==Introduction==
  
−
===Why do you need it?===
+
Two-Factor Authentication adds an additional layer of security by adding a second step to the login process. It takes something you know (i.e. your password) and adds a second factor, typically something you have (such as your phone). Since both are required to log in, the threat of a leaked password is lessened.
  
−
Passwords are increasingly easy to compromise for any number of reasons. For example, 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. With Two-factor authentication, it gives you additional security because your password alone no longer allows access to your account.
+
Below is a brief summary of the three Two-Factor Authentication services included with WHMCS. For more information on the different types of Two-Factor Authentication WHMCS supports, please refer to http://www.whmcs.com/two-factor/
  
−
How does it work?
+
===Time Based Tokens===
  
−
There are many different options available, and we support 3 of them so you have the choice. Here's a brief overview of the different types:
+
One of the most common and simplest forms of Two-Factor Authentication is Time Based Tokens. With Time Based Tokens, in addition to your regular username & password, you also have to enter a 6 digit code that re-generates every 30 seconds. Only your token device (typically a mobile smartphone app) will know your secret key and be able to generate valid one time passwords for your account. We recommend enabling Time Based Tokens (also enabled by default).
  
−
====DuoSecurity====
+
===DuoSecurity===
−
With DuoSecurity, you will be prompted 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. This application is used to perform push notifications, allowing you to restrict or allow access under your user from your phone.
+
With DuoSecurity, you will be prompted 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. This application is used to perform 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
+
Detailed configuration instructions are located at http://docs.whmcs.com/Duo_Security
  
−
====Time Based One-Time Passwords====
+
===YubiKey===
−
Time Based One-Time passwords requires downloading an OAUTH 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.
+
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.
 +
 
 +
==Enabling Two-Factor Authentication==
 +
 
 +
[[File:2FA_006.png|thumb|Time Based Tokens Configuration]]
 +
 
 +
To enable Two-Factor Authentication on an installation, follow the steps below:
 +
 
 +
# From the Admin Area, begin by navigating to ''Setup > Staff Management > Two-Factor Authentication''
 +
# Click the ''Activate'' button under the service that you would like to enable
 +
# Select one or both of the ''Enable for use by Clients'' and ''Enable for use by Administrative Users'' options
 +
# If applicable, complete any additional ''Configuration Settings''
 +
# Click on the ''Save'' button
 +
 
 +
These steps can be repeated for each service that you would like to enable.
 +
 
 +
[[File:2FA_001.png|border|800px]]
 +
 
 +
===Global Two-Factor Authentication Settings===
 +
 
 +
The ''Global Two-Factor Authentication Settings'' options allow you to forcibly enable Two-Factor Authentication for Client and/or Administrator Users on their next login.
 +
 
 +
To utilise this feature select the options you would like, and click the ''Save Changes'' button. If a user has not yet configured Two-Factor Authentication, then they will be forced to do so the next time they sign into WHMCS.
  
−
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.
+
[[File:2FA_002.png|border|800px]]
  
−
====YubiKey====
+
==Using Two-Factor Authentication==
−
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.
+
 
 +
Clients and Administrator Users can begin to use Two-Factor Authentication after one or more services have been activated and configured on the installation.
  
−
* For more information on different types of two-factor authentication WHMCS supports, please refer to http://www.whmcs.com/two-factor/
+
===Within the Client Area===
  
−
==Configuration==
+
[[File:2FA_005.png|thumb|Configuring Time Based Tokens in Client Area]]
−
[[File:2factor1.png|thumb|Yubico 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.
 
  
−
Once activated, you will be presented with a number of settings specific to that provider. Please fill these in with the account details from your welcome email or control panel. Some options are common to all auth methods:
+
The following steps demonstrate how Client Users can setup Two-Factor Authentication on their account using the ''Time Based Tokens'' service.
  
−
===Enable for Clients===
+
# From the Client Area, being by navigating to ''Hello, Name! > Security Settings''
−
[[File:2factor2.png|thumb|Enable for Clients]]
+
# Click on the ''Click here to Enable'' button
−
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.
+
# Select the ''Time Based Tokens'' service
 +
# Click on the ''Get Started'' button
 +
# Scan the QR code with an authenticator app such as Google Authenticator or Duo Mobile
 +
# Enter in the 6-digit code that the authenticator app generates
 +
# Click on the ''Submit'' button
 +
# Record the ''Backup Code'' in a safe place
 +
# Click the ''Close'' button
  
−
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.
+
[[File:2FA_003.png|border|800px]]
  
−
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.
+
===Within the Admin Area===
  
−
===Enable for Staff===
+
[[File:2FA_005.png|thumb|Configuring Time Based Tokens in Admin Area]]
−
[[File:2factor3.png|thumb|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.
+
In turn, Administrator Users can perform the following actions to setup Two-Factor Authentication on their account using the ''Time Based Tokens'' service.
  
−
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.
+
# From the Admin Area, begin by navigating to the ''My Account'' section
 +
# Toggle the ''Two-Factor Authentication'' setting to ''On''
 +
# Select the ''Time Based Tokens'' service
 +
# Click on the ''Get Started'' button
 +
# Scan the QR code with an authenticator app such as Google Authenticator or Duo Mobile
 +
# Enter in the 6-digit code that the authenticator app generates
 +
# Click on the ''Submit'' button
 +
# Record the ''Backup Code'' in a safe place
 +
# Click the ''Close'' button
  
−
==Force Settings==
+
[[File:2FA_004.png|border|800px]]
−
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. Upon their 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==
+
==Troubleshooting==
−
If you have recently purchased Two Factor and your WHMCS system is not yet reflecting your purchase, you may need to force a license update. This can be done by navigating to '''Help > License Information''' and clicking "Force License Update". 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.'''<br /><br />
−
===The code you entered did not match what was expected. Please try again===
 
 
Seeing this error when using the time based tokens 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 the server where WHMCS is installed being different.
 
Seeing this error when using the time based tokens 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 the server where WHMCS is installed 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. 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. In that scenario, you must change the time on your device to 00:01 so that they both match.
+
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. 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. In that scenario, you must change the time on your device to 00:01 so that they both match.
  
 
Syncing the server with [http://en.wikipedia.org/wiki/Network_Time_Protocol NTP] to ensure the time is exactly right may also help to resolve this. Most servers will revert to the internal hardware clock on reboot/power on, so you will need to sync any changes from NTP to the hardware clock as well.
 
Syncing the server with [http://en.wikipedia.org/wiki/Network_Time_Protocol NTP] to ensure the time is exactly right may also help to resolve this. Most servers will revert to the internal hardware clock on reboot/power on, so you will need to sync any changes from NTP to the hardware clock as well.
Line 68: Line 96:
 
Different time-zones are taken into account, so time-zone differences won't cause a problem.
 
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===
+
'''The second factor you supplied was incorrect. Please try again.'''<br /><br />
 
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.
 
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.
  

Revision as of 13:43, 14 August 2019

Two-Factor Authentication

Introduction

Two-Factor Authentication adds an additional layer of security by adding a second step to the login process. It takes something you know (i.e. your password) and adds a second factor, typically something you have (such as your phone). Since both are required to log in, the threat of a leaked password is lessened.

Below is a brief summary of the three Two-Factor Authentication services included with WHMCS. For more information on the different types of Two-Factor Authentication WHMCS supports, please refer to http://www.whmcs.com/two-factor/

Time Based Tokens

One of the most common and simplest forms of Two-Factor Authentication is Time Based Tokens. With Time Based Tokens, in addition to your regular username & password, you also have to enter a 6 digit code that re-generates every 30 seconds. Only your token device (typically a mobile smartphone app) will know your secret key and be able to generate valid one time passwords for your account. We recommend enabling Time Based Tokens (also enabled by default).

DuoSecurity

With DuoSecurity, you will be prompted 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. This application is used to perform 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

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.

Enabling Two-Factor Authentication

Time Based Tokens Configuration

To enable Two-Factor Authentication on an installation, follow the steps below:

  1. From the Admin Area, begin by navigating to Setup > Staff Management > Two-Factor Authentication
  2. Click the Activate button under the service that you would like to enable
  3. Select one or both of the Enable for use by Clients and Enable for use by Administrative Users options
  4. If applicable, complete any additional Configuration Settings
  5. Click on the Save button

These steps can be repeated for each service that you would like to enable.

2FA 001.png

Global Two-Factor Authentication Settings

The Global Two-Factor Authentication Settings options allow you to forcibly enable Two-Factor Authentication for Client and/or Administrator Users on their next login.

To utilise this feature select the options you would like, and click the Save Changes button. If a user has not yet configured Two-Factor Authentication, then they will be forced to do so the next time they sign into WHMCS.

2FA 002.png

Using Two-Factor Authentication

Clients and Administrator Users can begin to use Two-Factor Authentication after one or more services have been activated and configured on the installation.

Within the Client Area

Configuring Time Based Tokens in Client Area

The following steps demonstrate how Client Users can setup Two-Factor Authentication on their account using the Time Based Tokens service.

  1. From the Client Area, being by navigating to Hello, Name! > Security Settings
  2. Click on the Click here to Enable button
  3. Select the Time Based Tokens service
  4. Click on the Get Started button
  5. Scan the QR code with an authenticator app such as Google Authenticator or Duo Mobile
  6. Enter in the 6-digit code that the authenticator app generates
  7. Click on the Submit button
  8. Record the Backup Code in a safe place
  9. Click the Close button

2FA 003.png

Within the Admin Area

Configuring Time Based Tokens in Admin Area

In turn, Administrator Users can perform the following actions to setup Two-Factor Authentication on their account using the Time Based Tokens service.

  1. From the Admin Area, begin by navigating to the My Account section
  2. Toggle the Two-Factor Authentication setting to On
  3. Select the Time Based Tokens service
  4. Click on the Get Started button
  5. Scan the QR code with an authenticator app such as Google Authenticator or Duo Mobile
  6. Enter in the 6-digit code that the authenticator app generates
  7. Click on the Submit button
  8. Record the Backup Code in a safe place
  9. Click the Close button

2FA 004.png

Troubleshooting

The code you entered did not match what was expected. Please try again.

Seeing this error when using the time based tokens 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 the server where WHMCS is installed 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. 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. In that scenario, you must change the time on your device to 00:01 so that they both match.

Syncing the server with NTP to ensure the time is exactly right may also help to resolve this. Most servers will revert to the internal hardware clock on reboot/power on, so you will need to sync any changes from NTP to the hardware clock as well.

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. Most servers will revert to the internal hardware clock on reboot/power on, so you will need to sync any changes from NTP to the hardware clock as well.

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

Retrieved from "http://3.17.75.209/index.php?title=Two-Factor_Authentication&oldid=27477"