Because of the popularity of my first blog post Deep dive Microsoft Intune Management Extension – PowerShell Scripts, I’ve decided to write a second post regarding Intune Management Extension to further explain some architecture behind this feature and upcoming question from the community. A deeper understanding helps to successful troubleshoot the feature.
Table of content for easy navigation
Details of the MSI deployment of the Intune Management Extension agent?
Please read the first article Deep dive Microsoft Intune Management Extension – PowerShell Scripts, to get an understanding of the MSI install job.
The EnterpriseDesktopAppManagement CSP takes care of this task and delivers the MSI to the device and starts the execution. The CSP provides some helpful information in registry for troubleshooting.
In the registry at HKLM\SOFTWARE\Microsoft\EnterpriseDesktopAppManagement\<SID>\<MSI-ProductCode> you can find helpful information for troubleshooting:
Highlighted value names are described in detail here:
CurrentDownloadUrl: URL to the MSI install file.
EnforcementRetryCount: The number of times the download and installation operation will be retried before the installation will be marked as failed.
EnforcementRetryIndex: The current number of retry.
EnforcementRetryInterval: Amount of time, in minutes between retry operations.
EnforcementStartTime: Start time of enforcement.
EnforcementTimeout: Amount of time, in minutes that the installation process can run before the installer considers the installation may have failed and no longer monitors the installation operation.
LastError: Error after last execution.
Status: The Status can have the following values according to the EnterpriseDesktopAppManagement CSP documentation:
Value = Status
10 = Initialized
20 = Download In Progress
25 = Pending Download Retry
30 = Download Failed
40 = Download Completed
48 = Pending User Session
50 = Enforcement In Progress
55= Pending Enforcement Retry
60 = Enforcement Failed
70 = Enforcement Completed
In case of no sidecar agent on the device the status may indicate an error or it is still in progress of downloading. Try to figure out this status. Correlate the status with your device and environment. There may be a proxy issue?
According to the screenshot above the CSP will try it 3 times with a timeout of 10 min and then it will be marked as failed. Is there a retry after x days, I assume yes but I don’t have some documentation for it. As soon as I have more information I will update the article accordingly.
Be aware of the log files regarding sensitive data!
The following script below will create a local user account with a specified static password. It is a working script, but be aware that it should not be used in production! The whole script content will be logged to the IntuneManagementExtension.log file. There you will find the clear text static password as defined in the script. As an example I have copied and marked the particular log file entries below the script to show that. Disk encryption technologies like BitLocker are lowering the risks a bit, but even then this is not a concept to be used in production environments! An attacker can read the log files with standard user permissions and get the sensitive data. Without BitLocker encryption this can be done even offline!
Again: I do NOT recommend transferring sensitive data like passwords via this approach! I know it’s often done. There is a similar approach for on-prem AD which is often used. The GPO preferences for local user management tasks uses a simple xml file with passwords base64 encoded -> this is not secure! Please consider something that was build for that purpose. Admin account management should be done via LAPS or other third party. I know there is no equivalent solution like LAPS for a cloud only environment right now from Microsoft.
# Author: Oliver Kieselbach
# Date: 01/03/2018
# Description: Create a local user account.
# REMARK: DO NOT USE IN PRODUCTION, Password will not be unique and be visible in clear text in log file!
# The script is provided "AS IS" with no warranties.
Param([switch]$Is64Bit = $false)
Function Restart-As64BitProcess
{
If ([System.Environment]::Is64BitProcess) { return }
$Invocation = $($MyInvocation.PSCommandPath)
if ($Invocation -eq $null) { return }
$sysNativePath = $psHome.ToLower().Replace("syswow64", "sysnative")
Start-Process "$sysNativePath\powershell.exe" -ArgumentList "-ex bypass -file `"$Invocation`" -Is64Bit" -WindowStyle Hidden -Wait
}
if (!$Is64Bit) { Restart-As64BitProcess }
else
{
Start-Transcript -Path "$env:temp\CreateLocalUser.log"
$password = ConvertTo-SecureString "SecretP@ssw0rd!" -AsPlainText -Force
New-LocalUser "John" -AccountNeverExpires:$true -FullName "John Doe" -Password $password
Stop-Transcript
}
To demonstrate the problem with this approach, here is the corresponding log file part after script execution with the complete script and static password in clear text:
Getting content of scripts once they are uploaded to Intune?
The Intune Azure Portal does not provide any UI element to show the uploaded script again. Thanks to the GitHub repository Intune PowerShell Samples we do not script something by our own. We can use a script provided from there called DeviceManagementScripts_Get.ps1. It will get all uploaded scripts, including script content, and details from the Intune API via Microsoft Graph API.
Get it from here:
https://github.com/microsoftgraph/powershell-intune-samples/blob/master/DeviceConfiguration/DeviceManagementScripts_Get.ps1
Save it locally and run it with PowerShell and provide your Intune Administrator credentials when asked for:
What about return codes (exit codes) of PowerShell scripts?
At the moment the Intune Management Extension will gather various results, but the Intune Azure portal does not show them in an UI element (if it will change in the future and we have something available, I will update the post accordingly). As for now scripts can be executed through the Intune agent and the Intune UI will show just the execution state success or failure. The status is related to successful agent execution, like no hash mismatch, no script content problem, and no error output… it does not reflect the script exit code.
Scripts like this, I called it “failscript.ps1” are handled as success at the moment:
[Environment]::Exit(-1)
See here the results in Intune Azure Portal:
Perhaps Intune will show us script exit codes in the UI sometime, then we could verify this easily with the failscript from above.
If we use Write-Error cmdlet in our scripts then Intune will pick up the error output. Here an example:
Write-Error -Message "Could not write regsitry value" -Category OperationStopped
This gives us a failed status in the monitoring section of the PowerShell scripts:
Where can I find a helpful PowerShell script template to start with?
I have made a simple script template which:
- Enforces execution in x64 PowerShell (restart of PowerShell as x64 process)
- Generates a log file in C:\Windows\temp when run in system context
or %LocalAppData%\temp when run in user context
- Has exit code handling (exit code is even gathered when restarted as x64 process)
- Uses Write-Error to signal Intune a failed execution and makes sure we have reporting reflecting our script execution success (standard error is even gathered when restarted as x64 process)
For ongoing maintenance it is provided via GitHub Gist:
Script execution retry interval when failed?
The PowerShell scripts are executed via agent on the target device. If an execution fails, the agent tries to run the script again during next check-in. Current check-in interval is every 60 minutes. This procedure is limited to 3 attempts!
This is tracked in registry at:
HKLM\SOFTWARE\Microsoft\IntuneManagementExtension\Policies\UserGUID\ScriptGUID
The DownloadCount also means execution count and the result is tracked as Success or Failed.
If we change the run as account (user/system), signature check or script content, the DownloadCount will be reset, and the agent will try another 3 attempts to execute the script.
If a script should be enforced to run again, we can simply reset DownloadCount and ErrorCode to 0 and set Result and ResultDetails to nothing (empty string). After this we just restart the Microsoft Intune Management Extension Service (IntuneManagementExtension) and the script will rerun again on this device.
Can we schedule scripts?
No we do not have a run schedule at the moment. For example the agent does not execute the script every x hours. The agent checks every 60 minutes for new policies in the backend – during this no re-run of scripts occurs once a script is successful executed. If scheduling of scripts is needed I suggest to register the script as a scheduled tasks via PS commands. That’s the only way at the moment (as soon as we have something available for scheduling I will update the post accordingly).
Below a script to copy the scheduled script to a certain folder like C:\ProgramData\CustomScripts\myScript.ps1 and then register a scheduled task to run it periodically:
# Author: Oliver Kieselbach
# Date: 01/31/2018
# Description: install ps script and register scheduled task
# The script is provided "AS IS" with no warranties.
# define your PS script here
$content = @"
Out-File -FilePath "C:\Windows\Temp\test.txt" -Encoding unicode -Force -InputObject "Hello World!"
"@
# create custom folder and write PS script
$path = $(Join-Path $env:ProgramData CustomScripts)
if (!(Test-Path $path))
{
New-Item -Path $path -ItemType Directory -Force -Confirm:$false
}
Out-File -FilePath $(Join-Path $env:ProgramData CustomScripts\myScript.ps1) -Encoding unicode -Force -InputObject $content -Confirm:$false
# register script as scheduled task
$Time = New-ScheduledTaskTrigger -At 12:00 -Daily
$User = "SYSTEM"
$Action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-ex bypass -file `"C:\ProgramData\CustomScripts\myScript.ps1`""
Register-ScheduledTask -TaskName "RunCustomScriptDaily" -Trigger $Time -User $User -Action $Action -Force
Here some documentation regarding PowerShell and scheduled tasks:
https://docs.microsoft.com/en-us/powershell/module/scheduledtasks/register-scheduledtask?view=win10-ps
But you need to think about a strategy how to track all this or how to modify in the future. Once set you may want to have a modification script to change schedules or even delete it from the device again.
Integrated HealthCheck of Intune Management Extension agent?
The Intune Management Extension creates a scheduled task which will run a Health Check once a day.
If familiar with ConfigMgr and the ConfigMgr agent, there we have the same concept. The health check involves 4 files:
ClientHealthEval.exe and ClientHealthEval.exe.config: The binary which runs the health check.
HealthCheck.xml: The xml with all rules to run to perform the health check.
HealthReport.json: The json report with results of the rules defined by the xml.
The tests are defined in the xml file to check the agent registered service, startup type, service status and memory usage.
User interaction and timeout?
When using a scripts with the typical user interaction (like shown as an example in my first article Deep dive Microsoft Intune Management Extension – PowerShell Scripts), be advised that this script is getting executed and showing a dialog which blocks the script from finishing, until the user interacts with the dialog and then let the script finish. This can lead to timeouts and then scripts are getting marked as failed even when successfully ran.
The current default script timeout is 10 minutes for execution which is currently not adjustable.
PowerShell scripts execution without user logon?
Since 22th of October the end users are no longer required to be logged in on the device to execute PowerShell scripts.
If you find something missing or changed feel free to leave a comment. Thanks!
Like this:
Like Loading...
Cloud managed environments benefit from the idea of software as a service, you don’t have to think about upgrading or maintenance of the infrastructure itself. But often we need to automate the tools itself. A very good example here is when an employee quits his job, than we need to trigger a lot of processes like disabling the account, retire of the device(s), wiping of the devices, sending some notes to various people and so on. Another example might be the cleanup of devices within Intune and Azure AD as they get stale over time and they are not used by users anymore.
