Skip navigation

Effective October 28, 2019 Duo Security will be transitioning to Cisco's Privacy Statement. View the Duo Privacy Data Sheet.

Documentation

Duo Device Health Application

Last Updated: September 20th, 2019

Duo helps you control access to your applications through the policy system by restricting access when devices do not meet particular security requirements.

This application is in public beta. Please email Endpoint Health Beta to request access or provide feedback.

Overview

The Duo Device Health application gives organizations more control over which laptop and desktop devices can access corporate applications based on the security posture of the device.

There are three key components:

  1. New Duo access policies that enforce application access based on device health.

  2. A native client application for macOS 10.13+ and Windows 10 that checks the security posture of the device when a user authenticates to an application protected by Duo with the device health access policy.

  3. Additional endpoint information provided in the Duo Admin Panel.

The first time users log in to an application protected by the web-based Duo Prompt with the Device Health Application policy enabled, they are prompted to download and install the Duo Device Health application. Once the Device Health application is installed, Duo blocks access if the device is unhealthy based on the Duo policy definition and informs the user of the reason the authentication was denied.

Duo Beyond customers will have full access to all Device Health controls when the feature is released, while Duo Access customers will have limited access to the collection of security posture attributes checked by the Device Health application.

When a user's device doesn't meet the security requirements of the device health policy, the Duo Device Health application provides the user with steps they can take to remediate their security posture as to align with the device health policy on the application.

Note: While the information that is collected by the Duo Device Health application is transmitted securely, this information is not uniquely identified. This means that a bad actor could intercept the Duo prompt and create their own response to the Duo prompt’s request for device health information and send that response up to Duo servers. Every authentication is uniquely identified, however, so a user cannot reasonably impersonate another user’s device information.

Understanding the Device Health Application Policy Options

The Device Health Application policy has three operating modes:

  • Don’t require users to have the app: When this option is selected the policy is not in effect and has no impact on end user access. As a result, end users are not prompted to install the Duo Device Health application when accessing a Duo-protected application. Data will not be collected from the Duo Device Health application, even when it is present on the machine.

  • Require users to have the app only: When this option is selected, but none of the Block Access options are selected, having the Device Health application installed and reporting information to Duo is required for access.

    End users running devices that can install the app (Windows 10 and macOS 10.13+) are prompted to download the app from the Duo prompt when attempting to access a Duo-protected application associated with the policy if they do not already have the app installed. Devices that are capable of running the app but do not have it installed and running will be blocked.

    The app will collect health information from the device, but Duo will not block the user from getting access if it does not pass the specific firewall, encryption, and password health checks. This means that the device will be able to access the application even if the device would not pass each health check.

    Devices that cannot run the app, including older versions of Windows, Linux, etc., will not be prompted to install the app and are effectively allowed to bypass the Device Health Application policy.

  • Require users to have the app and any blocking options: When this option is selected and one or more of the Block Access options are selected, the Device Health application must be installed and reporting information to Duo, and the device must satisfy the specified health requirements for access.

    End users running devices that can install the app (Windows 10 and macOS 10.13+) are prompted to download the app from the Duo prompt when attempting to access a Duo-protected application associated with the policy if they do not already have the application installed. Devices that are capable of running the app but do not have it installed and running will be blocked.

    The app collects health information from the device, and Duo will allow or block access to the protected application based on the device health options selected.

    Devices that cannot run the app, including older versions of Windows, Linux etc. will not be prompted to install the app and are effectively allowed to bypass the Device Health Application policy.

Note that the default “fail-open” Device Health Application policy allows you to enforce health checks for supported macOS and Windows 10 devices, while not blocking users who need to access an application using a non-supported device. You can optionally use Duo's Operating Systems policy to restrict other device types from accessing the application.

Enabling the Device Health Application Policy

Create a new policy with the Device Health Application setting. We recommend targeting a test group of users and a pilot application to start, with the Duo Device Health policy configured to require installation of the Device Health application but not to block access based on security posture. This collects information about access devices to see how deployment of both the application and policy would affect a sample population of your overall user base.

After deployment, you can review the states of devices accessing Duo-protected applications in the Admin Panel and then make assessments to identify the policy that will protect all of your users.

  1. Log on to the Duo Admin Panel as an administrator with the Owner or Administrator admin role.

  2. Navigate to the details page of the application you'll use to pilot the Device Health Application policy.

  3. Click the Apply a policy to groups of users link to assign the new Device Health Application policy to just the pilot group.

    Apply Group Policy

  4. Click the Or, create a new Policy link instead of selecting a policy to apply from the drop-down list.

    Create New Application Policy

  5. The policy editor launches with an empty policy.

  6. Enter a descriptive Policy Name at the top of the left column, and then click the Device Health Application policy item on the left. Change the selected option to Require users to have the app.

    Creating the Device Health Application policy

  7. Click the Create Policy button to save the settings and return to the "Apply a Policy" prompt, with the new Device Health Application policy selected. Start typing in the pilot group's name in the Groups field and select it from the suggested names.

    Apply the New Device Health Application Group Policy

  8. Click the Apply Policy button. The application page shows the new group policy assignment.

    Applied Device Health Application Group Policy

For more information about creating and applying group policies, see the Policy documentation.

Policy Interactions

You can combine a Device Health Application policy in combination with most other existing Duo policies including Browsers, Plugins and Operating Systems policies.

For example, you can create a custom policy that only allows access if the device:

  • Has an encrypted drive (using FileVault for macOS or BitLocker for Windows 10)
  • Has the host firewall enabled (using Application Firewall for macOS or Windows Defender Firewall for Windows 10)
  • Is protected by a password
  • Is accessing the application using a Chrome browser

In that case, enforce the first three conditions with the Device Health Application policy's "Block access if system password is not set.", "Block access if disk encryption is off.", and "Block access if firewall is off." options. Enforce the fourth condition in the same custom policy by checking all browser's except Chrome in the Browser policy's "Always block" option.

Device Health Application and Browser Policy

Operating System Granular Policy

In order to enforce access based on operating system (OS) version, you can use the existing OS policy in combination with the Device Health Application policy. When OS policy is applied to an application in combination with Duo Device Health policy, the Duo Device Health application will be the preferred source of information about an endpoint. This means that we will trust Duo Device Health application more than the user agent that is provided by the web requests to Duo.

The Operating Systems policy settings for macOS remain the same as when the Duo Device Health Application policy is not enabled, and continue to look for a macOS version similar to “10.14.6”. The Duo Device Health application provides information that is more trustworthy than the user agent reported by a browser or embedded web view.

Windows 10, however, has some additional changes in the OS policy when the Duo Device Health application is present. A browser user agent provides only a very limited amount of information about the Windows 10 version. The Duo Device Health application is able to retrieve the Windows 10 build version and the security patch version. This allows you to make policy decisions on specific Windows 10 versions to keep users up to date.

You’ll notice these changes under the Operating Systems policy section under the “Allow Windows devices” header. Open the dropdown under the “Encourage users to update” or “Block versions” label and you’ll see new Windows 10 version options.

When you select these options, additional information appears on the right side of the policy screen containing the details of activating an Operating Systems policy with this setting.

Windows OS Policy Changes

If the Duo Device Health application is not enabled, then the policy engine will fallback to simply “Windows 10” when assessing the windows version of the device accessing a Duo protected application.

Help Desk Text

The Duo Device Health application displays the same help message text configured in the Help Desk global setting.

The application shows this information in the "Need Help?" area whenever the Action Required dialog is displayed to help the user remediate authentication issues.

Duo Prompt with Device Health - Access Blocked

Device Health Reporting

Information reported from the Duo Device Health application is shown in the Admin Panel along with existing Endpoint information. The Authentication Log report, Endpoints page list and endpoint details, and endpoint information shown for Users will be augmented with details from the Duo Device Health application.

Application Log

With the Device Health Application policy and app installed, authentication log events show checks related to the Duo Device Health application in the "Access Device" information. Operating system version information includes the build version for macOS and the build and revision versions for Windows 10.

Device Health Information in Authentication Log

Endpoints List and Details

The Endpoints list receives additional filters that allow you to search for devices that have a particular state or OS version and build as reported by the Duo Device Health application. The device warning information for a given device now includes Device Health reasons, if present.

Device Health Information on Endpoints List

An endpoint's details page shows information from the Duo Device Health application.

Device Health Endpoint Details

Device Health Client Application

The Duo Device Health application analyzes a device to assess the status of its security posture and reports the results of this scan to Duo. During authentication, Duo applies and enforces access policies using the device security posture information. When access is denied by Duo due to the state of security posture on the device, the Duo Device Health application receives the results of the policy check and presents guidance for the user to remediate the issue and successfully login the next time.

Standalone Health Check

The home page of the Duo Device Health application will perform a health check on the system and report information to the user about the state of the device. This information is Duo’s basis of a secure device and does not apply directly to the evaluation of policy or authentication to an application protected by Duo.

The health check will be performed anytime the application is opened from the menu bar (macOS) or the System Tray (Windows).

macOS Example Health Check

Device Health Check - macOS

Windows 10 Example Health Check

Device Health Check - Windows

This health check provides your preferred Duo device security posture. By keeping all of these health checks green, Duo helps users keep a secure system and alleviates issues that may arise before an authentication is required. If this check reports an issue, such as the firewall turned off or OS out of date, users have the opportunity to perform remediation before attempting to authenticate.

macOS Example Health Check Alert with Remediation Guidance Device Health Check Failed - macOS

Device Health Check Remediation Guidance

Duo Prompt Authentication

When a user first lands at a Duo Prompt with Device Health enabled, a loading spinner appears while Duo performs the health check. If the Device Health application is already installed and running this spinner should only appear for a few seconds and the user will continue with authentication. In the event of a failed authentication, the user will be directed to remediate these issues.

When the Device Health application is not already installed and running users see a notice indicating that the Duo Prompt is attempting to launch the Device Health application.

Duo Prompt with Device Health App Notice

If the application was already installed and the browser has been told to remember it, the application launches and the health check will be performed without any need for interaction.

Otherwise, the user will be asked to download and install the application if it isn't currently installed. Duo Prompt with Device Health Install Prompt

Installing the Device Health Application from the Duo Prompt

To install the Device Health application:

  1. Click the Download Now button to download the installer.

  2. Windows users: Double-click the MSI file and follow the installer prompts.

    macOS users: Double-click the DMG file to extract the installer. Then double-click the extracted installer and follow the installer prompts.

Note that installation requires administrator privileges on both Windows and macOS. During installation if the user doesn't have admin rights they'll get prompted to provide credentials of an account that is able to install software on the client.

The user may be prompted to launch the application if it is already installed and just not running. For some browsers, this prompt may include a “Remember my choice” option (actual dialog format varies by browser and operating system). Having the application already running or checking the “Remember my choice”/”Always open these types of links” checkbox skips this prompt for future health checks.

If the Device Health application was uninstalled after selecting the “Remember my choice” checkbox, the operating system may still try to handle the request. On macOS this results in a “Search the App Store” dialog and on Windows this results in a “Look for an app in the Store” dialog.

On macOS click Cancel to close the dialog, and on Windows click OK to close it. After a short timeout the Duo Prompt in the browser loads the download prompt for the Device Health application.

When the Device Health application is running it analyzes the user’s system and report the state of the device to Duo. Policy will then be applied to the information received from the device, and if there is a problem with the health posture it will be reported back to the user. If the health posture is acceptable under the policy, no further interaction is required from the user and the Duo Device Health application.

Device Remediation

When an issue is reported by the Duo Device Health application, a red exclamation point will be shown next to the item that has an issue. This can happen as part of the standalone health check or as a report from an authentication failure due to device health.

If a user is attempting to access an application with a Device Health blocking policy, and their endpoint's security posture does not comply with the policy requirements, then the Duo Prompt notifies the user that they must take action before they can access the application.

Duo Prompt with Device Health - Access Blocked

The Duo Device Health application automatically opens with with information about why the authentication was denied.

Duo Prompt with Device Health - Access Blocked

Each non-compliant setting shown is a clickable item, that directs the user to instructions on how to fix the problem. Additionally, there is a link at the bottom that will take the user to a page in the application that briefly explains why keeping the device healthy is important.

Duo Prompt with Device Health - Remediation Instructions

Installing the Device Health Application

User Self-install During Authentication

The easiest way to distribute the Device Health application is to apply a Device Health policy to a web-based application that features Duo's inline authentication prompt, and then let users self-install the client when prompted during Duo authentication. Note that installation requires administrator privileges on both Windows and macOS.

Duo Prompt with Device Health Install Prompt

Send Download Links to Users

If you'd like to notify your users of the new Device Health application requirement and give them the chance to install the application ahead of time, you can send these client download links to your users:

macOS: https://dl.duosecurity.com/DuoDeviceHealth-latest.dmg

Windows 10: https://dl.duosecurity.com/DuoDeviceHealth-latest.msi

View checksums for Duo downloads here.

Note that installation requires administrator privileges on both Windows and macOS. During installation if the user doesn't have admin rights they'll get prompted to provide credentials of an account that is able to install software on the client.

Scripted or Managed Deployment

If you'd like to deploy the Device Health application via a scripted install or an endpoint management tool, download the installers using the links above, and use the following syntax to automate installation:

macOS: Extract the PKG installer from the downloaded DMG file first.

sudo installer -pkg /Volumes/DuoDeviceHealth/Install-DuoDeviceHealth.pkg -target /

Windows 10: Replace the example MSI file name with your actual MSI filename.

msiexec /i DuoDeviceHealth-1.0.0.msi

After the initial installation, the Duo Device Health application will check your device health at the time of authentication. You can verify installation by looking for the Duo Device Health application icon in the menu bar. When you click on the app icon, you will be able to view device health status.

Starting the Device Health Application

The Duo Device Health application starts automatically after installation. If it is not running when a user lands on the Duo Prompt, the prompt attempts to launch the application.

The Device Health application may also be started manually.

macOS Users:

  1. Open Spotlight with Command key ⌘ + Space bar.

  2. Type Duo Device Health and click the application search result.

Windows 10 Users:

  1. Open the Start Menu with Windows key ⊞ key or click the Windows logo on the far left of the taskbar.

  2. Type DuoDeviceHealth and click the application search result.

Uninstalling the Device Health Application

macOS Users:

  1. Click the Finder icon from the dock

  2. Locate the "Duo Device Health" app in the list of applications.

  3. Right-click the "Duo Device Health" app and select Move to Trash.

  4. Optionally, right-click the Trash icon and select Empty Trash.

Windows 10 users:

  1. Go to StartSettings.

  2. Click Apps & Features.

  3. From the list, select the "Duo Device Health" application and click Uninstall.

Support Details

Additional support details for operating systems, machine platforms, and client browsers.

macOS

The Duo Device Health application supports macOS 10.13 and newer. There are no special cases of macOS to consider. It is not necessary to reinstall the Duo Device Health application after a macOS update.

Windows

The Duo Device Health application supports only client versions of Windows 10, including Home, Pro, and Enterprise editions. The Duo Device Health application is not supported on other Windows client OS versions or any Windows Server versions.

To simplify the policy selection for all of our customers, while also supporting the most Windows 10 machines, the Windows 10 version policy in the Admin Panel supports a subset of the currently supported builds of Windows 10. As Microsoft support for Home and Pro editions of Windows 10 terminates earlier than the Enterprise edition, The Duo OS policy will support the most recent three Windows 10 builds to capture all Windows devices.

Virtual Machines

Virtual machines may experience their own set of problems, for example, difficulty with unique system identification. Because of these issues, the Duo Device Health application does not officially support Windows or macOS virtual machines.

Browser Support

We recommend Google Chrome for the most seamless user experience. Internet Explorer 11, Safari, and Opera are also known to work without issues.

Microsoft Edge

Microsoft Edge has a caveat where the user is not presented with an option to remember the choice of allowing the Duo Prompt to communicate with the Duo Device Health application. This can result in a frustrating experience if the user continually closes the Duo Device Health application, as the Duo Prompt will use our fallback method of system URI communication which opens up the dialog that asks if the user intended to switch apps.

Leaving the Duo Device Health application running, even in the background, will prevent most of these dialogs from appearing. There could be cases where embedded web views within other software have issues communicating with the application over HTTPS, which will cause this dialog to appear even while the application is running.

Firefox

Firefox has implemented a feature as of version 67 that limits the rate at which you can attempt to open URLs from links, impacting communication between the Device Health application and Duo's service. If the end user is required to remediate, Duo must to open up to three custom URI links, each of which may be delayed for 10 seconds after the previous link is opened. Additionally. limitations in the way that Firefox examines certificate stores on the local system prevents the Device Health secure web server from functioning as expected. These factors result in poor end users experience when using Firefox.

End users can work around these issues by navigating to the Firefox about:config page, searching for enterprise_roots, double-clicking the security.enterprise_roots.enabled settings row to toggle the value to true.

Firefox version 69 and later make changes that need an exception set in order to trust the Device Health v0.9.x application's self-signed certificate. This is fixed in Device Health v1.0.x.

This exception may be added using one of the following methods:

Add Exception from Browser Warning

  1. Make sure the Duo Device Health app is running. Look for the Duo status icon in the macOS menu bar at the top right of the desktop, or in the Windows 10 system tray at the bottom left of the desktop.

    If the Duo Device Health application isn't running, start it.

  2. Open Firefox and go to https://127.0.0.1:53100/ in a new tab. The page will show a warning which will look like this:

    Firefox Security Warning

  3. Click the Advanced button and scroll down to the warning details about the certificate. Click the Accept the Risk and Continue button to permanently add an exception for the Duo Device Health certificate.

    Firefox Security Warning - Advanced

  4. Close the 127.0.0.1 Firefox tab and navigate to the Duo Prompt. Make sure the Duo Device Health app is running. You should not receive any security warning from Firefox.

Add Exception from Settings

  1. Make sure the Duo Device Health app is running. Look for the Duo status icon in the macOS menu bar at the top right of the desktop, or in the Windows 10 system tray at the bottom left of the desktop.

    If the Duo Device Health application isn't running, start it.

  2. Open Firefox preferences and go to the Privacy & Security panel.

  3. Scroll down to the "Certificates" section. Click View Certificates, then click the Servers tab in the Firefox Certificate Manager, and then click the Add Exception button.

  4. Enter https://127.0.0.1:53100/ in the "Location" field, and then click Get Certificate.

  5. Verify that the Permanently store this exception option is checked, and then click the Confirm Security Exception button.

    Firefox Site Exception

  6. You should now see an entry for "Duo Security, Inc" for the server "127.0.0.1:53100" with a permanent lifetime in the Certificate Manager server list. Click OK then exit the Preferences panel.

  7. Navigate to the Duo Prompt. Make sure the Duo Device Health app is running. You should not receive any security warning from Firefox.