Windows 8.1 MDM: Demystifying the operation modes of MDMAgent.exe

  • Article

The Windows 8.1 Enterprise Device Management Protocol document talks about the different contexts that MDMAgent.exe runs under the “OMA DM Mode” section on page 48.

The three operation contexts are:

  • Maintenance
  • Apps
  • Machine

However, the document does not specify when/ how the different modes are triggered. The purpose of this blog is to provide some clarity around this topic.

The Maintenance and Apps task are “Scheduled Tasks” that get generated AFTER you enroll a user with your MDM Server. These tasks can be seen in the “Task Scheduler” (Control Panel\System and Security\Administrative Tools\Task Scheduler). If you look at the conditions of each of the Scheduled task, you will notice the triggers under which the MDMAgent.exe will run. Under each of these conditions, MDMAgent.exe will run as the “Local System” user account. When configuring user commands such as WNS Channel registration or app installs, even though the MDMAgent.exe is running as “Local System” account, it will impersonate as the enrolled user – EnrolledUserSID value and configure the values for these commands accordingly.

 

image

 

MDMAppInstallationTask

The “MDMAppInstallationTask” is triggered as soon as the Device receives a Push Notification (using the WNS Channel URI). The purpose of the app installation task is to start a sync with the MDM Server to initiate an app installation that the below workflow illustrates.

 

image

 

The steps to initiate the app install task are described below:

Step 1: Typically, the user enrolled with your MDM server initiates an app install through some mechanism – such as a Web Portal. This is where the user just selects the app they need to install.

Step 2: Once the user selects the app they wish to install, the MDM Sever somehow needs to let the MDMAgent.exe (running on the User’s Windows system) about the app install. Since the MDM Protocol is based on the HTTP Protocol, the MDM server needs to receive the HTTP request from the MDMClient to initiate the app install.

Step 3: WNS Push Notifications helps in this scenario where the MDM Server initiates a Push notification to the device by sending a request to the WNS Server

Step 4: Assuming that the WNS Channel was previously setup (using the ./cimv2/MDM_WNSConfiguration/MDM_WNSConfiguration.AppId=%22{AppId}%22/Exec=UpdateConfiguration command), the WNS Server initiates a Push notification to the device.

Step 5: When the device receives the Push notification, Windows will trigger the “MDMAppInstallationTask” scheduled task where MDMAgent.exe will run with the –App parameter. This initiates a HTTP request to the MDM Server and the MDM Server can then push down the app install command to start the app installation. The HTTP request to the MDM Server is sent in the following format: https://your_MDM_Server/your_Handler?mode=Apps&Platform=WoA (Notice the mode=Apps parameter)

Note: Step 4, and 5 will only succeed if the WNS Channel is “valid” and if Step 3 succeeds. There could be a scenario when the WNS Channel has been revoked for any reason by the WNS Server, so if you ever encounter that Step 3 fails because the channel has been revoked, then the MDM Server should make sure that during the next “Maintenance” window it should re-configure the WNS Channel by sending the UpdateConfiguration command (./cimv2/MDM_WNSConfiguration/MDM_WNSConfiguration.AppId=%22{AppId}%22/Exec=UpdateConfiguration) again and then schedule the App Install

 

MDMMaintenanceTask

This task gets triggered under the following conditions:

  1. Machine reboot
  2. User logon event
  3. Nightly maintenance task

In all the above conditions, MDMAgent.exe will run without any parameters.

1. Machine reboot: When you reboot your system, MDMAgent.exe will run in the “Machine” mode context. As soon as MDMAgent.exe starts running, it will notice that the user on behalf of whom the MDM Enrollment has happened has not logged on yet (due to the reboot), and will perform a SYNC with the MDM server in the “Machine” context. This will cause the MDMAgent.exe to send a HTTP request to the MDM server in the following format https://your_MDM_Server/your_Handler?mode=Machine&Platform=WoA (Notice the mode=Machine parameter)

2. User logon event: When you logon to the system as the user on behalf of whom the enrollment had happened, MDMAgent.exe will recognize that this is the same user for whom the enrollment has happened and will perform a SYNC with the MDM server in the “Maintenance” context. This will cause the MDMAgent.exe to send a HTTP request to the MDM server in the following format https://your_MDM_Server/your_Handler?mode=Maintenance&Platform=WoA (Notice the mode=Maintenance parameter)

3. Nightly maintenance task: The Nightly maintenance task will run during the normal scheduled Maintenance hour (typically 2am local time) and needs a bit of explanation especially around the “context” under which MDMAgent.exe will run.

During the nightly maintenance task, when MDMAgent.exe runs, it will first check to see whether the user on behalf of whom the enrollment has happened has an “active” logged on session. Here, the meaning of “active” logon, just means that:

  1. Either the enrolled user is actively using the system
  2. Or, it means that the enrolled user is not actively using the system, but has locked the system (but NOT logged off)

If such a user logged on session exists, ONLY under that situation, MDMAgent.exe will perform a SYNC with the MDM Server in the “Maintenance” context (mode=Maintenance).

If the enrolled user logon session is NOT available because the user had logged off from the system prior to the maintenance hour, then the MDMAgent.exe will perform a SYNC with the server ONLY in the “Machine” context (mode=Machine).

This is a very important point to understand about “when” does MDMAgent.exe run in the “Maintenance” mode v/s “Machine” mode.

It is also important to understand that when the MDMAgent.exe is running as the “Machine” context, the MDM Server MUST NOT send any other than the following types:

  1. Device Inventory commands (see the DM device inventory section on Page 53 of the Windows 8.1 Enterprise Device Management Protocol)
  2. Password reset (./cimv2/MDM_Client/MDM_Client.DeviceClientID=<unique device identifier>/Exec=ResetUserPassword)
  3. Un-Enrollment (./cimv2/MDM_Client/MDM_Client.DeviceClientID=<unique device identifier>/Exec=SendUnenrollRequest)

Any commands such as updating the WNS Configuration MUST only happen when MDMAgent runs in the Maintenance mode.

The MDM Server should extract the running parameter from the HTTP request querystring to determine what operation context was the SYNC performed as and only send the commands based on that context (?mode=Machine/Maintenance/Apps parameter of the HTTP request querystring).

 

Manual operation

While the above three operation contexts should be sufficient for normal SYNC’s to happen between the MDMAgent.exe and the MDM Server, you can also “interactively” invoke MDMAgent.exe from the command prompt. Although nothing stops you from running MDMAgent.exe as an “Administrator”, you should not expect that running MDMAgent.exe from the command prompt will return you the same results when compared to MDMAgent.exe running normally (as Local System).

There are certain calls required for impersonation that only the non-interactive user account (Local System) can perform which the interactive user does not have the necessary permissions to do. If any task requires user impersonation (such as WNS Channel management), then such tasks will fail when MDMAgent.exe runs interactively.

Hopefully this blog provides some clarification about when and how will the MDMAgent perform a SYNC with the MDM server and also the different type of modes it runs as and when it will run as a specific mode (Machine v/s Maintenance v/s Apps).

Don’t forget to follow the Windows Store Developer Solutions team on Twitter @wsdevsol. Comments are welcome, both below and on twitter.

 

- Prashant H. Phadke