Onboard non-persistent VDI devices to Microsoft Defender for Endpoint

You can use the virtual desktop infrastructure (VDI) onboarding package to onboard non-persistent Windows virtual desktops to Microsoft Defender for Endpoint as the desktops are provisioned. Before you begin, review the prerequisites and choose a device-entry model. Then, add the onboarding scripts to a primary image, verify onboarding, and prepare an onboarded image for reuse.

Prerequisites

• Review the minimum requirements for Microsoft Defender for Endpoint and configure device connectivity.
• To download the onboarding package, you need full access to Defender for Endpoint. The Microsoft Entra Security Administrator role grants this access. For more information, see Assign basic permissions.
• Use an account with local administrator permissions to configure and maintain the primary VDI image.
• For Windows Server 2012 R2 and Windows Server 2016, install the current unified Defender for Endpoint solution before you add the VDI onboarding scripts. For prerequisites and installation guidance, see Onboard Windows Server 2012 R2 and Windows Server 2016.

Plan non-persistent VDI onboarding

Non-persistent desktops are short-lived, and their device names are often reused. Choose one of the following device-entry models before you configure the image:

• Single entry for each device: Recreated desktops that use the same final device name use one device entry in the Defender portal. This model uses Onboard-NonPersistentMachine.ps1 and WindowsDefenderATPOnboardingScript.cmd.
• Multiple entries for each device: Each provisioned VDI instance creates a separate device entry. This model uses WindowsDefenderATPOnboardingScript.cmd.

The first time a VDI device onboards, client reporting can be delayed by approximately three to four hours.

Onboard non-persistent VDI devices

Download the VDI onboarding package, add the applicable scripts to the primary image, and configure the scripts to run when each provisioned device starts.

1. On the Onboarding page in the Microsoft Defender portal at https://security.microsoft.com/securitysettings/endpoints/onboarding, configure the package. If the direct link doesn't open, sign in to the Microsoft Defender portal, and then open the Onboarding page.

   1. Step 1: Select an operating system to start deployment: Select the operating-system version group for the VDI devices. Don't select Windows, which starts the separate Defender deployment tool workflow.
   2. If Connectivity type is available, select Standard or Streamlined for your environment. For streamlined-connectivity requirements, see Onboard devices using streamlined connectivity.
   3. For Deployment method, select VDI onboarding scripts for non-persistent endpoints.
   4. Select Download onboarding package to download WindowsDefenderATPOnboardingPackage.zip.

2. Extract the package. Copy the applicable files from the extracted WindowsDefenderATPOnboardingPackage folder to C:\Windows\System32\GroupPolicy\Machine\Scripts\Startup in the primary image:

   • For a single entry for each device, copy Onboard-NonPersistentMachine.ps1 and WindowsDefenderATPOnboardingScript.cmd.
   • For multiple entries for each device, copy WindowsDefenderATPOnboardingScript.cmd.

   Note

   If the C:\Windows\System32\GroupPolicy\Machine\Scripts\Startup folder is hidden, turn on Hidden items in File Explorer.

3. Open the Local Group Policy Editor, and go to Computer Configuration > Windows Settings > Scripts (Startup/Shutdown) > Startup.

   Note

   You can also use domain Group Policy to run the onboarding scripts.

4. Configure the startup script for the device-entry model:

   • Single entry for each device: On the PowerShell Scripts tab, select Add, and select Onboard-NonPersistentMachine.ps1. The PowerShell script runs WindowsDefenderATPOnboardingScript.cmd; don't add the .cmd file separately.
   • Multiple entries for each device: On the Scripts tab, select Add, and select WindowsDefenderATPOnboardingScript.cmd.

   Note

   For the single-entry model, run Onboard-NonPersistentMachine.ps1 only after the VM has its final device name and completes its final provisioning restart. Running the script earlier can create duplicate device entries or inconsistent onboarding. The script isn't signed. If your organization restricts PowerShell script execution, use an organization-approved method to run the script.

5. Provision a test pool that contains one device. Sign in to the device, sign out, and then sign in with another account.

6. On the Device inventory page in the Microsoft Defender portal at https://security.microsoft.com/machines?category=all-devices, search for the device name.

   • For the single-entry model, verify that only one device entry appears.
   • For the multiple-entry model, verify that the expected separate device entries appear for the provisioned VDI instances.

Configure legacy MMA-based VDI devices

For an existing legacy MMA-based VDI deployment that uses the single-entry model, configure the VDI device tag:

1. Create the registry value by importing the following registry data:

   [HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows Advanced Threat Protection\DeviceTagging]
    "VDI"="NonPersistent"
   

   Alternatively, create the same registry value from Command Prompt:

   reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows Advanced Threat Protection\DeviceTagging" /v VDI /t REG_SZ /d "NonPersistent" /f
   

2. For Windows Server 2012 R2 and later, follow the server onboarding process.

Update VDI images

Apply operating-system, app, Defender platform, engine, and security intelligence updates to VDI images through your normal image-maintenance process. If the primary image was onboarded and the SENSE service is running, offboard the image and clear its local Defender for Endpoint registration data before you use the image to provision devices.

To remove Defender for Endpoint registration data from an onboarded image:

1. Offboard the machine, and confirm that the offboarding process finishes.

2. Make sure PsExec.exe is available in the command prompt path. PsExec starts a command shell under the SYSTEM account so that you can remove the registration data.

3. Open Command Prompt as an administrator.

4. Check the SENSE service state to confirm that the sensor isn't running:

   sc query sense
   

5. Start a SYSTEM-level command shell and remove the local Defender for Endpoint registration data:

   PsExec.exe -s cmd.exe
   
   del "C:\ProgramData\Microsoft\Windows Defender Advanced Threat Protection\Cyber\*.*" /f /s /q
   
   REG DELETE "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection" /v senseGuid /f
   
   REG DELETE "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection" /v senseId /f
   
   REG DELETE "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection" /v 2567E824-34AB-4A74-90E9-BC0F8BDFAA4A /f
   
   REG DELETE "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection" /v 7DC0B629-D7F6-4DB3-9BF7-64D5AAF50F1A /f
   
   REG DELETE "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection" /v C9D38BBB-E9DD-4B27-8E6F-7DE97E68DAB9 /f
   
   REG DELETE "HKLM\SOFTWARE\Microsoft\Windows Advanced Threat Protection\48A68F11-7A16-4180-B32C-7F974C7BD783" /f
   
   exit
   

Prepare images for third-party VDI platforms

For VMware instant cloning and similar technologies, make sure that the primary image, internal template VMs, and replica VMs aren't onboarded to Defender for Endpoint. With the single-entry model, clones provisioned from an onboarded VM can inherit the same senseGuid. The duplicate identifier can prevent new non-persistent VDI devices from appearing in the Microsoft Defender portal.

For platform-specific image preparation, contact the VDI platform vendor.

Other recommended configuration settings

Onboarding connects VDI devices to Defender for Endpoint, but it doesn't configure Microsoft Defender Antivirus protection and performance settings.

Configure Microsoft Defender Antivirus

For recommended protection, update, scan, and performance settings, see Configure Microsoft Defender Antivirus on a remote desktop or virtual desktop infrastructure environment.

Related content

• Onboard Windows devices using Group Policy
• Onboard Windows devices using Microsoft Configuration Manager
• Onboard Windows devices using Mobile Device Management tools
• Onboard Windows devices using a local script
• Troubleshoot Microsoft Defender for Endpoint onboarding issues