Skip navigation
Documentation

Duo Trusted Endpoints - Generic Certificate Deployment

Last Updated: November 2nd, 2023
macOS Certificate Users: Changes required to support macOS 12.3

The macOS 12.3 update removes Python, which was a required dependency for the certificate enrollment script prior to April 7, 2022. After updating a macOS client to 12.3, endpoint management tasks using the Duo Python script fail to perform new certificate issuance and existing certificate renewals.

To address this, download the replacement Duo certificate shell script from the Duo Admin Panel and use it to update the Duo certificate tasks in your endpoint management system.

Certificate-based Trusted Endpoint verification for Generic endpoint managed will reach end-of-life on October 7, 2024. Migrate existing Generic Certificate management integrations to Generic with Duo Desktop. Learn more about the end-of-life timeline and migration options in the Duo Trusted Endpoints Certificate Migration Guide.

Duo's Trusted Endpoints feature secures your sensitive applications by ensuring that only known devices can access Duo protected services. When a user authenticates via the Duo Prompt, we'll check for the presence of a Duo device certificate on that endpoint. You can monitor access to your applications from devices with and without the Duo certificate, and optionally block access from devices without the Duo certificate.

Trusted Endpoints is part of the Duo Essentials, Duo Advantage, and Duo Premier plans.

Before enabling the Trusted Endpoints policy on your applications, you'll need to deploy the Duo device certificate to your managed devices. We've documented this process for some popular endpoint management systems. If you're using a different tool to manage your endpoints, use our generic Windows and Mac management integrations to deploy the Duo device certificate package.

Once a client authenticates to Duo with this certificate, it becomes associated with that particular endpoint. Therefore, you'll need to repeat the process of downloading and installing a unique Duo certificate from the Duo Admin Panel for each individual system.

Duo's trusted endpoints certificate check works in Google Chrome, Edge Chromium, Apple Safari, and Internet Explorer browsers.

Prerequisites

  • Access to the Duo Admin Panel as an administrator with the Owner, Administrator, or Application Manager administrative roles.
  • Access to your endpoint management system console as an administrator with the rights to create new software distribution packages and scheduled tasks.

Mac OS X Enterprise Asset Management Tool

Create the Mac OS X Enterprise Asset Management Tool Integration

  1. Log in to the Duo Admin Panel and navigate to Trusted Endpoints.
  2. If this is your first management integration, click the Get started button at the bottom of the Trusted Endpoints introduction page. If you're adding another management integration, click the Add Integration button you see at the top of the page instead.
  3. On the "Add Management Tools Integration" page, locate Generic Integrations in the list of "Device Management Tools" and click the Add this integration selector.
  4. Choose Certs for macOS from the "Legacy" options, and then click the Add button.

The new Mac OS X Enterprise Asset Management Tool integration is created in the "Disabled" state. You'll turn it on when you're ready to apply your Duo trusted endpoints policy.

Keep the Admin Panel open in your browser to complete the rest of your Duo macOS certificate deployment.

Deploy the macOS Enrollment Script

  1. In the Duo Admin Panel browser window, view the "Mac OS X Enterprise Asset Management Tool" management tools integration. In the "Download the Deployment Files" section of the page (step 1), choose one of the certificate lifetime options:

    1 year certificates These certificates expire one year from issuance. This is the best option for most Duo deployments.
    7 days certificates These certificates expire one week (seven days) from issuance. Select this option when you have users who need certificates reissued more frequently than the one year default. For example, you have virtual desktop users whose VDI endpoints are redeployed periodically, or a group of contractors who aren't expected to use the same workstations for a year.
    Generic Mac OS X EAM Files in Duo Admin Panel

    Click Download Script. The actual name of the downloaded script will be similar to duo_cert_enrollment-3.6.sh.

  2. Copy the downloaded script to your Mac endpoint management system.

  3. Create a software package for your macOS endpoints to run the Duo certificate enrollment script with sudo privileges.

  4. Create a deployment job to run the Duo script package on your macOS endpoints. It should run on the endpoint in the context of the logged-in user, not the workstation, so that the certificate gets added to the user's keychain.

    This script enrolls the Mac OS client as a Duo trusted endpoint by obtaining a device certificate from Duo, and also configures Safari and Chrome (if present) to automatically select the Duo certificate during authentication.

    We recommend running the script on your managed workstations at each user's logon, and also on a regular daily or weekly schedule to ensure timely renewal of the client's Duo certificate.

  5. IMPORTANT! Make sure that your distribution job or scheduled task doesn't leave the Duo script behind on the Mac OS client in an easily-found location when done. If your end user has access to the script they could run it on other devices to obtain Duo certificates for those endpoints without your knowledge.

Verify the Certificate

To confirm that the Duo enrollment script deployed via your Mac endpoint management system worked, launch the Mac OS Keychain Access application and make sure the Duo Device Authentication certificate exists in the "duo-auth" keychain.

Duo macOS Certificate Verification

At this point the configured integration is disabled and applies to no users until you finish your deployment.

Windows Enterprise Asset Management Tool

Create the Windows Enterprise Asset Management Tool Integration

  1. Log in to the Duo Admin Panel and navigate to Trusted Endpoints.
  2. If this is your first management integration, click the Get started button at the bottom of the Trusted Endpoints introduction page. If you're adding another management integration, click the Add Integration button you see at the top of the page instead.
  3. On the "Add Management Tools Integration" page, locate Generic Integrations in the list of "Device Management Tools" and click the Add this integration selector.
  4. Choose Certs for Windows from the "Legacy" options, and then click the Add button.

The new Windows Enterprise Asset Management Tool integration is created in the "Disabled" state. You'll turn it on when you're ready to apply your Duo trusted endpoints policy.

Keep the Admin Panel open in your browser to complete the rest of your Duo Windows certificate deployment.

Deploy the Windows Enrollment Files

  1. In the Duo Admin Panel browser window, view the "Windows Enterprise Asset Management Tool" management tools integration. In the "Download the Deployment Files" section of the page (step 1.1), choose one of the certificate lifetime options:

    1 year certificates These certificates expire one year from issuance. This is the best option for most Duo deployments.
    7 days certificates These certificates expire one week (seven days) from issuance. Select this option when you have users who need certificates reissued more frequently than the one year default. For example, you have virtual desktop users whose VDI endpoints are redeployed periodically, or a group of contractors who aren't expected to use the same workstations for a year.
    Generic Windows EAM Files in Duo Admin Panel

    Click Download Batch File. The downloaded script name will be similar to duo_cert_enrollment.bat. Then, click the link in step 2.2 to download the enrollment executable file, whose name will be like duo_cert_enrollment-cmsv3-5.0.exe.

    If your users access Duo-protected sites with the Edge Chromium browser, also click the download link for the Edge configuration file duo_edge_configuration.bat.

  2. Copy the downloaded batch script(s) and executable file to your Windows endpoint management system.

  3. Create a software package for your Windows endpoints to run the Duo certificate enrollment batch script (which calls the Duo certificate enrollment executable). Your package should include both files.

    If you downloaded the Edge Chromium batch file in step 1, also add it as an additional file to the package.

  4. Create a deployment job to run the Duo certificate software package on your Windows endpoints. It should run on the endpoint in the context of the logged-in user, not the workstation, so that the certificate gets added to the user's Personal certificate store.

    This script enrolls the Windows client as a Duo trusted endpoint by obtaining a device certificate from Duo, and also configures Internet Explorer (and optionally Edge Chromium) to automatically select the Duo certificate during authentication.

    We recommend running the script on your managed workstations at each user's logon, and also on a regular daily or weekly schedule to ensure timely renewal of the client's Duo certificate.

  5. IMPORTANT! Make sure that your distribution job or scheduled task doesn't leave the Duo script and executable behind on the Windows client in an easily-found location when done. If your end user has access to the script and executable they could run it on other devices to obtain Duo certificates for those endpoints without your knowledge.

Verify the Certificate

To confirm that the Duo enrollment package deployed via your Windows endpoint management system worked, launch the User Certificate Manager ()certmgr.msc) and Expand Certificates - Current User\Personal\Certificates. Look for the Duo Device Authentication certificate in the list.

AD DS Certificate Verification

Chrome Browser Configuration

Duo's certificate package for Windows configures Internet Explorer to automatically select the Duo device certificate when requested by the Duo authentication prompt. Google Chrome requires additional steps to make the same change. Without this, users are prompted to select the Duo device certificate when they authenticate. You can distribute the Chrome browser configuration via AD Group Policy to PC clients joined to a domain. Standalone clients must be configured with Microsoft's LGPO utility.

Configure Chrome with EAM and LGPO

  1. Visit the "Local Group Policy Object Utility" page on Microsoft TechNet and download lgpo.zip using the link at the bottom of the page.

  2. Click the two download links in the "Download Files to Configure Google Chrome" section of the Windows Enterprise Asset Management Tool page (step 1). The downloaded file names will be similar to chrome_cert_lgpo_policy-1.0.pol and duo_chrome_configuration.bat.

  3. Extract the LGPO.exe executable from the zip file downloaded in step 1 and copy it and the .pol and .bat files downloaded from Duo in step 2 to your Windows endpoint management system.

  4. Create a software package for your Windows endpoints to run the Chrome configuration batch script (which calls LGPO.exe and the Chrome policy .pol file). Your package should include all three files.

  5. Create a deployment job to run the Duo certificate software package on your Windows endpoints. Unlike the Duo Certificate scheduled task, the Chrome configuration only needs to run once on a computer.

Configure Chrome with GPO

  1. On your domain controller or another system with the Windows Remote Server Administration Tools installed, launch the Group Policy Management console (GPMC).

  2. Expand your forest and navigate down the tree to Group Policy Objects. Right-click the Group Policy Objects folder and click New. Enter a name for the new GPO (such as "Duo Chrome Certificate Policy") and click OK.

  3. Right-click the new GPO created in step 2 and click Edit.

  4. Navigate to User Configuration\Preferences\Windows Settings\Registry.

  5. Download the Chrome Configuration.xml file, which contains the GPO registry settings necessary to configure Chrome to select the Duo certificate automatically. Save this file in a location accessible from the GPMC console. The downloaded file name will be similar to chrome_cert_gpo_config-1.xml.

  6. Return to the Group Policy editor window and copy/paste the downloaded Chrome XML file (from an Explorer window — not the file contents) into the "Registry" pane on the right of the GPO editor window. Confirm import of the pasted document by clicking Yes.

    This adds registry settings under the HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\AutoSelectCertificateForUrls key to the GPO.

    AD DS Chrome Registry Settings in GPO

    This registry value lets Chrome automatically select the Duo device certificate when requested by the Duo browser prompt without prompting the user interactively to select the certificate.

  7. When you've finished configuring all settings, close the Group Policy editor window.

  8. Apply the newly created Duo Chrome certificate GPO by linking it to OUs containing the domain client computers used to access Duo resources.

Finish Trusted Endpoints Deployment

Once you've deployed the Duo certificate on your endpoints you can configure the Trusted Endpoints policy to start checking for the certificate as users authenticate to Duo-protected services and applications.

When your trusted endpoints policy is applied to your Duo applications, return to the Mac OS X Enterprise Asset Management Tool or Windows Enterprise Asset Management Tool trusted endpoint management integration in the Admin Panel. The "Change Integration Status" section of the page shows the current integration status (disabled by default after creation). You can choose to either activate this management integration only for members of a specified test group, or activate for all users.

Enable Trusted Endpoints Management Integration

The Device Insight and Endpoints pages in the Duo Admin Panel show which access devices have the Duo certificate present.

Next Steps

As more of your devices receive the Duo certificate you can change the integration activation to apply to all users (if you just targeted test groups before), adjust your trusted endpoints policy to expand the target group, apply it to additional protected services, or start blocking access to applications from devices that do not have the Duo certificate. See the Trusted Endpoints documentation for more information.

Troubleshooting

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