Duo Two-Factor Authentication for Drupal 6 and 7 (Deprecated)

End of Support Information

The last date of support for Duo's two-factor solution for Drupal 6 and 7 was January 28, 2021.

Duo will no longer provide updates or fixes for this application. In addition, Duo Support will not provide configuration or troubleshooting assistance for the Drupal application.

If you created a Duo Drupal application before January 28, 2021:

• Your existing Duo Drupal installation will continue providing two-factor authentication for user logins past the end of support of the traditional Duo Prompt on March 30, 2024 but will no longer function past the end of life date.
  • The Duo Drupal application is ineligible for update to Universal Prompt.
• You may view and manage existing Duo Drupal applications in the Duo Admin Panel.
• No new Duo Drupal applications may be created in the Duo Admin Panel.

If you did not create a Duo Drupal application before January 28, 2021:

• No new Duo Drupal applications may be created in the Duo Admin Panel.

Duo recommends that you explore a third-party Drupal module that provides two-factor authentication, like Drupal TFA. Another option is to develop your own two-factor authentication module for Drupal using Duo’s Web SDK, or to migrate to Duo Single Sign-On for Drupal.

Review the Duo End of Sale, Last Date of Support, and End of Life Policy.

These installation instructions remain available as a reference for Duo customers who deployed the Duo Drupal module before January 28, 2021.

First Steps

Before starting:

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications → Protect an Application.
3. Locate the entry for Drupal with a protection type of "2FA" in the applications list. Click Protect to the far-right to configure the application and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications in Duo and additional application options.
4. Use NTP to ensure that your server's time is correct.
5. Download the latest Drupal 7.x or 6.x module from the Duo project page on Drupal.org

Install the Duo Module

Drupal 7 installation

Log in to your Drupal site as an administrator. Navigate to Modules → Install new module from the administrator menu. If you don't see the "Install new module" link, make sure that the "Update manager" module is enabled.

Upload the Duo module tarball or paste in the link directly to the module installer and click install. After installation is complete, make sure to enable the Duo module in the "Other" section of the modules list.

For a more detailed guide to installing contributed modules, see the Drupal 7 install documentation.

Drupal 6 installation

Like other Drupal 6 modules, you need to upload the unarchived module folder to your Drupal installation in the /sites/all/modules/ directory.

After uploading the folder, you should be able to enable the module from the Administer → Modules page.

For a more detailed guide to installing contributed modules, see the Drupal 6 install documentation.

Configure the Duo Module

Navigate to the Duo module configuration page.

In Drupal 7, you can find it at Configuration → System → Duo two-factor configuration from your administrator menu.

In Drupal 6, you can find it at Administer → Site configuration → Duo two-factor configuration.

Copy and paste in the integration key, secret key, and API hostname from the application you created in the Duo administrative interface.

Save the configuration and verify that the enrollment or login form shows up when you click the link in the form preview section. If you see an error message when you click the form preview link, double-check your configuration settings.

If the enrollment or login form shows up properly in the form preview link, the Duo module is configured successfully.

Set Up the User Permissions

The Duo module allow you to select which user roles will require two-factor authentication to log in.

In Drupal 7, you can configure permissions from People → Permissions in the administrator menu.

In Drupal 6, you can configure permissions from Administer → User management → Permissions in the administrator menu.

Roles that are enabled with the 'log in with duo' permission will be required to log in with two-factor authentication.

Test Your Setup

To test your Drupal two-factor authentication setup, go to the login URL. After you complete primary authentication, the Duo enrollment/login prompt appears.

After entering your Drupal username and password, the Duo enrollment or authentication prompt appears.

Customize the Login Page Style

While the default Duo module ships with a plain login page, the login page can be easily customized and styled to fit in with the rest of your Drupal site.

The module includes a resources folder that contains the files duo_header.php, duo_footer.php and custom.css which you can edit to achieve whatever visual style you desire for the login page.

Tips

If you have any troubles with the installation and configuration, be sure to disable the Duo module before logging out, to avoid being locked out of the Drupal administrator interface.

If you find yourself locked out, you will need to remove the duo folder from your Drupal installation, or rename duo.module to duo.module.disabled (re-enable it by removing the .disabled extension). The /duo folder is commonly located in /sites/all/modules/duo

There is a known incompatibility with the third-party Password Policy module when the "Password Expiration Warning" setting is configured. Duo recommends setting the "Password Expiration Warning" to 0 or disabling the Password Policy module.

Troubleshooting

Need some help? Take a look at our Drupal Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

1. Drupal connection initiated
2. Primary authentication
3. Drupal connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service
5. Drupal receives authentication response
6. Drupal session logged in