Support for Duo's two-factor solution for Drupal 6 and 7 ended on 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:
If you did not create a Duo Drupal application before January 28, 2021:
Duo recommends that you explore a third-party Drupal modules 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.
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.
Before starting:
The security of your Duo application is tied to the security of your secret key (skey). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!
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.
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.
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.
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.
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.
If you plan to permit use of WebAuthn authentication methods (security keys, U2F tokens, or Touch ID), Duo recommends enabling hostname whitelisting for this application and any others that show the inline Duo Prompt before onboarding your end-users.
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.
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.
Need some help? Take a look at our Drupal Knowledge Base articles or Community discussions. For further assistance, contact Support.
