How to Create and Deploy Custom Compliance Policies in Microsoft Intune
Build custom Intune compliance policies using PowerShell discovery scripts and JSON validation rules to check conditions like registry keys, app versions, and services beyond built-in capabilities.
- Difficulty
- Advanced
- Time required
- 30-45 minutes
- Steps
- 7
- Platform
- Microsoft Intune
Table of contents
Quick Answer
Go to the stepsWrite a PowerShell script, create JSON rules, upload both to Intune, create a compliance policy, assign to groups.
- Write a PowerShell script outputting compressed JSON.
- Create a JSON rules file with SettingName, Operator, Operand.
- Upload script under Device compliance > Scripts.
- Create compliance policy selecting script and uploading JSON.
- Assign to groups and monitor.
Endpoint security > Device compliance > Scripts > AddExpected result: Devices evaluate custom conditions every 8 hours.
Key takeaways
- How to write a PowerShell discovery script, create JSON compliance rules, upload both to Intune, build a custom compliance policy, and monitor results.
- Built-in policies cannot validate custom conditions. Custom compliance lets you check anything PowerShell can detect.
- Test scripts locally. Use the correct JSON schema (Rules/Operand). Monitor for Error states.
Introduction
Intune built-in compliance covers standard settings but cannot check custom conditions like third-party agent versions, specific registry keys, or proprietary app installations.
Custom compliance policies solve this by pairing a PowerShell discovery script with a JSON rules file. Per Microsoft Learn, the script runs every 8 hours via the Intune Management Extension, and the output is compared against your rules. The result feeds into the same compliance state Conditional Access uses.
This tutorial covers writing the script, creating the JSON with the correct schema, uploading to Intune, building the policy, and monitoring results.
Who this is for: Intune administrators and MSPs needing compliance checks beyond built-in settings.
Before you start
- Access
- Intune Administrator role.
- Required roles
- Intune Administrator
- Required licenses
- Microsoft Intune Plan 1 or Microsoft 365 E3/E5
- Environment
- Windows 10/11 devices enrolled in Intune with the Intune Management Extension.
- Vendor
- Microsoft
- Administrator permissions required
Script development 15-20 minutes. Policy creation 15-25 minutes.
Warning: Test scripts locally before deploying
Intune does not validate script syntax. A script error causes Error compliance status on all targeted devices, which overrides other states and can trigger Conditional Access blocks.
Note: JSON schema uses Rules and Operand
The correct JSON structure uses a Rules array with SettingName, Operator, DataType, Operand, and RemediationStrings. Some community guides use incorrect field names.
1Write the PowerShell discovery script
Create a script that checks custom conditions.
Create a PowerShell script that checks your conditions and returns compressed JSON. Per Microsoft Learn, output must be single-line compressed JSON under 2,048 characters. Include try/catch error handling.
Expected result: Script outputs valid compressed JSON.
Note
Scripts can be up to 1 MB and must complete within 10 minutes on Windows.
2Create the JSON compliance rules file
Define compliant values and remediation messages.
Create a JSON file with a Rules array. Each rule needs SettingName (matching script output key), Operator, DataType, Operand (the compliant value), and RemediationStrings with Language, Title, Description.
Per Microsoft Learn, the correct fields are SettingName and Operand. Some community guides incorrectly use Name and CompliantValue.
Expected result: Valid JSON with Rules array.
Note
SettingName matching is case-sensitive. Include MoreInfoUrl to link users to remediation guides.
3Upload the discovery script to Intune
Add the script to Intune.
Endpoint security > Device compliance > Scripts > AddIn the Intune admin center, go to Endpoint security > Device compliance > Scripts > Add > Windows 10 and later. Enter a name, upload the script, set Run in 64-bit PowerShell Host to Yes.
Expected result: Script appears in the Scripts list.
Note
Each script can only be used with one compliance policy. The upload workflow does not support scope tags.
4Create the custom compliance policy
Build the compliance policy with script and JSON.
Devices > Compliance policies > Policies > Create policyCreate policy for Windows 10 and later. On Compliance settings, expand Custom Compliance, set to Require. Select your discovery script and upload the JSON rules file. Intune validates the JSON during upload.
Expected result: Policy created with custom compliance.
Note
Each policy supports one script. Combine all checks into a single script with multiple output keys.
5Configure actions for noncompliance
Define escalation for failed devices.
Configure the noncompliance timeline: Mark noncompliant immediately, email user after 1 day, push notification after 1 day. Custom compliance integrates with Conditional Access to block noncompliant devices from cloud resources.
Expected result: Noncompliance actions with grace periods configured.
Note
Device lock and retire actions are severe. Use long grace periods (14+ days) and ensure helpdesk procedures.
6Assign the policy to groups
Target the policy to groups.
Assign to a pilot group first, then expand. Add exclusions for kiosks or exempt devices. Use Entra ID dynamic groups for automatic assignment. Complete with Review + create.
Expected result: Policy assigned. Devices evaluate at next check-in.
Note
Evaluation occurs every 8 hours. Manual sync from Company Portal triggers compliance check.
7Monitor and troubleshoot
Verify evaluation and troubleshoot issues.
Monitor in Intune: Devices > Compliance policies > your policy > Device status. Check for Error states which indicate script failures. On devices, review IntuneManagementExtension.log and the SideCarPolicies registry keys for script results.
Per Microsoft Learn, output exceeding 2,048 characters causes error 65009. Keep output concise.
Expected result: Devices show Compliant or Not compliant (not Error).
Note
Delete registry keys at HKLM\SOFTWARE\Microsoft\IntuneManagementExtension\SideCarPolicies\Scripts and restart IME to force re-evaluation.
How to Confirm Custom Compliance Works
Verify fix
Check your policy Device status tab. Devices should show Compliant or Not compliant. Noncompliant devices display your remediation messages in Company Portal.
Conditional Access blocks take effect based on your noncompliance actions timeline.
Normal result: Devices report Compliant or Not compliant with remediation messages.
Abnormal result: Error status means script failed. Not applicable means IME is not installed.
Working
Compliant/Not compliant
Script executes and rules evaluate.
Script failure
Error status
Check script syntax and output.
IME missing
Not applicable
Install a Win32 app to trigger IME.
Troubleshooting
Error compliance status on all devices
Warning
Cause: Script failed, returned invalid JSON, or exceeded 2,048 char output limit.
Check script syntax locally. Verify compressed JSON output under 2,048 chars. Review IntuneManagementExtension.log.
JSON validation fails during policy creation
Warning
Cause: SettingName mismatch or incorrect JSON field names.
Verify case-sensitive matching between script keys and JSON SettingName. Use Rules array with Operand, not Settings with CompliantValue.
Not applicable status
Note
Cause: Intune Management Extension not installed.
IME installs automatically when a Win32 app, PowerShell script, or compliance policy targets the device. Deploy a simple Win32 app to trigger installation.
Compliance evaluation delayed
Note
Cause: Normal 8-hour evaluation interval.
Trigger manual sync from Company Portal. Or delete script cache from registry and restart the IME service.
Frequently asked questions
What platforms support custom compliance?
Windows 10/11 (PowerShell) and Linux (POSIX shell). iOS, Android, and macOS are not supported per Microsoft Learn.
How often do custom compliance scripts run?
Every 8 hours via the Intune Management Extension. Users can trigger manual sync from Company Portal but this does not check for new scripts.
What if the discovery script fails?
Intune marks the device with Error compliance status, which has the highest severity and overrides other states. Include try/catch error handling.
What is the correct JSON structure?
A Rules array with SettingName, Operator, DataType, Operand, and RemediationStrings. Not Settings/Name/CompliantValue as some guides show.
Can I use this with Conditional Access?
Yes. Custom compliance integrates with Conditional Access the same way built-in settings do.
Conclusion
Custom compliance policies run PowerShell scripts every 8 hours and compare output against JSON-defined rules. Get the schema right and keep output under 2,048 characters.
Test scripts locally. Use the correct JSON schema (Rules/Operand). Monitor for Error states.
Endpoint security > Device compliance > Scripts > AddSources3
