How to “Push-button reset” Windows 10

The “push-button reset” (PBR) is the way to do a “factory reset” on Windows 10. It constructs a fresh Windows 10 installation and we can start over again.

Implementing a Microsoft 365 powered device mobility concept for a modern workplace with Windows 10, makes usage of Windows as a Service and provides new ways of self enrollment. Wherever we are, we service the OS from the cloud (Windows Update for Business) and manage it from the cloud (Intune).

In case of failure there are primarily two options:

  • Get a new device and enroll the device to Azure AD again
  • Start push-button reset to run a factory reset and start over again

In case of failure or if we want to re-purpose the device (back into stock or hand over to another employee) we use the push-button reset in this concept.

 

How is push-button reset triggered from the client?

First of all we need to distinguish between a device where the user is local administrator and a device where the user is standard user.

In case of local administrator the push-button reset can be triggered from Settings > Update & Security > Recovery > Reset this PC > Get started

PBR Settings Local Administrator

As shown there are two options available:

  • Keep my files
  • Remove everything

When choosing “Remove everything” we have the following two additional options:

PBRResetEverything

Be aware if “Remove files and clean the drive” is chosen it will really take a long time to complete!

 

In case of standard user we do not have the reset option in settings available. This is relevant when using AutoPilot and a profile with “Disable local admin account creation on the device” as shown below:

AutoPilotProfileSfB

As a standard user the settings are shown with no reset option in the recovery menu:

PBRSettingsStandardUser

For Microsoft 365 powered devices managed by Intune we can deploy the Company Portal and use it to trigger the reset. Open the deployed Company Portal > choose device > … (menu in the upper right) > Reset

PBRCompanyPortal

PBRCompanyPortalDialog

 

How is push-button reset triggered from Intune?

We need to open the Intune portal portal.azure.com and navigate to Intune > Devices > All Devices > pick the particular device > Factory reset

IntuneFactoryReset

as shown in the screenshot there is the additional option to “Retain the enrollment state and user account”.

For detailed description what is retained please refer to: https://docs.microsoft.com/en-us/intune/devices-wipe#factory-reset

If the device is on and connected, it takes less than 15 minutes for a factory reset command to propagate across all device types.

 

What is the “Fresh Start” available in Intune?

The Fresh Start device action removes any apps that were installed on a Windows 10 PC running the Creators Update, then automatically updates the PC to the latest version of Windows. This can be used to help remove pre-installed (OEM) apps that are often delivered with a new PC. You can configure if user data is retained when this device action is issued. In this case, apps and settings are removed, but the contents of the users Home folder are retained.

IntuneFreshStart

IntuneFreshStartDialog

If the device is on and connected, it takes less than 15 minutes for a factory reset command to propagate across all device types.

 

Reset in Action

When a reset is triggered the device will end up rebooting and the reset will occur.

Windows10Resetting

After finishing the reset the device will start in OOBE again for new enrollment or at the logon screen when enrollment was retained.

 

Issues with Lenovo devices and the troubleshooting

During tests I observed Lenovo devices which ran into an error after resetting and starting into OOBE again. Shortly after language and keyboard selection I got this:

OOBESomethingWentWrong

After some debugging I found out that the license.rtf file was not available in C:\Windows\System32 and this blocked the OOBE from displaying the EULA and resulted in the “Something went wrong” error screen. Click on “Try again” generated a loop.

I could solve this problem with a small customization of the PBR. The PBR has options to add a script to the PBR routine. More details see here: https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/add-a-script-to-push-button-reset-features

I prepared a script which copies the license.rtf file back to C:\Windows\System32 folder if it is missing after the reset. We need to prepare 2 files and we need the license.rtf from a running Windows 10 device.

EnableCustomizations.cmd

rem EnableCustomizations.cmd

rem Define %TARGETOS% as the Windows folder (This later becomes C:\Windows)
for /F "tokens=1,2,3 delims= " %%A in ('reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RecoveryEnvironment" /v TargetOS') DO SET TARGETOS=%%C

rem Define %TARGETOSDRIVE% as the Windows partition (This later becomes C:)
for /F "tokens=1 delims=\" %%A in ('Echo %TARGETOS%') DO SET TARGETOSDRIVE=%%A

rem Add back license.rtf file if missing
IF NOT EXIST "%TARGETOS%\System32\license.rtf" (
copy "%TARGETOSDRIVE%\Recovery\OEM\license.rtf" "%TARGETOS%\System32\license.rtf" /y
)
exit /b 0

ResetConfig.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- ResetConfig.xml -->
<Reset>
 <Run Phase="BasicReset_AfterImageApply">
 <Path>EnableCustomizations.cmd</Path>
 <Duration>2</Duration>
 </Run>
 <Run Phase="FactoryReset_AfterImageApply">
 <Path>EnableCustomizations.cmd</Path>
 <Duration>2</Duration>
 </Run>
</Reset>

In the end copy EnableCustomizations.cmd, ResetConfig.xml and the license.rtf to the folder:

C:\Recovery\OEM

After deploying the custom PBR fix for the Lenovo devices the push button reset runs smoothly.

 

Further information

Remove devices by using factory reset or remove company data
https://docs.microsoft.com/en-us/intune/devices-wipe

Push-button reset
https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/push-button-reset-overview

Add a script to push-button reset features
https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/add-a-script-to-push-button-reset-features

 

Happy resetting!

 

Configure Delivery Optimization with Intune for Windows Update for Business

When using the Modern IT approach and building Microsoft 365 powered devices it is a combination of the following cloud services for Modern Management:

WUfB

To support the Windows as a Service strategy with cloud services we rely on the well known Windows Update service, but with the controls for business usage. This is called Windows Update for Business (WUfB). That means our content is provided by Microsoft Update servers and we define the installation behavior like deferrals or even pause of feature or quality updates. The WUfB settings can be configured in Intune via Software Udpates. This article will not show the details of the WUfB settings. To monitor the Delivery Optimization Performance we have the Delivery Optimization Status in the Windows Analytics solution – Update Compliance.

For successful servicing we need to make sure an internet break out with proper bandwidth capacity is available to support our devices. To prevent internet traffic congestion we can utilize Peer 2 Peer technologies like BranchCache and Delivery Optimization to optimize Windows 10 update delivery. In case of Windows Update for Business we need to focus on Delivery Optimization (DO).

You can use Delivery Optimization to reduce bandwidth consumption by sharing the work of downloading these packages among multiple devices in your deployment. Delivery Optimization can accomplish this because it is a self-organizing distributed cache that allows clients to download those packages from alternate sources (such as other peers on the network) in addition to the traditional Internet-based Windows Update servers.

How does Delivery Optimization work in detail?

First of all the published content must be chunked and hashed. Currently Microsoft supports the following content:

  • Windows Updates (Feature/Quality)
  • Drivers
  • Store Apps

The basic procedure is:

  1. Client A checks for Updates
  2. Client A gets download sources (MS content server and additional clients (peers) B, C, …
  3. Client A requests chunks from MS content server and peers B, C, …
  4. Client A verifies hashes of chunks and builds file from chunks
  5. Client A verifies complete file via hash

The clients will check-in to the Delivery Optimization cloud service as long as the content is valid in its cache. This is necessary to let DO service keep track of devices and let it distribute peer info to requesting clients.

The Delivery Optimization has multiple Download Modes and this is an important part for successful utilization of DO. It configures the logical grouping of devices based on certain criteria. In this example we set Download Mode to Group and we use a custom group ID. This custom Group ID can be delivered by DHCP as an Option ID with code 234 when using upcoming Windows 10 Version 1803.

Group download mode is the recommended option for most organizations looking to achieve the best bandwidth optimization with Delivery Optimization.

The custom group id delivered by DHCP for scoped devices will let us take control over the grouping. We can assign multiple DHCP scopes the same Group ID or different Group IDs. That’s how we build our device collections and control the peer 2 peer traffic even across NATs.

The DO Peer 2 Peer traffic is a direct TCP/UDP connection on port 7680.

DOFirewall

Now we can build effective groups aligned with our networking infrastructure to restrict P2P traffic to physical sites, multiple sites, subnets, what ever we want.

 

How to configure DO with Intune?

At time of this writing I’m using the Insider Preview for the upcoming Windows 10 Version 1803 to test and include settings which are really worth to mention in this context.

I won’t get into details about every available setting but I will show a complete setup to test DHCP Option ID as source for Group ID.

The custom group ID can be generated by PowerShell:

[guid]::NewGuid()

The custom OMA-URI to configure Download Mode to Group is:

Name: DODownloadMode
OMA-URI: ./Vendor/MSFT/Policy/Config/DeliveryOptimization/DODownloadMode
Data type: integer
Value: 2 (group)

With Windows 10 Version 1803 we can provide the Group ID as a DHCP Option ID with code 234. To configure the client to use DHCP option ID we need to configure the following OMA-URI:

Name: DOGroupIdSource
OMA-URI: ./Vendor/MSFT/Policy/Config/DeliveryOptimization/DOGroupIdSource
Data type: integer
Value: 3 (DHCP Option ID)

Now we need to configure our DHCP infrastructure to provide the DHCP Option ID to our clients. In my example I use a Microsoft DHCP Server:

1. Set Predefined Options

 

MSDHCPpredefinedOptions

2. Configure the Predefined Options

MSDHCPpredefinedoptionsAdd

3. Confirm with OK

MSDHCPGroupIdValue

4. Configure Scope Options

MSDHCPScopeOptions

5. Set Custom Group ID as Option ID 234

MSDHCPScopeOptionsGroupId

6. Verify new Scope Option 234 DOGroupID

MSDHCPGroupIdOptionInScope

This would be enough to let all clients in the same DHCP scope group together and allow P2P traffic.

When testing DO in Virtual Machines I encourage you to configure the following additional settings:

  • DOMinFileSizeToCache to 1 MB to ensure caching with even small downloads
  • DOMinRAMAllowedToPeer to 1 GB to let VMs with small amount of RAM P2P
  • DOPercentageMaxForegroundBandwidth to limit manual Store download Bandwith (this will not restrict peer traffic) *
  • DODelayForegroundDownloadFromHttp to 30 seconds to give time to find other peers *

* Windows 10 Version 1803 is needed

Custom OMA-URIs:

./Vendor/MSFT/Policy/Config/DeliveryOptimization/DOMinFileSizeToCache = 1 (Integer, in MB)

./Vendor/MSFT/Policy/Config/DeliveryOptimization/DOMinRAMAllowedToPeer = 1 (Integer, in GB)

./Vendor/MSFT/Policy/Config/DeliveryOptimization/DOPercentageMaxForegroundBandwidth = 10 (Integer, in %)

./Vendor/MSFT/Policy/Config/DeliveryOptimization/DODelayForegroundDownloadFromHttp = 30 (Integer, in Sec.)

A test environment configuration may look like this:

DOMDMSettings

For production environments please review all available MDM Delivery Optimization settings and adjust as needed for your environment. For example DOMaxCacheAge, DOMinBackgroundQoS, DOPercentageMaxBackgroundBandwidth , and DOMinBatteryPercentageAllowedToUpload might be from interest for production environments. Remember to check for new settings with every new Version of Windows 10!

 

Test to verify everything works as expected!

Make sure the settings are applied to the test devices. Generate a advanced diagnostic report:

Open Settings > Accounts > Access work or school > Connected to TenantName’s Azure AD > Info > scroll down to the bottom and click “Create report”

AdvancedDiagnosticsReport

Important settings to verify:

DOMDMReport

Test procedure:

On Client A start a download from the Store with 100MB+ download size and wait for finish. You should observe a throttled download when using VMs with setting DOPercentageMaxForeDownloadBandwidth.

On Client B start the same download from the Store and wait for finish. You should notice a significant faster download on Client B, as it will receive data from local peer without restrictions when tested with VMs and mentioned settings above.

Since Windows 10 Version 1803 we can generate a DO log file to trace the behavior:

Get-DeliveryOptimizationLog | ft -Wrap | Out-File -FilePath $env:temp\DOLogs.txt ; notepad $env:temp\DOLogs.txt

Get the log files from Client A and B and look for entry “Using groupID”, here you must find the DHCP Group ID in both logs:

DOLogFileGroupId

On Client B you will find stats regarding communication with Peer Client A on port 7680:

DOLogfilePeerUsage

If you like to test again you can use disk cleanup utility to clean the DO cache:

DODiskCleanup

Then uninstall the Store app and start the test over again.

 

Further information

 

Happy caching and a good P2P utilization!

How to disable SMBv1 with Intune [deep dive analysis]

I recently got motivated to research a bit about new MDM settings available in the latest Windows 10 Insider Build (17074) and how to configure them. Settings available in preview Windows 10 versions normally do not have a lot of technical documentation for it or there is even no documentation for a particular feature and corresponding setting at preview release time.

In this post I would like to show how to get the right pieces of information to configure an ADMX-backed policy setting in Windows 10 via Intune OMA-URIs with no technical documentation for it. We need to get all implementation details by our self. My goal is to show some of the inner workings how parts of the MDM policies are implemented and how we can get a deeper understanding of them.

I’ll demonstrate my analysis with some new Windows 10 latest Insider build settings (at time of writing build version 17074) derived from MSSecurityGuide to control SMBv1 on the device. The two settings are:

  • ConfigureSMBV1ClientDriver
  • ConfigureSMBV1Server

These settings control the SMB 1.0/CIFS File Sharing Support

Optional Feature SMBv1

 

How do we get to know this new available settings?

First we have a look at the registry. There is a new place where you can find MDM Policy CSP settings. Group Policy settings are stored in the Policies registry key and MDM Policy CSP settings can be found in the PolicyManager key here:

HKLM\SOFTWARE\Mircosoft\PolicyManager

As we see in the screenshot below there are two different sub keys. One current key and a default key.

Within the current key we find all settings configured for this device by Policy CSP via MDM like Intune. Within the default key we find all available settings for the particular Windows 10 release.

RegistryPolicyManagerDefault

As mentioned the latest Windows 10 version (at time of writing build version 17074) has a sub key for MSSecurityGuide with additional sub keys for ConfigureSMBV1ClientDriver and ConfigureSMBV1Server.

RegistryPolicyManagerSMBv1

If we have a look at the details, for example of ConfigureSMBV1ClientDriver we see the value name admxMetadataDevice. This gives us a hint that this particular policy is an ADMX-backed policy.

SMBv1ADMXHint

 

How do we configure it if we don’t know the input values for it?

The way Microsoft implemented the feature ADMX-backed policies is as follows:

A defined set of the default policies which come with the OS in the path C:\Windows\PolicyDefinitions are parsed at OS build time and stored in the MDM store as converted MDM policies. The second way is to ingest custom ADMX files after OS shipment which are then also parsed and stored in the MDM store as MDM policies. I wrote an ADMX file ingestion article for a custom OneDrive ADMX file here: Deep dive ADMX ingestion to configure SilentAccountConfig with OneDrive.

For a thorough understanding everyone should read the Background section of the Microsoft docs article Understanding ADMX-backed policies.

With all that in mind we need to find the original ADMX file for the policy and then we can derive the actual values for configuration because ADMX-backed policies are configured by a schema derived from the ADMX xml file structure.

Luckily I know that the MSSecurityGuide is provided by Microsoft through the Microsoft Security Compliance Toolkit 1.0 and within that package is the Windows 10 Version 1709 Security Baseline.zip. This includes the SecGuide.admx in the subfolder Templates.

SecGuideAdmx

Due to public knowledge how to configure ADMX-backed policies we can derive the configuration input values from the SecGuide.admx file. To derive the input values we need to study the article Understanding ADMX-backed policies especially the sections ADMX-backed policy examples and Sample SyncML for various ADMX elements.

To create the OMA-URI we append the registry key MSSecurityGuide and the sub key ConfigureSMBV1ClientDriver to ./Vendor/MSFT/Policy/Config/

./Vendor/MSFT/Policy/Config/MSSecurityGuide/ConfigureSMBV1ClientDriver

Now we need to follow the Sample SyncML for various ADMX elements for proper Enum usage as input value to disable the SMBv1 Client driver

  1. find enum
  2. get name from id attribute
  3. choose value for disable

SecGuideAdmxXml

construct the xml data element with derived values for id and value:

<data id="Pol_SecGuide_SMB1ClientDriver" value="4"/>

The result is the following custom OMA-URI setting:

Name: ConfigureSMBV1ClientDriver
OMA-URI: ./Vendor/MSFT/Policy/Config/MSSecurityGuide/ConfigureSMBV1ClientDriver
Data type: string 
Value:
<enabled/>
<data id="Pol_SecGuide_SMB1ClientDriver" value="4"/>

 

According to How to detect, enable and disable SMBv1, SMBv2, and SMBv3 in Windows and Windows Server the SMBv1 Server can be controlled by this registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters
Registry entry: SMB1 REG_DWORD: 0 = Disabled

To disable the SMBv1 Server we need to set the registry value SMB10 and this is the disabled value in the SecGuide.admx xml file.

SecGuideAdmxXml2

The result is the following custom OMA-URI setting:

Name: ConfigureSMBV1Server
OMA-URI: ./Vendor/MSFT/Policy/Config/MSSecurityGuide/ConfigureSMBV1Server
Data type: string 
Value: <disabled/>

Now we configure this as a custom OMA-URI in Intune and target it to our user group with Windows 10 Insider builds

SMBv1MDMOMAURI

 

How to verify if the settings are correctly deployed?

First of all we can generate a MDM Advanced Diagnostics Report:

Open Settings > Accounts > Access work or school > Connected to TenantName’s Azure AD > Info > scroll down to the bottom and click “Create report”

AdvancedDiagnosticsReport

open the Report MDMDiagReport.html it in Edge and look for:

MDMReport

Second we can check the registry for MDM applied settings:

SMBv1MDMSetting

Third we can verify the SMBv1 LanmanServer > Parameters > SMB1 = 0:

SMBv1ServerSetting

We can query the Windows feature if not enabled via PowerShell:

Get-WindowsOptionalFeature -Online -FeatureName SMB1Protocol

SMBv1WindowsFeature

We can verify the SMBv1 Client and Server component via PowerShell:

Get-SmbServerConfiguration | Select EnableSMB1Protocol, EnableSMB2Protocol

SMBv1ServerConfig

sc.exe query MRXSMB10

SMBv1ClientConfig

Congratulations you successfully disabled the SMBv1 protocol as recommended in the Security Baseline for Windows 10!

Important note

SMBv1 is not installed by default in Windows 10 Fall Creators Update and Windows Server, version 1709
https://support.microsoft.com/en-us/help/4034314/smbv1-is-not-installed-windows-10-and-windows-server-version-1709

If a Windows 10 Version was upgraded from an earlier edition like RS2 to RS3, SMBv1 is not deactivated, the install state is migrated. SMBv1 will not be installed for fresh RS3 installations. The setting above would enforce uninstall of SMBv1 for migrated devices.

Further information

Configuring Windows Defender Credential Guard with Intune

The Windows Defender Credential Guard is a feature to protect NTLM, Kerberos and Sign-on credentials. Windows 10 Enterprise provides the capability to isolate certain Operating System (OS) pieces via so called virtualization-based security (VBS). NTLM and Kerberos credentials are normally stored in the Local Security Authority (LSA). Once VBS is enabled the LSASS process will be split into an isolated process (protected by virtualization based security)  called LSAiso and the LSASS process. The LSAiso process can not be accessed by other OS components than the LSASS. This approach protects credentials from malicious tools which gained system context access. A well known tool to accomplish extraction of credentials from LSASS in system context is Mimikatz. This will not work after enabling Windows Defender Credential Guard as the only process validated to gain access to LSAiso process is LSASS.

With that in mind Credential Guard can protect an attack vector used by a lot of bad guys trying to steal sensitive information. It’s really worth considering to turn this protection on for Windows 10 Enterprise x64 (no support for x86) devices.

CredentialGuardDesign

Further information of Credential Guard:
https://docs.microsoft.com/en-us/windows/access-protection/credential-guard/credential-guard-how-it-works

 

How do we configure this via Modern Management in Intune?

Since Windows 10 Version 1709 Microsoft provides Policy CSP support to configure Credential Guard via custom OMA-URIs. We can create a custom device profile:

CreateDeviceProfile

and then choose Profile type: custom

CredentialGuardDeviceProfile

Here we add the following OMA-URIs to configure Credential Guard with default settings and additional DMA Protection:

Name: DeviceGuard/EnableVirtualizationBasedSecurity
OMA-URI: ./Vendor/MSFT/Policy/Config/DeviceGuard/EnableVirtualizationBasedSecurity
Data type: integer
Value: 1 (enable virtualization based security)

Name: DeviceGuard/LsaCfgFlags
OMA-URI: ./Vendor/MSFT/Policy/Config/DeviceGuard/LsaCfgFlags
Data type: integer
Value: 1 (Enabled with UEFI lock)

Name: DeviceGuard/RequirePlatformSecurityFeatures
OMA-URI: ./Vendor/MSFT/Policy/Config/DeviceGuard/RequirePlatformSecurityFeatures
Data type: integer
Value: 3 (Turns on VBS with Secure Boot and direct memory access (DMA). DMA requires hardware support.)

Further information regarding Policy CSP values:
https://docs.microsoft.com/en-us/windows/client-management/mdm/policy-csp-deviceguard

As a last step we assign the new device configuration profile to our user group we want to provide the additional Credential Guard protection.

 

How to verify successful configuration?

First of all we verify if Intune applied the configuration successfully:

CredentialGuardDeploymentStatus

Then you can verify the applied registry settings on the target device of the user:

CredentialGuardRegistrySettings

Further information regarding registry settings:
https://docs.microsoft.com/en-us/windows/access-protection/credential-guard/credential-guard-manage

Make sure the device was restarted after successful configuration! This is needed as Credential Guard relies on Hyper-V technology for virtualization-based security and therefore it will enable the feature Hyper-V Hypervisor component.

We can have a look for the LsaIso.exe process in task manager:

CredentialGuardProcess

Finally we open up msinfo32.exe and verify if virtualization-based security is running and Credential Guard is activated:

CredentialGuardMsinfo32

If everything went well your machine is now protected against stealing of password secrets (hashes) which can be used by attackers for Pass-The-Hash (PTH) attacks. Keep in mind that this will not protect against attacks like key loggers. The solution is an effective way to protect credential stealing from memory.

 

How to test this in a Hyper-V Virtual Machine?

When using Microsoft Hyper-V you can enable nested virtualization on the VM and enable the Trusted Platform Module. Now you can test Credential Guard in your Hyper-V VM.

Enabling nested virtualization on Hyper-V VM:

Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true

Further information on nested virtualization:
https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/nested-virtualization

Enabling the TPM on Hyper-V VM:

HyperVTPM

 

Additional things to consider?

The target hardware must support Credential Guard
https://docs.microsoft.com/en-us/windows/access-protection/credential-guard/credential-guard-requirements

Compatibility problems
https://docs.microsoft.com/en-us/windows/access-protection/credential-guard/credential-guard-considerations

Limitation in protection
https://docs.microsoft.com/en-us/windows/access-protection/credential-guard/credential-guard-protection-limits

 

UPDATE

Virtualization based security (VBS) will be available for non-Enterprise SKUs and starting with RS4+ VBS will be automatically enabled for clean installs!

 

If you are using Windows 10 please try Credential Guard in your environment as it is a really big security enhancement of Windows 10 Enterprise.

Deep dive Microsoft Intune Management Extension – PowerShell Scripts

Microsoft made a big step forward in the Modern Management field. Limitations like custom configurations or even Win32 App installs can be addressed now. Microsoft developed an EMS agent (aka SideCar) and released it as a new Intune feature called Intune Management Extension. This agent is able to manage and execute PowerShell scripts on Windows 10 devices and it does this quite well.

IntuneManagementExtensionMSIProperties

We can simply upload our own PowerShell scripts for device configuration:

PowerShellScriptsIntune

Part 2 of this article answers common questions I’ve seen, when working with the Intune Management Extension – Part 2, Deep dive Microsoft Intune Management Extension – PowerShell Scripts.

Part 3 of this series will dive into the Microsoft Intune Management Extension – Win32 Apps deployment capabilities – Part 3, Deep dive Microsoft Intune Management Extension – Win32 Apps

 

How do we get the agent installed on the devices?

The ability to deploy basic MSI packages via MDM OMA-DM channel, is provided by Microsoft since the beginning of Windows 10. This is achieved by using the EnterpriseDesktopAppManagement CSP.

Microsoft is using this mechanism to deploy the agent to Windows 10 devices. Beginning with Windows 10 Version 1607 we have support of the Intune Management Extension now. The device must be AAD joined and the automatic MDM enrollment must be enabled (see Prerequisites).

The workflow is basically like this. If a PowerShell script is assigned to a user group (device groups are not supported since 22th of Oct.) and the agent is not installed, it will be pushed down automatically to the device via EnterpriseDesktopAppManagement CSP by Intune. This can be verified and traced in the “Advanced Diagnostics Report” of the MDM management.

Open Settings > Accounts > Access work or school > Connected to TenantName’s Azure AD > Info > scroll down to the bottom and click “Create report”

AdvancedDiagnosticsReportNow you get an report about all MDM configurations including the desktop app installations. Here we can see the EnterpriseDesktopAppManagement msi install of the EMSAgent with the ProductCode: {25212568-E605-43D5-9AA2-7AE8DB2C3D09}

EMSAgentInstallReport

./device/Vendor/MSFT/EnterpriseDesktopAppManagement/MSI/%7B25212568-E605-43D5-9AA2-7AE8DB2C3D09%7D

The instruction can be translated into more human readable form with ProductCode and curly brackets, as the yellow marked resource uses URL encoding and here %7B = { and %7D = }

./device/Vendor/MSFT/EnterpriseDesktopAppManagement/MSI/{25212568-E605-43D5-9AA2-7AE8DB2C3D09}

If the device encounters any error during installation of the agent, we can troubleshoot this with the eventlog:

Start event viewer > Applications and Services Logs > Microsoft > Windows > DeviceManagement-Enterprise-Diagnostics-Provider > Admin

An example where the agent installation went wrong with an error event id 1924 looks like this:

Event ID 1924, Error

EnterpriseDesktopAppManagement CSP: An application install has failed. 
Examine the MSI log (C:\Windows\system32\config\systemprofile\AppData\
Local\mdm\{25212568-E605-43D5-9AA2-7AE8DB2C3D09}.log) for more details. 
Install command: ("C:\Windows\system32\msiexec.exe" /quiet /l*v 
C:\Windows\system32\config\systemprofile\AppData\Local\mdm\
{25212568-E605-43D5-9AA2-7AE8DB2C3D09}.log /qn /i "C:\Windows\system32\
config\systemprofile\AppData\Local\mdm\
{BD19E4D8-D6C9-48B2-A53C-579D03B29FE9}.msi" ), 
MSI ProductCode: {25212568-E605-43D5-9AA2-7AE8DB2C3D09}, 
User SID: (S-0-0-00-0000000000-0000000000-000000000-000), 
Result: (User cancelled installation.).

Here we can see the original MSI install command including logfile path for further analysis:

C:\Windows\system32\config\systemprofile\AppData\Local\mdm\ {25212568-E605-43D5-9AA2-7AE8DB2C3D09}.log

The agent will get installed in the 32-bit Program Files path:

C:\Program Files (x86)\Microsoft Intune Managment Extension

IntuneManagementExtension

 

How does the agent gets it’s policy?

The agent will start to figure out the service endpoint via Service Discovery. A common approach in Microservices architecture in modern cloud platforms. After getting the Intune Service URL (https://somemssubdomain.manage.microsoft.com/SideCar/StatelessSideCarGatewayService) the agent can start to communicate and will receive its assigned policies.

All this can be traced in the logfiles here:

C:\ProgramData\Microsoft\IntuneManagementExtension\Logs

IntuneManagementExtensionLogs

The agent will start to download and execute the assigned PowerShell script here:

C:\Program Files (x86)\Microsoft Intune Managment Extension\Policies\Scripts\UserGUID_ScriptGUID.ps1

and the results are written here:

C:\Program Files (x86)\Microsoft Intune Managment Extension\Policies\Results\UserGUID_ScriptGUID.output|.error|.timeout

After successful execution the script and results are cleaned up and nothing is left on the device. Corresponding registry entries for the assigned scripts and execution results are here:

HKLM\SOFTWARE\Microsoft\IntuneManagementExtension\Policies\UserGUID\ScriptGUID

IntuneManagementExtensionRegistry

 

How often does the agent check for new policies?

The default is every 60 minutes.

 

What are the PowerShell script execution options?

We can execute scripts in system context or user context. Optional we can enforce a signature check.

ScriptSettings

The current file size limit is 10KB for ASCII scripts and 5KB for unicode scripts. The current file size limit is max. 200KB.

 

How do I enforce next agent check for policies?

Simply restart the Windows Service “Microsoft Intune Management Extension”.

IntuneManagementExtensionWindowsService

 

Is there a particular order in which multiple scripts are executed?

No, they are executed in random order.

 

What can be done with the PowerShell script execution?

Some examples and potentially pitfalls with the usage of the Intune Management Extension are listed below:

Install Win32 application

Install Win32 applications can be done easily by using a web request to get sources for the installation and finally execution of the sources. This technique is used a lot in the Chocolatey space. A simple example with 7-zip is shown below and can be modified to your needs:

# Author: Oliver Kieselbach
# Date: 11/28/2017
# Description: Download executable or msi and execute to install.

# The script is provided "AS IS" with no warranties.
$url = "http://www.7-zip.org/a/7z1701-x64.msi"
$filePath = "c:\windows\temp\7z1701-x64.msi"
$ProgressPreference = 0
Invoke-WebRequest $url -OutFile $filePath -UseBasicParsing
& $filePath /quiet

To use Chocolatey you should follow the install instructions from the Chocolatey website:

iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

After Chocolatey Framework installation you can use choco.exe install Package in additional PS scripts to install Chocolatey software. An excellent post from Peter van der Woude regarding Chocolatey and Intune Management Extension can be found here: Combining the powers of the Intune Management Extension and Chocolatey

 

Write registry keys in x64 hive and not WOW6432Node

As the agent is an 32-bit agent every PowerShell script execution will be in the 32-bit agent process. If we write a registry key on a x64 device from a 32-bit process it will be redirected to the WOW6432Node in the registry. This is often not the desired behavior. To solve this we can restart the script as a 64-bit process for script execution. An example to write a registry key to the x64 hive with this technique is shown below:

# Author: Oliver Kieselbach
# Date: 11/28/2017
# Description: Write to registry and ensure execution from x64 process environment.

# 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
}

Function New-RegistryKey
{
 Param([Parameter(Mandatory = $true)]
 [string]$Key,
 [Parameter(Mandatory = $true)]
 [string]$Name,
 [Parameter(Mandatory = $true)]
 [string]$Value,
 [ValidateSet("String", "ExpandString", "Binary", "DWord", "Multistring", "QWord", ignorecase=$true)]
 [string]$Type = "String")
 try
 {
 $subkeys = $Key.split("\")

foreach ($subkey in $subkeys)
 {
 $currentkey += ($subkey + '\')
 if (!(Test-Path $currentkey))
 {
 New-Item -Type String -Path $currentkey | Out-Null
 }
 }

Set-ItemProperty -Path $currentkey -Name $Name -Value $Value -Type $Type -ErrorAction SilentlyContinue
 }
 catch [system.exception]
 {
 $message = "{0} threw an exception: `n{0}" -f $MyInvocation.MyCommand, $_.Exception.ToString()
 Write-Host $message
 }
}

if (!$Is64Bit) { Restart-As64BitProcess }
else
{
 # Enable Potentially Unwanted Application protection
 New-RegistryKey -Key "hklm:\SOFTWARE\Microsoft\Windows Defender" -Name "PUAProtection" -Value "1" -Type DWord
}

Please see my GitHub account for Intune Management Extension Samples for a enhanced and maintained PowerShell Template (IntunePSTemplate.ps1) which takes care of x64 restarting, logging and so on!

 

Execute in user context and show dialog

To show a simple example to execute scripts in user context we can use the following script to present a Message Box to the user:

 Add-Type -AssemblyName PresentationFramework
 [System.Windows.MessageBox]::Show('Hello World from Sid-Car!')

HelloSideCar

 

I hope this explains the technical implementation of the Microsoft Intune Management Extension and the extension addresses some road blockers you might have in the past with Intune regarding advanced configurations.

See also my follow up post Part 2, Deep dive Microsoft Intune Management Extension – PowerShell Scripts for even more details and common questions around architecture and troubleshooting.

Part 3 of this series will dive into the Microsoft Intune Management Extension – Win32 Apps deployment capabilities – Part 3, Deep dive Microsoft Intune Management Extension – Win32 Apps