TroubleshootingIntune PowerShell Scripts
PowerShell is a cross-platform task automation solution made up of a command-line shell, a scripting language, and a configuration management framework. In some of our posts we discuss using PowerShell scripts
to perform various tasks, such as deploying Intune Remediation scripts or setting up Windows kiosk mode with the MDM Bridge. We also have a post discussing how to leverage the Power of AI in PowerShell Scripting. Once you have developed your PowerShell script, you may be looking to deploy it with Intune.
There are multiple ways to run PowerShell scripts using Microsoft Intune or Microsoft Endpoint Manager (MEM). These include the in-built PowerShell feature for running scripts once, proactive remediations for scheduling script runs or fixing common support issues, and Win32 for deploying scripts as an app package.
In this article, we will focus on the in-built Intune PowerShell feature for one-time script execution. We will address the challenges in troubleshooting PowerShell scripts and explore how MPA Tools can simplify the process of identifying these issues.
Quickly about Intune management extension (IME)
Intune Management Extension (IME) improves the management of Windows devices using MDM, facilitating the transition to modern management. The IME is installed automatically on devices when either a PowerShell script or a Win32 app is targeted to the device or associated user. Upon execution of the PowerShell script, the IME downloads and runs it from the path C:\Program Files (x86)\Microsoft Intune Management Extension\Policies\Scripts. The action is recorded in the IME log file C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\IntuneManagementExtension.log.
The IME log records detailed and verbose information about every policy execution transaction. However, it can be quite challenging to find the necessary information to troubleshoot issues in your scripts. Unfortunately, the Intune portal doesn’t provide much reporting information, so we have to rely on the IME log file to see the execution return code and the resulting message (stderr or stdout) returned from the PowerShell execution environment. To demonstrate, a failed PowerShell execution can reveal a simple underlying issue that may seem obvious once discovered. However, identifying it using the Intune portal and IME log can prove to be not so obvious.
OK, our quick config
- First, we have set up a PowerShell script in Intune titled “Remove Access Rule on System Drive” which should execute the PS script Remove-AccessRuleOnSystemDrive.ps1. This script removes the Access Control Entry in the ACL for Authenticated Users on the system drive to prevent users from creating folders on the root of C:\.
- We have validated with stand-alone execution on a test device that the script works as intended and successfully performs the ACL changes without error.
- However, an error is returned when we assign the “Remove Access Rule on System Drive” PowerShell script in Intune (as shown below).
Debugging Intune PowerShell Script
When we click on the error, we see the device and username, but the status displays an “Unknown” error. From the portal view, there isn’t much information other than messaging to show that there was an error.
We see the same “Unknown” error status in the “Device Status” view.
We also see the same “Unknown” error status if we export the results in the “Device Status” view.
Since the portal does not offer any useful information that can be used to troubleshoot the issue, we will need to investigate further using the registry and IME log. For this, we will need the policy ID, which we can retrieve from the address bar in the Intune portal (when viewing the PowerShell script configuration). In this case the policy ID is 9203dbb9-67bb-49f4-b017-45ec87c6ece6.
If we navigate to the registry path HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\IntuneManagementExtension\Policies and expand the registry key for policy 9203dbb9-67bb-49f4-b017-45ec87c6ece6, we can see some of the policy execution information. But unfortunately, the Result value only shows “Failed,” which doesn’t provide us with the actual PowerShell execution error. Although, in the ResultDetails value, we can see the ExecutionMessage that was returned is “3”. We are getting closer, but we still do not have any information that can tell us what the actual script error is.
Dive Deeper with Troubleshooting Intune PowerShell Script
Next, we can search the IME log file (C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\IntuneManagementExtension.log) for the policy ID. Hopefully, we will find the information we need in order to troubleshoot the script. However, we will have to do a fair amount of searching before we can find this information (as shown below).
We will now be reviewing some logs that may be difficult to read, but are extremely useful. Please follow along with me.
This IME log entry suggests that there was an error file generated in the C:\Program Files (x86)\Microsoft Intune Management Extension\Policies\Results folder, however, the file would need to be captured at the time of the PowerShell script execution. After which, the file is cleared from the folder (as shown below).
First, take a look into the highlighted in the previous picture folder, it will be empty!
If we keep searching the IME log, we eventually find the policy result, which shows as “Failed” (same as the registry value).
“Remove-LocalGroupMember : The term ‘Remove-LocalGroupMember’ is not recognized as the name of a cmdlet, function, \r\nscript file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is \r\ncorrect and try again.
The PS script appears to have failed to execute the cmdlet Remove-LocalGroupMember, which is odd because the Remove-AccessRuleOnSystemDrive.ps1 script does not use this cmdlet. This is the “penny drop” moment when we realize the script content might be wrong.
If we search back up through the IME log file, we can find the PS script content and as shown below, it is clear that the PS script name is in fact Remove-AccountsFromLocalAdminGroup and not Remove-AccessRuleOnSystemDrive as expected.
Troubleshooting Intune PowerShell Script With MPA Tools
Now, let’s compare this painful and arduous process of trawling through the IME log file for root cause information with what MPA Tools can provide easily…
If we select the test device in MPA Tools and then select the Intune Deployed PowerShell Scripts node, we can see the failure for the “Remove Access Rule on SystemDrive” policy (as shown below).
Important: An Azure application must be registered for MPA Tools with your Azure AD tenant to delegate identity and access management functions to Azure AD. When you register an application with Azure AD, you create an identity configuration that allows it to integrate with Azure AD. For more information, see Connecting MPA Tools to Azure Tenant: A Step by Step Guide.
If we use the navigation slider to scroll to the right, we can see that the script file name is Remove-AccountsFromLocalAdminGroup.ps1. We can also see the result message is “3” (as shown before in the registry), and the error description is “The system cannot find the path specified“.
From here, it is easy to tell that if I revisit the “Remove Access Rule on SystemDrive” Intune configuration, the script settings are not showing the correct PowerShell script and that we must have selected the wrong script when we were uploading the script during the initial configuration.
IT HAPPENS!!! 🙂
All we need to do now is to fix our PowerShell package by uploading a correct Script file.
In conclusion, MPA Tools easily provides the status messages and return codes required for troubleshooting PowerShell scripts fast and effectively, which can be done remotely before having to access the IME log file that is stored locally on the device. Granted, there may be times where extensive troubleshooting using the IME log may be required but MPA Tools will quickly provide you most of what you need to get started and point you in the right direction when it comes to resolving PowerShell script issues!
Also, Microsoft Intune troubleshooting articles can be found here
Frequently Asked Questions (FAQs)
What is the Intune Management Extension (IME) and its role in running PowerShell scripts?
IME enhances Windows device management using MDM and is automatically installed when PowerShell scripts or Win32 apps are targeted to the device. It executes scripts from a specific path and logs actions.
How do you troubleshoot PowerShell script errors in Intune?
Troubleshooting requires checking the IME log file and the registry for error details, as Intune portal provides limited information on script execution errors.
What common issues might occur with PowerShell script execution in Intune?
Errors can range from incorrect script names to path issues, often indicated by vague error messages in Intune and detailed in the IME log.
How can MPA Tools aid in troubleshooting PowerShell scripts in Intune?
MPA Tools provides an easier way to access status messages and return codes for PowerShell scripts, streamlining the troubleshooting process.
What steps are involved in debugging a failed PowerShell script in Intune?
Debugging involves checking the Intune portal for error status, retrieving the policy ID, examining the registry, and reviewing the IME log for detailed error information.
How do you identify the actual script error in Intune?
The actual error is often discovered by examining the IME log for script execution details and error messages.