Difference between revisions of "Two-Factor Authentication"

From WHMCS Documentation
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
Two-Factor Authentication
+
Two-Factor Authentication adds a layer of security by adding a second step to the login process. It takes something you know (for example, your password) and adds a second factor, typically from something you have (such as your phone). Requiring both to log in decreases the threat of a leaked password.
  
−
==Introduction==
+
You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Two-Factor Authentication''' or, prior to WHMCS 8.0, '''Setup > Staff Management > Two-Factor Authentication'''.
  
−
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.
+
WHMCS includes three Two-Factor Authentication services.
−
 
+
−
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===
−
 
+
−
===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.  
−
 
 
−
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).
 
  
 +
We recommend enabling Time-Based Tokens, and WHMCS enables this 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, 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.
−
 
+
−
Detailed configuration instructions are located at http://docs.whmcs.com/Duo_Security
+
<div class="docs-alert-info">
−
 
+
* Duo has announced that support for the previous iframe-based Duo Prompt will [https://duo.com/docs/universal-prompt-update-guide end on March 30, 2024]. Duo Security will '''not''' function in WHMCS 8.8 and earlier after this date.
 +
* After you upgrade to WHMCS 8.9 or later, we recommend activating [https://guide.duo.com/universal-prompt Duo Universal Prompt] in your Duo customer portal to ensure continued functionality.
 +
</div>
 +
 +
For more information, see [[Duo Security]].
 +
 
===YubiKey===
 
===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.
+
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 [https://www.yubico.com/ from Yubico directly].
−
 
+
 
==Enabling Two-Factor Authentication==
 
==Enabling Two-Factor Authentication==
−
 
+
 
[[File:2FA_006.png|thumb|Time Based Tokens Configuration]]
 
[[File:2FA_006.png|thumb|Time Based Tokens Configuration]]
 +
 +
To enable Two-Factor Authentication, follow the steps below:
  
−
To enable Two-Factor Authentication on an installation, follow the steps below:
+
# Click '''Activate''' under the service that you would like to enable.
−
 
+
# Select one or both of '''Enable for use by Clients''' and '''Enable for use by Administrative Users'''.
−
# From the Admin Area, begin by navigating to ''Setup > Staff Management > Two-Factor Authentication''
+
# If applicable, configure any additional '''Configuration Settings'''.
−
# Click the ''Activate'' button under the service that you would like to enable
+
# Click '''Save'''.
−
# 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''
+
You can repeat these steps for each service that you want to enable.
−
# 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]]
 
[[File:2FA_001.png|border|800px]]
−
 
+
 
===Global Two-Factor Authentication Settings===
 
===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.
+
The '''Global Two-Factor Authentication Settings''' options allow you to forcibly enable Two-Factor Authentication for Accounts, Users, and Admins 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.
+
To use this feature, select your options and click '''Save Changes'''. If a user has not yet configured Two-Factor Authentication, the system will force them to the next time they sign in to WHMCS.
−
 
+
 
[[File:2FA_002.png|border|800px]]
 
[[File:2FA_002.png|border|800px]]
  
 
==Using Two-Factor Authentication==
 
==Using Two-Factor Authentication==
 +
 +
Client accounts, users, and admins can begin to use Two-Factor Authentication after you have activated one or more services and configured the installation.
  
−
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, see [[Using Two-Factor Authentication]].
−
 
 
−
===Within the Client Area===
 
−
 
 
−
[[File:2FA_005.png|thumb|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.
 
−
 
 
−
# From the Client Area, being by navigating to ''Hello, Name! > Security Settings''
 
−
# Click on the ''Click here to Enable'' button
 
−
# 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
 
−
 
 
−
[[File:2FA_003.png|border|800px]]
 
−
 
 
−
===Within the Admin Area===
 
  
−
[[File:2FA_005.png|thumb|Configuring Time Based Tokens in Admin Area]]
+
==Lost/Unavailable Device==
  
−
In turn, Administrator Users can perform the following actions to setup Two-Factor Authentication on their account using the ''Time Based Tokens'' service.
+
[[Two-Factor Authentication]] requires a secondary device in order to log in. Because of this, some users will inevitably need help when their device is lost or otherwise unavailable.
  
−
# From the Admin Area, begin by navigating to the ''My Account'' section
+
For more information, see [[Logging In Without Your Two-Factor Authentication Device]].
−
# 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
 
−
 
 
−
[[File:2FA_004.png|border|800px]]
 
  
 
==Troubleshooting==
 
==Troubleshooting==
 +
 +
====The code you entered did not match what was expected. Please try again.====
 +
 +
Seeing this error when using the Time-Based Token method means that the six characters your device generated do not match the six numbers WHMCS expected. Usually, this indicates that the time on your device (for example, your phone or tablet) and on the WHMCS server are 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 [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 boot or reboot, so you will need to sync any changes from NTP to the hardware clock.
 +
 +
This provides support for time zone differences, so they are unlikely to cause problems.
 +
 +
====The second factor you supplied was incorrect. Please try again.====
  
−
'''The code you entered did not match what was expected. Please try again.'''<br /><br />
+
Seeing this error when activating the DuoSecurity method for the first time indicates that the entered code does not match what DuoSecurity expects. This indicates that the time on your server does not match DuoSecurity's clocks.
−
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 make sure to sync the server time 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.
−
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 will resolve this. Most servers will revert to the internal hardware clock when they boot or reboot, so you will need to sync any changes from NTP to the hardware clock.
−
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.
+
−
 
+
This provides support for time zone differences, so they are unlikely to cause problems.
−
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.'''<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.
 
−
 
 
−
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 [http://en.wikipedia.org/wiki/Network_Time_Protocol 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.
 

Latest revision as of 17:04, 7 February 2024

Two-Factor Authentication adds a layer of security by adding a second step to the login process. It takes something you know (for example, your password) and adds a second factor, typically from something you have (such as 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 or, prior to WHMCS 8.0, Setup > Staff Management > Two-Factor Authentication.

WHMCS includes three Two-Factor Authentication 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.

DuoSecurity

With DuoSecurity, 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 March 30, 2024. Duo Security will not function in WHMCS 8.8 and earlier after this date.
  • After you upgrade to WHMCS 8.9 or later, 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 Two-Factor Authentication

Time Based Tokens Configuration

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

  1. Click Activate under the service that you would like to enable.
  2. Select one or both of Enable for use by Clients and Enable for use by Administrative Users.
  3. If applicable, configure any additional Configuration Settings.
  4. Click Save.

You can repeat these steps for each service that you want 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 Accounts, Users, and Admins on their next login.

To use this feature, select your options and click Save Changes. If a user has not yet configured Two-Factor Authentication, the system will force them to the next time they sign in to WHMCS.

2FA 002.png

Using Two-Factor Authentication

Client accounts, users, and admins can begin to use Two-Factor Authentication after you have activated one or more services and configured the installation.

For more information, see Using Two-Factor Authentication.

Lost/Unavailable Device

Two-Factor Authentication requires a secondary device in order to log in. Because of this, some users will inevitably need help when their device is lost or otherwise unavailable.

For more information, see Logging In Without Your Two-Factor Authentication Device.

Troubleshooting

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

Seeing this error when using the Time-Based Token method means that the six characters your device generated do not match the six numbers WHMCS expected. Usually, this indicates that the time on your device (for example, your phone or tablet) and on the WHMCS server are 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 boot or reboot, so you will need to sync any changes from NTP to the hardware clock.

This provides support for time zone differences, so they are unlikely to cause problems.

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 entered code does not match what DuoSecurity expects. This indicates that the time on your server does not match 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. You must make sure to sync the server time 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 when they boot or reboot, so you will need to sync any changes from NTP to the hardware clock.

This provides support for time zone differences, so they are unlikely to cause problems.

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