Skip navigation
Documentation

Duo for WordPress - Duo Universal Prompt

Last Updated: May 23rd, 2024

Contents

Duo's WordPress plugin enables two-factor authentication for WordPress logins, offering inline self-service enrollment and authentication with Duo Universal Prompt. The code is open-source and available on GitHub.

Support for the traditional Duo Prompt experience and Duo Prompt delivery via iframe ended on March 30, 2024.

See the update instructions for WordPress to update an existing deployment of the iframe-based WordPress software to the latest release. Authenticating once with the updated Duo software is a required step before you can enable the Duo Universal Prompt for your existing WordPress application.

Please visit the Duo Universal Prompt Update Guide for more information about the traditional Duo Prompt end of support.

First Steps

  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 the 2FA-only entry for WordPress in the applications list. Click Protect to the far-right to configure the application and get your Client ID, Client secret, 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.

    Previously, the Client ID was called the "Integration key" and the Client secret was called the "Secret key".

Treat your secret key like a password

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!

Duo Universal Prompt

The Duo Universal Prompt provides a simplified and accessible Duo login experience for web-based applications, offering a redesigned visual interface with security and usability enhancements.

Universal Prompt Traditional Prompt
 Duo Push in Universal Prompt  Duo Push in Traditional Prompt

For WordPress applications created before March 2024, migration to Universal Prompt is a three-step process:

  1. Install an update for the WordPress application, which implements a redirect to Duo during authentication to support the Universal Prompt.
  2. Authenticate with Duo 2FA using the updated application so that Duo makes the Universal Prompt activation setting available in the Admin Panel. This first authentication after updating shows the traditional Duo prompt in a redirect instead of an iframe.
  3. From the Duo Admin Panel, activate the Universal Prompt experience for users of that Duo WordPress application if the traditional prompt is still selected. Once activated, all users of the application see the Duo Universal Prompt in a redirect.

If you created your WordPress application before March 2024, it's a good idea to read the Universal Prompt Update Guide for more information, about the update process and the new login experience for users, before you activate the Universal Prompt for your application.

New WordPress Applications

When you install the latest version of Duo for WordPress you're ready to use the Universal Prompt. WordPress applications created after March 2024 have the Universal Prompt activated by default. If you're configuring WordPress now, proceed with the installation instructions in this document.

The "Universal Prompt" area of the application details page shows that this application is "Activation complete", with these activation control options:

  • Show traditional prompt: Your users experience Duo's traditional prompt via redirect when logging in to this application.
  • Show new Universal Prompt: (Default) Your users experience the Universal Prompt via redirect when logging in to this application.

Universal Prompt Info - Activation Complete for Universal Prompt

Existing WordPress Applications

Duo for WordPress needs a software update installed to support the Universal Prompt. The "Universal Prompt" section of your existing WordPress application reflects this status as "Update required". To update Duo for WordPress application to a newer version, follow the update directions below.

Universal Prompt Info - Update Required

Once a user authenticates to Duo for WordPress via the updated Duo plugin, the "Universal Prompt" section of the WordPress application page reflects this status as "Ready to activate", with these activation control options:

  • Show traditional prompt: (Default) Your users experience Duo's traditional prompt via redirect when logging in to this application.
  • Show new Universal Prompt: Your users experience the Universal Prompt via redirect when logging in to this application.

Universal Prompt Info - Application Ready for Universal Prompt

In addition, the "Integration key" and "Secret key" property labels for the application update to "Client ID" and "Client secret" respectively. The values for these properties remain the same.

Activate Universal Prompt

Activation of the Universal Prompt is a per-application change. Activating it for one application does not change the login experience for your other Duo applications.

Enable the Universal Prompt experience by selecting Show new Universal Prompt, and then scrolling to the bottom of the page to click Save.

Once you activate the Universal Prompt, the application's Universal Prompt status shows "Activation Complete" here and on the Universal Prompt Update Progress report.

Universal Prompt Info - Universal Prompt Activation Complete

Should you ever want to roll back to the traditional prompt, you can return to this setting and change it back to Show traditional prompt. However, this will still deliver the Duo prompt via redirect, not in an iframe. Keep in mind that support for the traditional Duo prompt ended for the majority of applications in March 2024.

Universal Update Progress

Click the See Update Progress link to view the Universal Prompt Update Progress report. This report shows the update availability and migration progress for all your Duo applications. You can also activate the new prompt experience for multiple supported applications from the report page instead of visiting the individual details pages for each application.

Install and Configure the Plugin

To install and configure the Duo Universal plugin, proceed as follows:

Install the Duo Plugin from the Plugin Directory

  1. Log in to your WordPress Dashboard as an administrator.

  2. Navigate to PluginsAdd New in the left navigation bar. Then search for "Duo Security" and click Install Now for the Duo Universal plugin.

    Add Plugins Search
  3. Click Activate Plugin after installing the Duo plugin:

    Activate Duo Plugin
  4. Proceed to Configure the Duo Plugin.

Manually Upload the Duo Plugin

To install the Duo Universal plugin without using the WordPress Plugin directory:

  1. Download the Duo Universal plugin as a zipped package from WordPress.

  2. In the WordPress console go to PluginsAdd New and click the Upload Plugin button.

  3. Click Choose File and select the duo-universal.n.n.n.zip package you downloaded (where n.n.n reflects the actual plugin version). Click Install Now to upload Duo's plugin to your WordPress site.

    Upload Duo Plugin
  4. Click Activate Plugin after installing the Duo plugin:

    Activate Duo Plugin
  5. Proceed to Configure the Duo Plugin.

Configure the Duo Plugin

  1. After activation, click Settings to configure the plugin.

    Duo Universal Authentication Settings
  2. Copy your Client ID, Client secret, and API hostname from the Duo WordPress application you created earlier in the Duo Admin Panel and paste the values into WordPress.

  3. (Optional) The "Failmode" setting determines plugin behavior if Duo’s authentication service becomes unreachable. Leave it set to open to allow users to log in if MFA is unavailable. Change to closed to deny all login attempts if there is a problem contacting the Duo service. Default: open.

  4. Select which WordPress user roles need to authenticate using Duo. For example, you may only require those users with the "Administrator" role to use two-factor authentication, or require all roles to use two-factor.

  5. To fully secure your WordPress site we recommend that you disable XML-RPC. However, this will prevent use of offline Weblog clients and the WordPress mobile app.

    Configure Duo Universal Plugin Main Settings
  6. Click Save Changes to complete configuration.

Test Your Setup

To test your setup, log into WordPress using the hostname or fully-qualified domain name URL. Successful verification of your username and password redirects you to Duo. Complete Duo two-factor authentication when prompted and then you'll return to WordPress to complete the login process.

Duo Universal Prompt

Update the Duo Universal Plugin

To update an existing Duo Universal plugin, install the most recent version:

  1. Log into your WordPress Dashboard as an administrator.

  2. If a newer version of the Duo plugin exists then you'll see a notification icon under both Home - Updates and Plugins. Click either one to view the available update.

  3. WordPress lists the available plugin updates. Check the box next to the Duo Universal plugin to select it, and then click the Update Plugins button (if you clicked the Updates navigational link in step #2), or click the update now link in the Duo plugin description (if you clicked the Plugins navigational link in step #2).

    WordPress Plugin Updates
  4. WordPress updates the Duo plugin and reports status when complete.

    Duo Universal Plugin Updated

Migrate from the Legacy WordPress Plugin

There is no direct update path from the legacy Duo WordPress plugin to the Duo Universal WordPress plugin. To complete the migration:

  1. Deactivate the existing Duo WordPress plugin as having both versions of the plugins active at the same time can result in some unexpected behavior.
  2. Follow the instructions under “Install and Configure the Plugin”.
  3. Ensure the new Duo Universal Plugin is activated and delete the deprecated Duo WordPress plugin.

If you are updating an existing Duo WordPress deployment to use the Universal Prompt, you will need to authenticate once using the updated Duo Universal plugin first before you can enable the Universal Prompt for WordPress in Duo.

Troubleshooting

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

Network Diagram

WordPress Network Diagram
  1. WordPress connection initiated
  2. Primary authentication
  3. WordPress connection established to Duo Security over TCP port 443
  4. User completes Duo two-factor authentication via the interactive web prompt served from Duo's service and their selected authentication factor.
  5. WordPress receives authentication response
  6. WordPress session logged in