Difference between revisions of "DuoSecurity"

From WHMCS Documentation

(→‎WHMCS DuoSecurity Account Migration)
 
(17 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
[http://docs.whmcs.com/Two-Factor_Authentication < Back to Two-Factor Authentication]
 
[http://docs.whmcs.com/Two-Factor_Authentication < Back to Two-Factor Authentication]
  
−
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> This page describes a feature available in version 7.0 and above</div>
+
Duo® Security increases security with [[Two Factor Authentication]] (2FA). 2FA using Duo Security combines traditional account credentials (like a username and password) with a code or other verification from a device like a smart phone. Requiring both to log in decreases the threat of a leaked password.  
  
−
==What is DuoSecurity==
+
Use of Duo Security is free for up to 10 accounts, and the Duo® Mobile app is available on all major smartphone platforms.
−
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.  
+
<div class="docs-alert-info">
−
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.
+
In WHMCS 8.9 and later, our Duo Security integration uses [https://guide.duo.com/universal-prompt Duo Universal Prompt], which uses Duo Push by default. This pushes login or transaction details to your phone, allowing for immediate one-tap approval. If you already used Duo Security with the previous integration, you '''must''' log in to the Duo portal and upgrade your API credentials to use Duo Universal Prompt.
 +
 
 +
* 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's support team cannot troubleshoot issues with iframe-based Duo Prompt after this date.
 +
* After you upgrade to WHMCS 8.9 or later, we '''strongly''' recommend activating [https://guide.duo.com/universal-prompt Duo Universal Prompt] in your Duo customer portal to ensure continued functionality. If you do not do this, your customers may experience problems.
 +
* You will require a Duo Security account with an account level of '''Duo MFA''' or higher in order to access the Duo API. [https://go.whmcs.com/918/duo-security-signup Click here to sign up].
 +
</div>
 +
 
 +
== Configuring Duo Security ==
  
−
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.  
+
Before you can configure Duo Security globally in WHMCS, you must perform additional steps to retrieve your Duo credentials.
  
−
<div class="docs-alert-info">
+
To configure Duo Security in WHMCS:
−
You will require your own Duo Security account. A 'Duo MFA' or higher level account is required to access the necessary API: [http://go.whmcs.com/918/duo-security-signup Signup Here].
+
 
−
</div>
+
# Log in to [https://admin.duosecurity.com/ your Duo Security account].
 +
# Click '''Applications''' in the left sidebar.
 +
# Click '''Protect an Application'''.
 +
# Perform the appropriate step for your WHMCS version:
 +
#* For WHMCS 8.9 and later, click '''Protect this Application''' under '''Web SDK'''.
 +
#* For WHMCS 8.8 and earlier, click '''Protect this Application''' under '''Auth API'''.<div class="docs-alert-info">If you don't see this option, contact Duo support.</div>
 +
# Retrieve the following values:  [[File:duo-configuration.png|thumb|Duo Universal Prompt credentials (WHMCS 8.9 and later)]]
 +
#* For WHMCS 8.9 and later, retrieve the '''Client ID''', '''Client Secret''', and '''API hostname''' values.
 +
#* For WHMCS 8.8 and earlier, retrieve the '''Integration Key''', '''Secret Key''', and '''API hostname''' values.
 +
# Go to '''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'''.
 +
# Click '''Activate''' for '''Duo Security'''.
 +
# To enable Duo Security as a two-factor option for staff, check '''Enable for Staff'''.
 +
# To enable Duo Security for customers, check '''Enable for Clients'''.
 +
# Enter the credentials and hostname that you retrieved from your Duo Security account.
 +
# Click '''Save Changes'''.
 +
 
 +
== Enabling Duo Security as an Admin User ==
 +
 
 +
To enable Duo Security for an admin:
 +
 
 +
# Perform the steps above to configure Duo Security.
 +
# Navigate to the '''My Account''' page within the WHMCS Admin Area.  
 +
# Click '''Enable Two-Factor Authentication'''.
 +
# Follow the instructions to complete the setup process.
  
−
==Configuration==
+
== Enabling Duo Security as a Client ==
−
[[File:Duo1.png|thumb|Protect an Application]][[File:Duo2.png|thumb|Protect Auth API]]
 
−
First Login to your account on the [https://admin.duosecurity.com/ DuoSecurity website]:
 
−
# Click ''Applications'' in the left sidebar
 
−
# Click ''Protect an Application''
 
−
# Locate the '''Auth API''' option
 
−
# Beneath it click ''Protect this Application''
 
−
# Take note of following values:
 
−
* Integration Key
 
−
* Secret Key
 
−
* API hostname
 
  
−
Now login to your WHMCS Admin area as a Full Administrator user:
+
To enable Duo Security as a client:
−
[[File:Duo3.png|thumb|Complete configuration in WHMCS]]
 
−
# Navigate to '''Setup > Staff Management > Two-Factor Authentication'''
 
−
# Click the "Activate" button next to Duo Security
 
−
# To enable Duo Security as a two-factor option for staff and/or clients, tick the corresponding ''Enable for'' checkboxes.
 
−
# Enter the Integration Key, Secret Key and API Hostname you noted down earlier into the corresponding fields.
 
−
# Click ''Save Changes''
 
  
−
Once a member of staff or client has [[Security_Modules#Enable_for_Clients|activated Two Factor Authentication]] on their account, upon the next login they will be prompted to complete the DuoSecurity registration process.
+
# Log in to the WHMCS Client Area.
 +
# Go to  '''Account > My Account > Security Settings''' or, prior to WHMCS 8.0, '''My Account > Security Settings'''.
 +
# Click '''Enable Two-Factor Authentication'''.
 +
# Follow the instructions to complete the setup process.
  
−
==WHMCS DuoSecurity Account Migration==
+
On all future login attempts, the client will be asked to complete the Two-Factor Authentication process.
  
−
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.
+
==Using Existing Duo Accounts With WHMCS==
  
−
A phased approach has been implemented for the transition.
+
The WHMCS Duo integration uses the following format for admins that it transmits to Duo:
  
−
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.
+
<div class="source-cli">
 +
adminemailaddress:adminemailaddress:whmcslicensekey  
 +
</div>
  
−
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.
+
You can use existing Duo accounts or users to complete two-factor authentication into the Admin Area. To do this, use the alias function in Duo to create an alias for the admin. For more information, see Duo's [https://help.duo.com/s/article/aliases-guide?language=en_US Aliases Guide ] documentation.
  
−
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.
+
== Reactivating a user ==
 +
 +
When a user replaces or loses a two-factor device, they will need to reauthenticate DuoSecurity in order to enable the prompt. To achieve this, an admin will need to delete and restore the users from within the Duo dashboard.
 +
 +
For more information, see [https://duo.com/docs/administration-users#activating-duo-mobile Duo's documentation].
  
−
===Configuring your own DuoSecurity API Credentials===
+
== Troubleshooting ==
  
−
# [http://go.whmcs.com/918/duo-security-signup Signup for an account with DuoSecurity]
+
=== The second factor you supplied was incorrect. Please try again ===
−
# Login to your DuoSecurity account
 
−
# Click ''Applications'' in the left sidebar
 
−
# Click ''Protect an Application''
 
−
# Locate the '''Auth API''' option
 
−
# Beneath it click ''Protect this Application''
 
−
# Take note of following values: Integration Key, Secret Key & API hostname
 
−
#Now login to your WHMCS Admin area as a Full Administrator user:
 
−
# Navigate to '''Setup > Staff Management > Two-Factor Authentication'''
 
−
# Enter the Integration Key, Secret Key and API Hostname you noted down earlier into the corresponding fields.
 
−
# 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.
+
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.
  
−
==Common Errors==
+
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 [http://en.wikipedia.org/wiki/Network_Time_Protocol NTP] to verify the time will resolve this.
−
===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 [http://en.wikipedia.org/wiki/Network_Time_Protocol NTP] to ensure the time is exactly right will resolve this.
+
Different timezones are taken into account, ensuring that these differences won't cause a problem.
  
−
Different time-zones are taken into account, so time-zone 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 [[#Configuring_Duo_Security|following the steps above]].

Latest revision as of 15:30, 18 March 2024

< Back to Two-Factor Authentication

Duo® Security increases security with Two Factor Authentication (2FA). 2FA using Duo Security combines traditional account credentials (like a username and password) with a code or other verification from a device like a smart phone. Requiring both to log in decreases the threat of a leaked password.

Use of Duo Security is free for up to 10 accounts, and the Duo® Mobile app is available on all major smartphone platforms.

In WHMCS 8.9 and later, our Duo Security integration uses Duo Universal Prompt, which uses Duo Push by default. This pushes login or transaction details to your phone, allowing for immediate one-tap approval. If you already used Duo Security with the previous integration, you must log in to the Duo portal and upgrade your API credentials to use Duo Universal Prompt.

  • Duo has announced that support for the previous iframe-based Duo Prompt will end on March 30, 2024. Duo's support team cannot troubleshoot issues with iframe-based Duo Prompt after this date.
  • After you upgrade to WHMCS 8.9 or later, we strongly recommend activating Duo Universal Prompt in your Duo customer portal to ensure continued functionality. If you do not do this, your customers may experience problems.
  • 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

Before you can configure Duo Security globally in WHMCS, you must perform additional steps to retrieve your Duo credentials.

To configure Duo Security in WHMCS:

  1. Log in to your Duo Security account.
  2. Click Applications in the left sidebar.
  3. Click Protect an Application.
  4. Perform the appropriate step for your WHMCS version:
    • For WHMCS 8.9 and later, click Protect this Application under Web SDK.
    • For WHMCS 8.8 and earlier, click Protect this Application under Auth API.
      If you don't see this option, contact Duo support.
  5. Retrieve the following values:
    Duo Universal Prompt credentials (WHMCS 8.9 and later)
    • For WHMCS 8.9 and later, retrieve the Client ID, Client Secret, and API hostname values.
    • For WHMCS 8.8 and earlier, retrieve the Integration Key, Secret Key, and API hostname values.
  6. Go to Configuration () > System Settings > Two Factor Authentication or, prior to WHMCS 8.0, Setup > Staff Management > Two-Factor Authentication.
  7. Click Activate for Duo Security.
  8. To enable Duo Security as a two-factor option for staff, check Enable for Staff.
  9. To enable Duo Security for customers, check Enable for Clients.
  10. Enter the credentials and hostname that you retrieved from your Duo Security account.
  11. 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.

Using Existing Duo Accounts With WHMCS

The WHMCS Duo integration uses the following format for admins that it transmits to Duo:

adminemailaddress:adminemailaddress:whmcslicensekey

You can use existing Duo accounts or users to complete two-factor authentication into the Admin Area. To do this, use the alias function in Duo to create an alias for the admin. For more information, see Duo's Aliases Guide documentation.

Reactivating a user

When a user replaces or loses a two-factor device, they will need to reauthenticate DuoSecurity in order to enable the prompt. To achieve this, an admin will need to delete and restore the users from within the Duo dashboard.

For more information, see Duo's documentation.

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.

Retrieved from "http://3.17.75.209/index.php?title=DuoSecurity&oldid=34488"