Working with custom compliance settings

This week is all about the latest capabilities that are available within compliance policies. Those capabilities are custom compliance settings. Custom compliance settings enable the IT administrator to basically check for anything and to use that for the compliance state of the device. The IT administrator can use PowerShell script in the custom compliance setting, to verify the status of anything that is available on the device. The results can be compared to rules and values that are configured in a JSON file. The result of that comparision can be used as part of the compliance policy. This post will proivde a quick introduction to custom compliance settings, followed with the steps to create the require PowerShell script and JSON file. This post will end with the verification of the device compliance policy with the custom compliance setting.

Important: At the moment of writing custom settings for compliance is still in preview. Once it becomes generally available, it will be additional cost to the licensing options that include Microsoft Endpoint Manager or Intune.

Introducing custom compliance settings

Let’s start with an introduction to custom compliance settings. Those settings relies on a JSON file and a PowerShell script that must be uploaded to Microsoft Intune. That PowerShell script is used to detect a specific configuration and that JSON file is used to define the actual rule. Once configured as part of a device compliance policy, the results will also be reported alongside the standard available compliance settings. With that those settings can also be used for Conditional Access decisions. Just like any other compliance setting.

The biggest difference, however, is how Windows devices handle custom compliance settings. For running the detection, the Intune Management Extension (IME) is used. That will make sure that the PowerShell script is downloaded and that the script will run. The idea is similar as how IME handles other PowerShell scripts. Besides that, there is also some specific behavior related to the discovery scripts of custom compliance settings:

  • It will check for new or updated discovery scripts every eight hours
  • It will run the discovery scripts every eight hours
  • It will run detection scripts that download when manually checking the device
  • It doesn’t support custom compliance settings to run on demand

Important: Please note how often the discovery scripts are downloaded and run. Make sure that the interval would fit with the requirements for the custom compliance settings.

Creating PowerShell script for custom settings

The first action is to create a PowerShell script that will be used to discover the required settings (and values) on the device. The most important part of the script is that it should return a list of discovered values in a compressed single line JSON-format. A quick example that detects the current BIOS version is shown below.

$biosInfo = Get-WmiObject -Class Win32_BIOS
$biosHash = @{"BIOS version" = $biosInfo.SMBIOSBIOSVersion}
return $biosHash | ConvertTo-Json -Compress

Once the PowerShell script is constructed it must be uploaded to Microsoft Intune. That upload should be performed before creating the device compliance policy that verifies the custom compliance setting. The following five steps walk through the process of uploading the PowerShell script.

  1. Open the Microsoft Endpoint Manager admin center portal and navigate to Endpoint security > Device compliance > Scripts
  2. On the Compliance policies | Scripts page,  click Add > Windows 10 and later
  3. On the Basics page, specify a Name and optionaly a Description and Publisher and click Next
  4. On the Settings page (as shown in Figure 1), specify the following information and click Next
  • Detection script: Copy the just constructed PowerShell script
  • Run this script using the logged on credentials: Select No to run the PowerShell script in SYSTEM context
  • Enforce script signature check: Select No to not perform a signature check on the PowerShell script
  • Run script in 64 bit PowerShell Host: Select Yes to run the PowerShell script in 64-bit
  1. On the Review + create page, verify the configuration of the PowerShell script and click Create

Note: Once the PowerShell script is uploaded, it can be editted via Microsoft Endpoint Manager admin center portal.

Creating JSON for custom settings

The second action is construct a JSON file that will be used to define the settings that the device compliance policy should verify and the acceptable values for those settings. It even contains the options to configure a message that will tell the user what to do when the device is not compliant with the custom compliance setting. The JSON file should contain the following information:

  • SettingName – The name of the custom compliance setting, as returned by the PowerShell script
  • Operator – The operator (IsEquals, NotEquals, GreaterThan, GreaterEquals, LessThan, LessEquals) that specifies the action that is used for the compliance rule
  • DataType – The type of data (Boolean, Int64, Double, String, DateTime, Version) that specify the data, as returned by the PowerShell script
  • Operand – The operand represent the values that the operator works on
  • MoreInfoURL – The URL that provides more information about the custom compliance setting
  • RemediationStrings – The information that provides information about the the noncompliance

Once the information is available the JSON file can be constructed by using the different described properties (key-value pairs). A quick example that verifies the returned BIOS version with the expected version is shown below.

       "SettingName":"BIOS version",
       "Operand":"Hyper-V UEFI Release v4.0",
             "Title":"BIOS version must be upgraded to the latest version.",
             "Description": "Please make sure that the BIOS version is up-to-date."

Creating a device compliance policy with custom setting

The third action is to create a device compliance policy. That policy can be used to verify if a device is compliant with the company policy. That compliance state can be used for reporting purposes, but also for usage with Conditional Access to determine access to data and resources. The following nine steps walk through the process of creating a device compliance policy that includes (and focusses on) a custom compliance setting.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Endpoint security Device compliance
  2. On the Compliance policies | Policies blade, click Create Policy to open the Create a policy page
  3. On the Create a policy page, select Windows 10 and later with Platform and click Create
  4. On the Basics page, provide a valid name for the device compliance policy and click Next
  5. On the Compliance settings page, navigate to the Custom Compliance section (as shown in Figure 2), provide the following information and click Next
  • Custom compliance: Select Require to enable the custom compliance setting
  • Select your discovery script: Select the just uploaded PowerShell script
  • Upload and validate the JSON file with your custom compliance settings: Select the just constructed JSON file
  1. On the Actions for noncompliance page, leave the default configuration of Action on Mark device noncompliant with Schedule (days after noncompliance) on Immediately and click Next
  2. On the Scope tags page, configure the applicable scope tags and click Next
  3. On the Assignments page, configure the assignment by selecting the applicable group and click Next
  4. On the Review + create page, review the configuration and click Create

Note: Keep in mind that each device compliance policy supports a single script and that each script can detect multiple different settings.

Experiencing the results of custom compliance policies

Now let’s end this post by having a look at the results of a device compliance policy with a custom compliance setting. That will show it integrates with the compliance state of the device. Below in Figure 3 is an example of the BIOS version custom compliance setting that was created throughout this post.

More information

For more information about custom settings for compliance, refer to the following docs.

18 thoughts on “Working with custom compliance settings”

  1. “Custom Compliance is currently offered in preview. When it becomes generally available, you can add it for an additional cost to the licensing options that include Microsoft Endpoint Manager or Intune.”

    Looks like the era of Microsoft nickel and diming Intune customers has begun in earnest. First it was Remote Help, now this. Shameful.

      • It would be easier to swallow if it followed the same license scheme as the other products and they included it in either the E5 or an Endpoint Manager P2 plan or something.

        When compared to other products, like JAMF, WS1, Tanium, these are basic features that are not as well implemented as their competitors are. Its hard to recommend to customers as a solution when the items they are looking for are behind a significant additional pay wall.

        I dunno man, its just upsetting. Not like I actually have to pay the stuff, I just help people implement it.

  2. How to add a variable from powersehll to the description in json? something like below. Whats the right syntax?
    “Description”: “Please make sure that the BIOS version is up-to-date. – Current bios version is $biosInfo.SMBIOSBIOSVersion”

  3. How can I have Status show as “Not applicable”?
    It makes zero sense, it is a script, which evaluates to either (Yes, Compliant, or Not, Not Compliant)
    There is nothing grey here
    Also Overview pages (Policy assignment status — Windows 10 and later devices) makes no sense, it shows Error xx
    I assume the Error means it did run & evaluated to “Not Compliant” ?

  4. Total madness! One can NOT re-use the script for different models, because the new created policy chokes with
    “Message”: “The script 5c341fa9-9a95-40d2-9ce5-2736d5124dc8 is already being used by ba3dfbae-2ff3-41fd-9d04-3e6b79493c2d”
    Ofcourse it is already used, it is same generic script, the assignment (dynamic group based on model) is different!

      • That is correct – I am writing a compliance script to detect if Dell BIOS requires updating.
        I have 10 json files that all work with the 1 compliance script but I am unable to re-use the compliance script due to the above error
        I guess the solution here is to have a single massive compliance json…

        • But just for my understanding, why can’t you simplify that if you “just” want to check if it’s up-to-date or not? Are you creating scenario specific user notification?
          Regards, Peter


Leave a Reply to J Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.