Onboarding Devices into Microsoft Defender for Endpoint via Workspace ONE UEM

The Client Call That Started This Post

A few weeks ago I got a message from a client that stopped me mid-coffee. They had been onboarding Windows devices into Microsoft Defender for Endpoint (MDE) by deploying the onboarding package through a Workspace ONE Script. It had been running, devices were appearing in the Defender portal, and nobody had questioned it — until it stopped working reliably on a subset of machines.

The question was simple: "Is this the right way to do it?"

The short answer is no. The slightly longer answer is the rest of this post.

Deploying the MDE onboarding package via a Script in Workspace ONE UEM is tempting because it feels lightweight and familiar. However, there is a fundamental problem: Workspace ONE Scripts run in a transient execution context and are not tracked as installed applications. If the script fails silently, or if a device re-enrolls, there is no reliable delivery guarantee and no installation state to detect against. For something as foundational as Defender onboarding, that is too fragile.

The correct delivery mechanism is Workspace ONE Software Distribution — and it is actually the only component in the entire Omnissa Workspace ONE UEM Windows Defender integration pack that must go through Software Distribution. Everything else — sensors, remediation scripts, scan triggers — runs just fine as a Script or Sensor. Licensing is the exception.

This post walks through exactly how to build and deploy that package, and how to validate the result using the defender_licensestatus sensor from the omnissa-chase/WorkspaceOneDefenderIntegration repository.

---

Why Software Distribution — Not Scripts

Workspace ONE Scripts are excellent for configuration tasks, health checks, and one-time remediations. What they are not designed for is tracked application delivery with installation detection.

Software Distribution in Workspace ONE UEM provides:

• Retry and re-delivery logic — if a device is offline at assignment time, it will receive the package when it checks back in.
• Installation detection — you define a registry key, file, or other condition that confirms the package ran successfully. UEM tracks this state and will not re-run the installer on already-compliant devices.
• Compliance integration — once a device is confirmed onboarded, that state can feed into Smart Groups, compliance policies, and access rules.
• Fully Managed scope — the MDE onboarding package writes to protected registry hives and requires SYSTEM-level execution with persistent tracking. Software Distribution handles this natively.

The Omnissa community article linked above makes this explicit: licensing is the only component in the Defender integration pack that must be delivered through the Software Distribution framework.

---

Prerequisites

Before you begin, confirm the following:

• Devices are Fully Managed in Workspace ONE UEM (not Registered/BYOD). The onboarding package requires deep system access and persistent state.
• You have a Microsoft 365 Defender or Microsoft Defender XDR subscription that covers Defender for Endpoint Plan 1 or Plan 2.
• You have access to the Microsoft Defender portal at security.microsoft.com with sufficient permissions to download onboarding packages.
• Workspace ONE UEM admin console access with rights to create and assign Applications.
• Target Windows devices are running Windows 10 1703 or later, or Windows 11.

---

Step 1: Download the Onboarding Package from Microsoft

1. Navigate to security.microsoft.com and sign in.
2. In the left navigation, go to Settings → Endpoints → Device Management → Onboarding.
3. Set the Operating System to Windows 10 and 11.
4. Set the Deployment Method to Mobile Device Management / Microsoft Intune.

Note: Even though the label says "Intune," this method produces a generic MDM onboarding package that works with any MDM solution, including Workspace ONE UEM. Do not select the "Local Script" option — that produces a standalone .cmd file that is not suitable for Software Distribution with detection logic.

5. Click Download onboarding package.
6. The download will be a .zip file (typically named something like WindowsDefenderATPOnboardingPackage.zip).
7. Extract the zip. Inside you will find a file named WindowsDefenderATP.onboarding (an XML-based configuration blob) along with a deployment script.

Keep this extracted folder. You will re-package it as a ZIP for Workspace ONE UEM.

---

Step 2: Prepare the Deployment Package

Workspace ONE UEM's Software Distribution for Windows supports several package types. For this use case, we will deploy it as a ZIP with a PowerShell install script — a clean, auditable approach.

Create the install script

Create a file named Install-DefenderOnboarding.ps1 with the following content:

$OnboardingFile = Join-Path $PSScriptRoot "WindowsDefenderATP.onboarding"

if (-not (Test-Path $OnboardingFile)) {
    Write-Host "Onboarding file not found: $OnboardingFile"
    exit 1
}

$OnboardingXml = [xml](Get-Content $OnboardingFile -Raw)
$OnboardingBlob = $OnboardingXml.SenseMdrConfiguration.OnboardingInfo

$RegPath = "HKLM:\SOFTWARE\Policies\Microsoft\Windows Advanced Threat Protection"
if (-not (Test-Path $RegPath)) {
    New-Item -Path $RegPath -Force | Out-Null
}

Set-ItemProperty -Path $RegPath -Name "OnboardingInfo" -Value $OnboardingBlob -Type String
Write-Host "Defender for Endpoint onboarding policy applied successfully."
exit 0

This script reads the .onboarding XML blob and writes it to the correct registry path where the Windows Defender service picks it up. The service will then complete the onboarding handshake with Microsoft's cloud.

Build the ZIP

Your ZIP should contain:

DefenderOnboarding.zip
├── WindowsDefenderATP.onboarding
└── Install-DefenderOnboarding.ps1

Do not nest inside a subfolder — the files should be at the root of the archive.

---

Step 3: Add the Application in Workspace ONE UEM

1. In the Workspace ONE UEM console, navigate to Resources → Apps → Native → Add → Internal.
2. Upload your DefenderOnboarding.zip file.
3. Set the following metadata:

Field	Value
Name	Microsoft Defender for Endpoint Onboarding
Version	Match your MDE portal package version or use today's date (e.g. 2026.05)
Supported OS	Windows 10 / Windows 11
Managed By	Your top-level Organization Group or the OG covering your managed Windows fleet

4. Under Files / Actions, configure the install command:

powershell.exe -ExecutionPolicy Bypass -File "Install-DefenderOnboarding.ps1"

5. Set the Install Context to Device.

This is critical. The onboarding registry keys live under HKLM and require SYSTEM context. Running in User context will silently fail.

---

Step 4: Configure the Detection Criteria

This is the step that separates a proper Software Distribution deployment from a script workaround. The detection rule tells Workspace ONE UEM whether onboarding actually completed on the device.

1. In the application's Detection Criteria tab, add a new rule:
   • Type: Registry
   • Hive: HKEY_LOCAL_MACHINE
   • Key Path: SOFTWARE\Microsoft\Windows Advanced Threat Protection\Status
   • Value Name: OnboardingState
   • Value Type: DWORD
   • Comparison: Equals
   • Value: 1

This key is written by the Defender service itself after it successfully completes the onboarding handshake with Microsoft's cloud backend. Setting OnboardingState = 1 as your detection condition means UEM will only mark the application as installed when the device is genuinely onboarded — not just when the script ran.

2. Save the application.

---

Step 5: Assign to Devices

1. Go to the application's Assignment tab.
2. Click Assign and select your target Smart Group (the group representing your Fully Managed Windows fleet, or a pilot group to start).
3. Set App Delivery Method to Auto.
4. Save and publish.

Workspace ONE UEM will begin pushing the package to devices in scope at their next check-in. Devices that are already onboarded (if any) will be skipped because the detection condition will already be satisfied.

---

Step 6: Validate With the Defender License Status Sensor

Once the package has had time to deploy, use the defender_licensestatus sensor from the omnissa-chase/WorkspaceOneDefenderIntegration repository to confirm the onboarding state at scale.

Add the sensor to Workspace ONE UEM

1. Copy the sensor script from the repository's Sensors/ directory.
2. In the UEM console, navigate to Resources → Sensors → Add.
3. Paste the script content, set the execution context to Device, and set the return type to match the sensor's output (typically String or Integer).
4. Name it defender_licensestatus to match the repository convention.
5. Assign it to your Windows device fleet.

What to expect

The sensor queries the same OnboardingState registry value you used for detection, along with additional Defender service state. Devices that return a value of 1 are fully onboarded. Any device returning 0 or an error indicates a failure that needs investigation.

You can surface this data in:

• Workspace ONE Intelligence — build a dashboard widget showing onboarding coverage across your fleet.
• Smart Group filters — create a group of non-onboarded devices and trigger a re-push of the onboarding package.
• Compliance policies — mark devices as non-compliant if they are not onboarded, feeding into access control decisions in Workspace ONE Access or a third-party IdP.

---

The Broader Integration Pack

The Defender license deployment is just one piece of the broader omnissa-chase/WorkspaceOneDefenderIntegration pack. Once your devices are onboarded, the repository gives you:

Component	Purpose
defender_computerstate_summary	Overall Defender health rollup
defender_cloudblock_bafs	Verifies Block at First Sight prerequisites
defender_signatureoutofdate	Flags devices with stale definitions
Remediation Scripts	Quick/Full scans, signature updates, service recovery, CloudBlock enablement
Scheduled Tasks	Scan monitoring and reporting

This entire pack is designed around idempotent, single-purpose sensors that return deterministic values — ideal for feeding into Workspace ONE Intelligence dashboards and automated remediation workflows.

The Omnissa community thread at community.omnissa.com goes into detail on each component and is the canonical reference for this integration. It is worth reading in full if you are building out a complete Defender management posture through Workspace ONE.

---

Summary

If your devices are being onboarded into Microsoft Defender for Endpoint through a Workspace ONE Script today, the workflow is fragile. It lacks delivery guarantees, installation state tracking, and re-delivery logic on failure.

The correct path is a three-part approach:

1. Software Distribution for the onboarding package — with registry-based detection to confirm real onboarding, not just script execution.
2. Sensors from the integration pack to validate and report state at scale.
3. Remediation Scripts to recover devices that fall out of compliance.

The onboarding package only needs to be delivered once per device. Getting it right the first time — with proper detection and delivery tracking — means you stop chasing Defender coverage gaps and start trusting your data.

---

Questions about deploying Defender for Endpoint through Workspace ONE UEM, or building out the broader integration? Get in touch with Workspace Consultants.