How to Onboard Devices to Microsoft Defender for Endpoint

Microsoft Defender for Endpoint provides enterprise-grade endpoint detection and response (EDR) capabilities across Windows, macOS, Linux, iOS, and Android devices. This guide walks you through onboarding devices to Defender for Endpoint using various methods appropriate for different deployment scenarios.

Prerequisites

Before onboarding devices, ensure you have:

• Microsoft 365 Defender portal access with Security Administrator or Global Administrator role
• Appropriate licenses (Microsoft 365 E5, E5 Security, Defender for Endpoint P1/P2, or standalone)
• Supported operating systems (Windows 10/11, Windows Server 2012 R2+, macOS 11+, supported Linux distributions)
• Network connectivity to Microsoft Defender cloud services
• Local administrator access on devices to be onboarded

Understanding Onboarding Methods

Choose the appropriate onboarding method based on your environment:

Step 1: Access the Onboarding Packages

1. Sign in to the Microsoft Defender portal
2. Navigate to Settings > Endpoints > Device management > Onboarding
3. Select your operating system from the dropdown
4. Choose your deployment method
5. Click Download package to get the onboarding package

Important: Onboarding packages are tenant-specific and contain your unique workspace ID. Never share these packages publicly.

Step 2: Onboard Windows Devices

Method A: Local Script (Testing/Small Deployments)

1. Download the Local Script package from the Defender portal
2. Extract the ZIP file to get WindowsDefenderATPLocalOnboardingScript.cmd
3. On the target device, open Command Prompt as Administrator
4. Navigate to the script location and run:

WindowsDefenderATPLocalOnboardingScript.cmd

5. Press Y when prompted to confirm
6. Wait for the script to complete (typically 1-2 minutes)

Method B: Group Policy (Domain Environments)

1. Download the Group Policy package from the Defender portal

2. Extract the ZIP file containing:

   • WindowsDefenderATPOnboardingScript.cmd
   • WindowsDefenderATPOnboardingPackage.zip

3. Copy files to a network share accessible by target devices:

\\domain.local\SYSVOL\domain.local\scripts\DefenderATP\

4. Open Group Policy Management Console

5. Create a new GPO or edit an existing one linked to target OUs

6. Navigate to Computer Configuration > Policies > Windows Settings > Scripts > Startup

7. Click Add and browse to the onboarding script

8. Configure the script parameters:

   • Script Name: WindowsDefenderATPOnboardingScript.cmd
   • Script Parameters: (leave blank)

9. Link the GPO to appropriate OUs

10. Run gpupdate /force on target devices or wait for policy refresh

Method C: Microsoft Intune (Cloud-Managed)

1. In the Microsoft Intune admin center, go to Endpoint security > Endpoint detection and response
2. Click Create Policy
3. Select:
   • Platform: Windows 10 and later
   • Profile: Endpoint detection and response
4. Configure settings:
   • Microsoft Defender for Endpoint client configuration package type: Auto from connector
   • Sample sharing: All (or as per policy)
   • Telemetry reporting frequency: Normal
5. Assign to device groups
6. Click Create

Method D: Microsoft Endpoint Configuration Manager

1. In the SCCM console, go to Assets and Compliance > Endpoint Protection > Microsoft Defender ATP Policies
2. Right-click and select Create Microsoft Defender ATP Policy
3. Configure:
   • Name: Defender ATP Onboarding
   • Client configuration file: Browse to downloaded onboarding package
4. Deploy the policy to target device collections

Step 3: Onboard macOS Devices

Method A: Local Script

1. Download the macOS onboarding package from the Defender portal
2. Transfer WindowsDefenderATPOnboardingPackage.zip to the Mac
3. Extract and locate the .pkg file
4. Open Terminal and run:

sudo installer -pkg /path/to/wdav.pkg -target /

5. After installation, onboard using the script:

sudo /usr/local/bin/mdatp onboard

Method B: Microsoft Intune

1. In Intune admin center, go to Devices > macOS > Configuration profiles
2. Create a profile using Settings catalog
3. Add Microsoft Defender for Endpoint settings:
   • Enable real-time protection
   • Enable cloud-delivered protection
   • Configure onboarding blob (from portal)
4. Assign to macOS device groups

Method C: JAMF Pro

1. Download the macOS onboarding package
2. In JAMF Pro, create a new Configuration Profile
3. Add the Microsoft Defender payload
4. Upload the onboarding configuration
5. Scope to target devices

Step 4: Onboard Linux Devices

Supported Distributions

• RHEL 7.2+, CentOS 7.2+
• Ubuntu 16.04 LTS+
• Debian 9+
• SLES 12+
• Oracle Linux 7.2+
• Amazon Linux 2
• Fedora 33+

Installation Steps

1. Add the Microsoft repository:

For RHEL/CentOS:

sudo yum-config-manager --add-repo=https://packages.microsoft.com/config/rhel/8/prod.repo

For Ubuntu/Debian:

curl -o microsoft.list https://packages.microsoft.com/config/ubuntu/22.04/prod.list
sudo mv microsoft.list /etc/apt/sources.list.d/microsoft-prod.list
sudo apt-get update

2. Install the Defender package:

RHEL/CentOS:

sudo yum install mdatp

Ubuntu/Debian:

sudo apt-get install mdatp

3. Download the Linux onboarding package from the Defender portal
4. Extract and run the onboarding script:

unzip WindowsDefenderATPOnboardingPackage.zip
sudo python MicrosoftDefenderATPOnboardingLinuxServer.py

5. Verify onboarding status:

mdatp health --field org_id

Step 5: Onboard Mobile Devices

iOS Devices (via Intune)

1. Ensure Microsoft Defender app is deployed via Intune
2. Create an App configuration policy for iOS
3. Configure:
   • VPN profile for web protection
   • Supervised mode settings (if applicable)
4. Assign to user groups

Android Devices (via Intune)

1. Deploy Microsoft Defender app from Managed Google Play
2. Create an App configuration policy for Android
3. Configure permissions and settings
4. Assign to user groups

Step 6: Verify Onboarding Status

Check in Microsoft Defender Portal

1. Go to Assets > Devices
2. Search for the onboarded device by name
3. Verify:
   • Onboarding status: Onboarded
   • Health state: Active
   • Sensor health: No issues

Run Detection Test

Validate Defender is working by running a detection test:

Windows:

# Run from elevated PowerShell
powershell.exe -NoExit -ExecutionPolicy Bypass -WindowStyle Hidden $ErrorActionPreference='silentlycontinue';(New-Object System.Net.WebClient).DownloadFile('http://127.0.0.1/1.exe', 'C:\\test-MDATP-test\\invoice.exe');Start-Process 'C:\\test-MDATP-test\\invoice.exe'

macOS/Linux:

curl -o /tmp/safe_eicar.txt https://www.eicar.org/download/eicar.com.txt

After running the test, an alert should appear in the Defender portal within 10-30 minutes.

Check Local Health (Windows)

# Check Defender service status
Get-Service -Name Sense

# Check onboarding status via registry
Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows Advanced Threat Protection\Status"

# Run connectivity test
& "C:\Program Files\Windows Defender Advanced Threat Protection\MsSense.exe" -test

Check Local Health (macOS/Linux)

# Check health status
mdatp health

# Check specific fields
mdatp health --field healthy
mdatp health --field org_id
mdatp health --field real_time_protection_enabled

Troubleshooting Common Issues

Device Not Appearing in Portal

Symptoms: Device shows successful onboarding locally but doesn't appear in Defender portal.

Solutions:

1. Verify network connectivity to *.securitycenter.windows.com
2. Check proxy/firewall allows required URLs
3. Ensure system clock is accurate
4. Run the connectivity test tool:

   MDATPClientAnalyzer.cmd
   

   Copy
5. Review C:\ProgramData\Microsoft\Windows Defender Advanced Threat Protection\Cyber\ logs

Onboarding Script Fails

Symptoms: Script returns error or doesn't complete.

Solutions:

1. Run as Administrator
2. Temporarily disable other security software
3. Verify package is for correct OS version
4. Check Windows Event logs for errors
5. Ensure .NET Framework 4.5+ is installed

Sensor Health Issues

Symptoms: Device shows "Inactive" or health warnings in portal.

Solutions:

1. Restart the Sense service:

   net stop sense
   net start sense
   

   Copy
2. Verify network connectivity
3. Check for conflicting security software
4. Update to latest OS version
5. Re-run onboarding script

Best Practices

1. Test first: Onboard a few devices manually before large-scale deployment
2. Use automation: Leverage Intune or GPO for consistent, scalable onboarding
3. Monitor health: Regularly check device health status in the portal
4. Document process: Create runbooks for onboarding new devices
5. Plan offboarding: Know how to offboard devices when decommissioned
6. Network preparation: Pre-configure firewall rules for Defender URLs

Network Requirements

Ensure the following URLs are accessible:

For complete URL list, refer to Microsoft documentation.

Next Steps

After successful onboarding:

• Configure alert notifications for security events
• Run remote antivirus scans on devices
• Configure Attack Surface Reduction rules for enhanced protection
• Review Security recommendations in the portal for device hardening

Need help with your Defender for Endpoint deployment? Inventive HQ provides comprehensive endpoint security services, from initial deployment to ongoing management and incident response. Contact us for a free consultation.