An application binds Duo's two-factor authentication system to one or more of your services or platforms, such as a local network, VPN (virtual private network), CMS (content management system), email system, or hardware device. You can protect as many applications as you need, and administer each independently.
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 Access plan, and set up your Duo administrator account. See Getting Started for an overview of the entire Duo deployment process.
Role required: Owner, Administrator, or Application Manager.
Log into the Duo Admin Panel. To add a new application click Applications in the left sidebar, then click the Protect an Application button or the Protect an Application submenu item in the left sidebar. Alternatively, you can click the Add New... button in the top right of the Dashboard page and then click Application.
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 Beyond, Duo Access, and Duo MFA 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 to make it unique (e.g. "Cisco SSL VPN 1", "Cisco SSL VPN 2", etc.). Users see this application name in the loging 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.
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 hostname whitelisting (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.
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!
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.
You can also begin enrolling users now. Read Enrolling Users for details.
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 as end users of the application you just created.
Role required: Owner, Administrator, or Application Manager.
Configure additional settings from an application’s properties page. Click the Save Changes button at the bottom of the page after updating any of these settings.
Migration to Universal Prompt for your application is a two-step process:
As we add support for the Universal Prompt to applications, you'll see a new section on the details page of the application indicating your progress towards the Universal Prompt for that application.
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.
Most applications will require a Duo software update on your web application server. The application's Universal Prompt details will indicate availability of an application software update, with a link to the update guide where you can find the next steps.
After you complete the application update, the status changes to reflect that the application now supports the Universal Prompt. When the Universal Prompt end-user experience becomes available, you'll be able to activate it for a single Duo application from this area of the application's page. Until then, the "Activate Universal Prompt" setting remains inactive.
Most policy settings are visible to Duo Beyond, Duo Access, and Duo MFA plan customers. These plan customers can create and assign application and group policies that control device security, allowed authenticators, and more.
Duo MFA 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 and instructions for managing application policies.
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 Changes button at the bottom of the page when done.
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 manage their devices box. Click the Save Changes button at the bottom of the page when done.
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 "firstname.lastname@example.org" 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 "email@example.com" would all resolve to a single "jsmith" Duo user.
To turn on username normalization, click the radio button next to Simple.
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.
Enter any additional information about your application in the "Notes" field. The notes are only visible to administrators.
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 Changes button at the bottom of the page when done. You can select up to 100 permitted groups.
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.
This optional setting ensures only "approved" application hostnames may show users the Duo Prompt. This prevents displaying the Duo Prompt for this application 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.
The hostname whitelisting options only display on the application details page for applications that make use of referring sites. Duo applications that do not show a browser-based prompt and applications with Universal Prompt support are protected from this and do not show the setting.
While optional, Duo recommends enabling hostname whitelisting before onboarding your end-users, especially if you plan to allow use of U2F and WebAuthn authentication methods.
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. These entries should be listed 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 whitelisting feature 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.
WARNING: Removing an application may prevent user logins!
Be sure to remove Duo authentication from your product's configuration before you remove the corresponding application from the Duo Admin Panel. Depending on the application this could mean uninstalling Duo software from your systems, or updating your device or application settings to no longer include Duo in the authentication process.
To remove an application from Duo, view the application's configuration page in the Duo Admin Panel and click the Remove Application button at the top right.
Confirm that you want to remove the application.
The application is permanently removed from Duo. User logins that attempt to use the deleted integration fail if you did not remofe Duo from your configuration.