Skip navigation
Documentation

Duo for Drupal

Contents

Duo integrates with for Drupal 6.x/7.x sites to add two-factor authentication to your logins, complete with inline self-service enrollment and authentication prompt. The code is open-source and available on GitHub.

This application is not compatible with Drupal 8. If you'd like to be notified when Duo releases login protection for Drupal 8, please contact Support.

First Steps

Before starting:

  1. Sign up for a Duo account.
  2. Log in to the Duo Admin Panel and navigate to Applications.
  3. Click Protect an Application and locate Drupal in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.)
  4. Use NTP to ensure that your server's time is correct.

Install the Duo Module

Drupal 7 installation

First, download the latest Drupal 7.x module from the Duo project page on Drupal.org.

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

First, download the latest Drupal 6.x module from the Duo project page on Drupal.org.

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

Ready to Get Started?

Sign Up Free