Duo Administration - Protecting Applications

Before you can protect your applications with Duo, you'll first need to sign up for a Duo account, which offers a free 30-day trial of our Advantage plan, and set up your Duo administrator account. See Getting Started for an overview of the entire Duo deployment process.

Protect an Application

Role required: Owner, Administrator, or Application Manager.

1. Log into the Duo Admin Panel. To add a new application, navigate to Applications → Protect an Application. Alternatively, you can click the Add New... button in the top right of the Home page and then click Application.

2. The "Protect an Application" page lists the different types of services you can protect with Duo. The Protection Type column indicates how Duo protects that specific application.

   

   You can scroll down the page to browse all available applications, or start typing the name of your product in the space provided to filter the applications list. For example, type "ci" to view Cisco solutions.

   

   Click the Documentation for an application to review the requirements and configuration steps for integrating Duo into your service before adding the new application. If you don't see a "Documentation" link that means it's a partner application for which Duo doesn't host configuration instructions. You'll see a link for more information later once you create the application.

   If you don't see your specific product, use this table as a guide in selecting an appropriate application:

   To protect…	Choose this application…
   Local and remote (ssh) logins on Unix systems	UNIX Application
   SSL or IPSec VPN Logins	Check for your specific brand of VPN
   Other VPNs and remote access solutions that support RADIUS authentication	RADIUS
   Microsoft services like RDP or OWA	Look for your named application
   Any device or system that supports authentication via LDAP	LDAP Proxy
   Your own web applications	WebSDK (requires some programming proficiency)
   SAML 2.0 service providers	Check for your specific service provider or Generic Service Provider

   If you're coding your own two-factor authentication using Duo's Auth API choose the Auth API application. The Accounts API and Admin API applications are available to Duo Premier, Duo Advantage, and Duo Essentials plan customers. Please contact us to request access to the Accounts API.

   When you've located the application you want to protect with Duo, click the Protect button to the right of the application's name. This creates your new application with a default name (like "Cisco SSL VPN").

   If an application using the default name already exists, the new application's name has a number appended to make it unique (e.g. "Cisco SSL VPN 1", "Cisco SSL VPN 2", etc.). Users see this application name in the login request they receive each time they authenticate using Duo Push. You can change the application's name any time after creation from the "General" settings section of your application's properties page.

3. You'll be taken directly to the new application's properties page after creation. Here you can update the application's name and apply other settings like enabling the self-service portal or configuring allowed hostnames (find all settings described below in Application Options), or set policies for that application.

   The "Details" section near the top of the page shows your Integration key (ikey), Secret key (skey), and API hostname:

   

   Applications with Universal Prompt support rename the Integration key and Secret key to better align with the OAuth 2.0 specification. These values are now known as the "Client ID" or client_id and the "Client secret" or client_secret. The actual values for these properties remain the same (so when you update an application from the traditional Duo prompt there's no need to enter new application information).

   

   The integration key/Client ID and secret key/Client secret uniquely identify a specific application to Duo. The API hostname is unique to your account, but shared by all your applications. You'll need all these values when configuring your system to work with Duo. You may also need them if you contact Duo Support.

   Treat your Secret key or Client ID like a password

   The security of your Duo application is tied to the security of your Secret key (skey) or Client secret (client_secret). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

4. The next step after adding an application is to configure your appliance, device, application, service, or system to work with Duo. You'll find a link to the appropriate documentation in the highlighted "Setup Instructions" section at the top of each application's properties page.

   

5. You can also begin enrolling users now. Read Enrolling Users for details.

   Duo user accounts and admin accounts are distinct

   Duo administrator accounts are only used to log on to the Admin Panel. They can't be used to access devices or applications using Duo two-factor authentication. Be sure to also enroll your Duo admins as users if they need to log on to Duo protected services.

Connectivity Requirements

Some applications communicate from your network to Duo's cloud service on SSL TCP port 443. You'll see specific connectivity requirements mentioned on the Duo documentation page for the application you've selected.

Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review Duo Knowledge Base article 1337.

Effective June 30, 2023, Duo no longer supports TLS 1.0 or 1.1 connections or insecure TLS/SSL cipher suites. If you are unsure how this may affect your Duo deployment plans, please see the Duo Knowledge Base article Guide to TLS support for Duo applications and TLS 1.0 and 1.1 end of support for additional information.

Application Options

Role required: Owner, Administrator, or Application Manager.

Configure additional settings from an application’s properties page. Click the Save button at the bottom of the page after updating any of these settings. Read on for information about the available application settings.

Universal Prompt

Duo's next-generation authentication experience, the 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

The requirements for Universal Prompt are:

• Configure the application to support the Universal Prompt. This may involve installing a software upgrade with Universal Prompt support provided by Duo or one of our technology partners on your application server, or making a configuration change in the admin console of a cloud-hosted application where you use Duo.

  Duo partners are working to make application updates available for their developed integrations.

• In the Duo Admin Panel, enable the Universal Prompt experience for users of that application after the application has been updated with Universal Prompt support. Universal Prompt is activated by default when you create a new application that supports it.

The "Universal Prompt" section on the details page of the application indicates your progress and next steps towards the Universal Prompt for that application. 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.

Read the Universal Prompt Update Guide for more information about changes to the user authentication experience and the update process to support the new prompt, and watch the Duo Blog for future updates about the Duo Universal Prompt.

New Applications

When you create a new application of a type with Universal Prompt support, Duo activates Universal Prompt by default and the application's Universal Prompt status shows "Activation Complete" here and on the Universal Prompt Update Progress report.

Application using Universal Prompt

Follow the instructions for configuring Duo with Universal Prompt for your application.

If you see this status for a Duo Web SDK application you developed in-house, your application must utilize Web SDK v4 or the OIDC API before you can use the Universal Prompt.

If you did not develop the application, please contact the software vendor to confirm that they have made the necessary updates to support the Universal Prompt. We have granted support extensions for third-party Duo integrations when the software vendor has informed us of their intent to make the required updates. View the list of applications with support extensions in the Duo Knowledge Base article Which applications have been granted a Traditional Duo Prompt support extension?.

Web SDK applications that do not support the Universal Prompt continue to show the traditional Duo Prompt, and after the first authentication will show the Universal Prompt status as "Update Required" until updated with Web SDK v4.

Existing Applications

When Universal Prompt support becomes available for a given Duo application already in use by your organization, whether maintained by Duo or by a partner, the Universal Prompt details on that application's properties page in the Duo Admin Panel indicates availability of an application software update as "Update required" with a link to update instructions.

If you see the "Update required" status for a Duo Web SDK application you developed in-house, you will need to update your application from Web SDK v2 to Web SDK v4 before you can use the Universal Prompt.

If you did not develop the Web SDK application, please contact the software vendor that did to determine availability of the necessary update. We have granted support extensions for third-party Duo integrations when the software vendor has informed us of their intent to make the required updates. View the list of applications with support extensions in the Duo Knowledge Base article Which applications have been granted a Traditional Duo Prompt support extension?.

If you aren't sure how to proceed, contact us and provide information about the third-party application.

Your users continue to see the current Duo prompt experience until you apply the update and authenticate using the updated application, and then activate Universal Prompt for that application.

Application update available

If you see this status for a Duo Web SDK application you developed in-house, you will need to update your application from Web SDK v2 to Web SDK v4 before you can use the Universal Prompt.

If you did not develop the application, please contact the software vendor that did to determine availability of the necessary update.

When you view an application that supports Universal Prompt in the Admin Panel and we've detected the necessary update or configuration is in place, you'll see a pop-up asking if you want to activate the prompt now. If you click Activate Now, then the Universal Prompt will be activated right away. Click No, thanks to defer activating Universal Prompt until later.

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 that will have Universal Prompt support.

Application Updates

Many existing applications will require a Duo software update on your web application server before you can use the Universal Prompt. The application's Universal Prompt details show availability of an application software update, with a link to the update guide where you can find more information. You can't use the "Activate Universal Prompt" controls yet.

The status shows "Waiting on App Provider" when viewing the Universal Prompt information for an application created by one of Duo's technical partners that has no update available. Contact the application provider to request Duo Universal Prompt support.

Example: Application waiting on update availability

When an update becomes available, you complete the update, and Duo detects that users have logged in using the updated software, then the status changes to reflect that the application now supports the Universal Prompt. You can return to activate it for this Duo application from this area of the application's page. Until then, the "Activate Universal Prompt" setting remains inactive.

Universal Prompt Activation

The update details show that the application is ready for the new prompt experience. The status "Ready to activate" for updated applications reflects that you've done all the work required to update your application for the Universal Prompt.

Use the activation control options to determine the login experience for your users:

• Show traditional prompt: Your users experience Duo's traditional prompt when logging in to this application. Default setting for applications that do not support Universal Prompt.

• Show new Universal Prompt: Your users experience the Universal Prompt when logging in to this application. Default setting for applications that support Universal Prompt.

If you accept the Universal Prompt activation default when you create your new application in Duo, but then do not deploy a version of the Duo application integration that supports the Universal Prompt, once a user authenticates using the traditional iFrame-based prompt to that application then the Universal Prompt status shown for that application reverts to "Update Required", instructing you to apply the necessary updates to support the new prompt experience.

If you do not activate the Universal Prompt and deploy a version of the Duo application that includes Duo Prompt support, your users see Duo's traditional prompt when they authenticate to that application.

Application ready for Universal Prompt

Policy

Most policy settings are visible to Duo Premier, Duo Advantage, and Duo Essentials plan customers. These plan customers can create and assign application and group policies that control device security, allowed authenticators, and more.

Duo Essentials customers may create a policy for an individual application that affects all users of that application, or use the Global Policy to manage settings for all applications.

Duo Free plan users may apply only the New User policy via global and application policy.

See the Policy & Control documentation for more information about available policy restrictions, to learn the effective policy default settings, and to see instructions for managing global, application, and group policies.

Type and Name

The application "Type" shows what kind of Duo application you created. This field is read-only.

Users see the application's "Name" in the notification they receive each time they authenticate using Duo Push. To update, type in a new name and click the Save button at the bottom of the page when done.

Self-service Portal

Duo's self-service portal lets users add, update, and remove authentication devices. The self-service portal is an option for web-based and some SSL VPN applications that feature inline enrollment and authentication prompt. See the self-service portal documentation and Managing Your Devices in the Duo end user guide.

To enable this feature, check the Let users remove devices, add new devices, and reactivate Duo Mobile box. Click the Save button at the bottom of the page when done.

Username Normalization

The "Username normalization" option controls whether usernames entered for primary authentication should be altered before trying to match them to a Duo user account. With normalization off, the usernames "jsmith," "DOMAIN\jsmith," and "jsmith@domain.com" would be three separate users in Duo. When enabled, username normalization strips any domain information from the username received from the application before trying to match to a known Duo user, so "jsmith," "DOMAIN\jsmith," and "jsmith@domain.com" would all resolve to a single "jsmith" Duo user.

To turn on username normalization, click the radio button next to Simple.

Voice Greeting

The "Voice greeting" is read to users who select a phone call for authentication at the beginning of the verification call before the Duo instructions. You may customize the greeting as you wish.

Notes

Enter any additional information about your application in the "Notes" field. The notes are only visible to administrators.

Permitted Groups

With "Permitted Groups" Duo groups can be used to restrict active Duo user access to applications. See the Using Groups documentation for more information and detailed instructions.

To configure this setting, check the Only allow authentication from users in certain groups box and then click in the "Select groups" field to bring up a list of groups. Click on a group name to select it. You may also narrow down the group search results by typing a group name in the box. Click the Save button at the bottom of the page when done. You can select up to 100 permitted groups.

Administrative Unit

If you're using Administrative Units to delegate management of users and applications to certain admins, you can assign the unit that will administer this application. Restricted administrators who aren't assigned to that same administrative unit won't be able to view or manage this application after saving the assignment here.

Allowed Hostnames

The allowed hostnames options only display on the application details page for traditional Duo Prompt applications that make use of referring sites. Duo applications that do not show a browser-based prompt and applications with Universal Prompt support have built-in protection from this risk and therefore do not make this setting available.

This optional setting ensures only "approved" application hostnames may show users the traditional Duo Prompt in an iframe. This prevents displaying the traditional Duo Prompt for this application in an iframe on a web page you do not control, minimizing the risk of having your users tricked into authenticating on fraudulent web sites. When you limit which sites may send authentication traffic to Duo you ensure that your users authenticate only from known sites.

Check the box next to Only allow access for approved application hostnames to enable this setting and specify additional options.

In the Approved application hostnames entry field, enter the fully-qualified hostnames, IP addresses, or domain wildcard entries that represent the referring web sites your services or systems that you'll use with this Duo application. List these entries one per line. You can append an information comment on each line with a comma, followed by your descriptive text.

If a user tries to log into an application configured to use a Duo application that has the allowed hostnames enabled and restricted to known referring sites and the parent parameter used does not match the configured hostnames, then Duo blocks the user's authentication attempt, lets the user know that the request came from an unauthorized domain, and presents the referring URL information from the request to they can report to your IT or Corporate Security service desk.

View Your Applications

The Applications page of the Duo Admin Panel lists all of your applications, and shows the following information:

• Name: This is the free-text name of the application. You can change this at any time from the application's details page.
• Type: The Duo application type information for a given application. This information can't be changed.
• Application Policy and Group Policies: Display current policy assignments for each application.
• Alerts: Displays current support information.

You can sort your applications list by application name, and filter the list by application name or type with the search box. Click any application to view its properties, policies, and settings.

End-of-Support Applications

We will end support for Duo applications as needed, in accordance with our Duo End of Sale, Last Date of Support, and End of Life Policy. Any existing applications in your Duo customer account which are approaching or have reached the end of Duo support will receive a visual indicator reflecting this, and will show up in the "End of support" filtered view of the Applications list.

When a given Duo application type reaches the Duo end-of-support date, your existing applications may continue to work. However, you will no longer be able to create new instances of end-of-support applications after that date (even if you delete an existing end-of-support application).

Check the documentation for your specific end-of-support applications to determine if it will continue performing user authentications after the end-of-support date or if it requires reconfiguration of your device or application or migration to a new application for continued use.

Reset an Application Secret

If you suspect a compromise of the credentials of your Duo application you may want to reset the application's secret. To reset the client secret or secret key for a Duo application:

1. Determine the steps necessary to update the Duo secret value in your configured application after you perform the reset action.

2. Log into the Duo Admin Panel.

3. View the application's details page by either navigating to Applications and clicking on it in the applications list, or entering the name of the application in the search bar at the top of the Admin Panel and clicking on the result.

4. Once you are viewing the Duo application's details page, locate the "Details" section.

5. Click the Reset Secret Key or Reset Client Secret button on the right.

6. Confirm that you want to reset the secret for this application. Cancelling the action leaves the current application secret value unchanged.

   

7. Copy the new client secret or secret key value and update your configured application to use the new value. The Duo application fails to authenticate users until the updated client secret or secret key value is in use.

Remove an Application

To remove an application from Duo:

1. Uninstall the Duo application or disable Duo auhentication in the application, service, or device you have configured to use the Duo application you plan to remove.

2. Log into the Duo Admin Panel.

3. View the application's details page by either navigating to Applications and clicking on it in the applications list, or entering the name of the application in the search bar at the top of the Admin Panel and clicking on the result.

4. Once you are viewing the Duo application's details page, click the Remove Application action at the top right.

5. Confirm that you want to remove the application. Cancelling leaves the application intact.

   

The application is permanently removed from Duo. User logins that attempt to use the deleted integration fail if you did not previously remove Duo from your configuration before this action.

If you're deleting an application that has reached Duo end-of-support status then the warning additionally reminds you that you will not be able to create new instances of that end-of-support application.

Troubleshooting

Need some help? Try searching our Knowledge Base articles or Community discussions. For further assistance, contact Support.

All Duo customers have access to Level Up, our online learning platform offering courses on a variety of Duo administration topics. To access Level Up content, sign in with the same email address you use to sign in to the Duo Admin Panel.

Level Up course: Setting Up Duo: Protecting Applications