Use custom compliance policies and settings for Linux and Windows devices with Microsoft Intune

To expand on Intune’s built-in device compliance options, you can use policies for custom compliance settings for managed Linux and Windows devices. Custom settings provide flexibility to base compliance on the settings that are available on a device without having to wait for Intune to add these settings to the built-in policy templates.

This feature applies to:

• Windows 10/11 (excluding Windows 10/11 Home)
• Linux
  • Ubuntu Desktop, version 20.04 LTS and 22.04 LTS
  • RedHat Enterprise Linux 8
  • RedHat Enterprise Linux 9

Before you can add custom settings to a policy, you must prepare a JSON file, and a discovery script for use with each supported platform. Both the script and JSON become part of the compliance policy. Each compliance policy supports a single script, and each script can discover multiple settings:

• The JSON file defines the custom settings and the values that you considered to be compliant. You can also configure messages for users to tell them how to restore compliance for each setting. You add your JSON file when you create a compliance policy, just after you select a discovery script for that policy.

• Discovery scripts are specific to the different platforms and are delivered to devices as part of the compliance policy. When a device evaluates its policy, the script detects (discovers) the settings from the JSON file, and then reports the results to Intune. Windows devices use a PowerShell script and Linux devices use a POSIX-compliant shell script.

  The scripts must be uploaded to the Microsoft Intune admin center before you create a compliance policy. You select the script when you’re configuring a policy to support custom settings.

After you deploy custom compliance settings and devices report back, you can view the results alongside the built-in compliance setting details in the Microsoft Intune admin center. Custom compliance settings can be used for conditional access decisions in the same way built-in compliance settings are. Together they form a compound rule set, equally affecting the device compliance state.

Prerequisites

• Microsoft Entra joined devices, including Microsoft Entra hybrid joined devices.

  Microsoft Entra hybrid joined devices are devices that are joined to Microsoft Entra ID and also joined to on-premises Active Directory. For more information, see Plan your Microsoft Entra hybrid join implementation.

• Microsoft Entra registered/Workplace joined (WPJ)

  For information about devices registered in Microsoft Entra ID, see Workplace Join as a seamless second factor authentication. Typically these devices are Bring Your Own Device (BYOD) devices that have a work or school account added via Settings>Accounts>Access work or school.

  On WPJ devices, device context PowerShell scripts work, but user context PowerShell scripts are ignored.

• Discovery script - A PowerShell for Windows or a POSIX-compliant shell script for Linux that you create. The script runs on a device to discover the custom settings defined in your JSON file. The script returns the configuration value of those settings to Intune. You need to upload your script to the Microsoft Intune admin center before you create a compliance policy and then select the script you want to use when creating a policy.

  To create a custom compliance script, see Custom compliance discovery scripts for Microsoft Intune.

• JSON file - The JSON file defines the custom settings and the value that is to be considered as compliant and can contain messages for users on how to restore the device to compliance for the setting. For guidance on creating a JSON for custom compliance, see Custom compliance JSON files.

Create a policy with custom compliance settings

Before you begin to create a policy that includes custom settings, review the prerequisites.

You must first upload an applicable discovery script to Intune, and have a ready JSON to add while creating the policy.

When ready, use the normal procedure to create a compliance policy, which includes platform specific instructions for adding custom settings to the policy. Custom settings are added while on the Configuration settings page by configuring the option for Custom Compliance.

Note

When a Windows device receives a compliance policy with custom settings, it checks for the presence of Intune Management Extensions. If not found, the device runs an MSI that installs the extensions, enabling the client to download and run PowerShell scripts that are part of a compliance policy, and to upload compliance results. Actions managed by the services include:

• Checking for new or updated PowerShell scripts every eight hours.
• Running the discovery scripts every eight hours.
• Running scripts that download when a user selects Check Compliance on the device. However, there is no check for new or updated scripts when Check Compliance is run.

It is not possible to push notifications to a device to enable custom compliance to run on demand.

Monitor custom compliance policy

Use the following methods to view details about a device’s compliance status.

• For both Linux and Windows devices, you can view per-setting device compliance details for custom compliance settings in the Microsoft Intune admin center.

  In the admin center go to Reports > Device compliance, and then select the Reports tab. Select the tile for Noncompliant devices and settings, and then use the drop-down menus to configure the report. Be sure to select a platform for the OS, and then select Generate report.

  For more information, see Monitor Intune Device compliance policies.

• On a Linux device, you can open the Intune app to view the device’s status:

  • Compliant – Your device is compliant with your organization’s policies and should be able to access organizational resources.
  • Checking status – Intune is currently evaluating the devices compliance to your organization’s policies.
  • Not compliant – The device doesn’t meet your organization’s device and security requirements and might not have access to your organization’s resources.

  When the device status is Not compliant, select View issues to see details about issues that must be addressed to bring that device into compliance. For information on resolving common issues, see Additional troubleshooting for Linux devices in this article.

Troubleshoot custom compliance for devices

Custom settings aren’t evaluated

Check the device compliance reports for the following error codes and insight into the problem:

• 65007: Script returned failure
• 65008: Setting missing in the script result
• 65009: Invalid json for the discovered setting
• 65010: Invalid datatype for the discovered setting

On Windows you can add the following line at the end of the PowerShell script to return errors related to the PowerShell script, ensure the following line is at the end of the PowerShell script file: return $hash | ConvertTo-Json -Compress

PowerShell or POSIX-compliant shell scripts aren’t visible to select, or remain visible after being deleted

Refresh the current view. If the issue persists, cancel the policy creation flow, and start again.

After an issue on a device is fixed, subsequent syncs don’t identify the issue as resolved and compliant

It can take up to eight hours before a noncompliant status shows as compliant after a change to the device.

Can a user manually check for compliance after fixing an issue on a device in order to identify if the issue is resolved and compliant?

• On Windows, a user can go to the Company Portal website and trigger a sync to update the device status after fixing a noncompliant custom compliance setting.

• On Linux, a user can open the Microsoft Intune app and select Refresh on either the device details page or the compliance issues page to start a new check-in with Intune.

Why aren’t more operators and operands supported?

Contact your account manager to request the addition of specific operators and operands. They can then be considered for a future update.

Why can’t I apply multiple discovery scripts to one custom compliance policy?

Policies support the use of a single script. However, each script supports checking for multiple compliance values.

Additional troubleshooting for Linux devices

To identify settings that aren't compliant for a device:

• In the Microsoft Intune admin center, you can identify devices that aren't compliant with policy. Go to Reports > Device compliance, select the Reports tab, and then select the tile for Noncompliant devices and settings. Use the drop-downs to configure the report you want, and then select Generate report.

The admin center displays a separate line for each setting that isn’t compliant on a device.

• On the Linux device, open the Microsoft Intune app and view the Update device settings page.

The following sections discuss common issues and resolutions for issues that users of Linux devices might encounter.

Operating system distro and version

Users of a device that doesn't meet the compliance requirements for the Linux distribution or operating system version, might receive a message that indicates a need to upgrade or downgrade that devices operating system.

To be compliant with the Allowed Distros setting, devices Linux distribution and version must meet minimum, maximum, and type requirements. If necessary, install a different version or distribution of Linux to bring the device into compliance.

Password complexity

Users of a device that doesn't meet the compliance requirements for password complexity requirements might receive a message that indicates they must use a strong password.

To be compliant with Password Policy settings, configure the Linux system to use passwords that meet those requirements. Common organization requirements include:

• Passwords that include a minimum number of letters, digits, or special characters
• Passwords of a minimum length

Device encryption

Users of a device that doesn't meet the compliance requirements for disk and partition encryption might receive a message that they must encrypt the device drives.

To be compliant with the Require Device Encryption setting, device-level encryption is required for writable fixed disks on the Linux device.

There are several options for disk and partition encryption on Linux operating systems. Intune recognizes any encryption system that uses the underlying dm-crypt subsystem. This subsystem is a long-time standard on Linux systems. The preferred method of setting up dm-crypt is to use the LUKS format with the cryptsetup tool.

The following list provides general guidance when encrypting disk and partitions:

• Encrypting Linux system volumes after installation is possible, but potentially time consuming. We recommend setting up disk encryption while installing the operating system.
• Not all filesystem partitions need to be encrypted for a device to meet organizational standards. The following aren't evaluated by the built-in device encryption settings:
  • Read-only partitions
  • Pseudo-filesystems, like /proc or tmpfs
  • The /boot or /boot/efi partitions

Refresh your compliance status on Linux devices

After making changes to a device to bring it into compliance, refresh the device status with Intune:

• If the Microsoft Intune app is still running, select Refresh on the device details page, or on the compliance issues page to start a new check-in with Intune.
• If the Microsoft Intune app isn't running, sign into the app to start a new check-in.
• After installation, the Microsoft Intune app periodically checks in with Intune on its own, so long as the device is on, and a user is signed in to it.

Next steps

• Create a compliance policy