2.2.9.3 DMClient Configuration Service Provider

Article
04/23/2024

The DMClient configuration service provider is used to specify additional enterprise-specific mobile device management configuration settings for identifying the device in the enterprise domain, security mitigation for certificate renewal, and server-triggered enterprise unenrollment.

The following diagram shows the DMClient configuration service provider in tree format.

The DMClient configuration service provider in tree format

Figure 5: The DMClient configuration service provider in tree format

DMClient: Root node for the CSP.

UpdateManagementServiceAddress: For provisioning packages only. Specifies the semicolon-delimited list of servers. The first server in the list is the server that will be used to instantiate MDM sessions. The list can be a permutation or a subset of the existing server list. New servers cannot be added to the list using this node

Provider: Required. The root node for all settings that belong to a single management server. Scope is permanent. Supported operation is Get.

ProviderID: Optional. This node contains the URI-encoded value of the bootstrapped device management account's Provider ID. Scope is dynamic. As a best practice, use text that doesn't require XML/URI escaping. Supported operations are Add and Get.

ProviderID/EntDeviceName: Optional. The character string that contains the user-friendly device name used by the IT admin console. The value is set during the enrollment process by way of the DMClient configuration service provider. It can be retrieved later during an OMA DM session. Supported operations are Add and Get.

ProviderID/EntDMID: Optional. The character string that contains the unique enterprise device ID. The value is set by the management server during the enrollment process by way of the DMClient configuration service provider. It can be retrieved later during an OMA DM session. Supported operations are Add and Get.

Although hardware device IDs are guaranteed to be unique, there is a concern that this is not ultimately enforceable during a DM session. The device ID could be changed through the w7 APPLICATION configuration service provider's USEHWDEVID parmeter by another management server. So during enterprise bootstrap and enrollment, a new device ID is specified by the enterprise server.

This node is required and MUST be set by the server before the client certificate renewal is triggered.

ProviderID/ExchangeID: Optional. The character string that contains the unique Exchange device ID used by the Outlook account. This is useful for the enterprise management server to correlate and merge records for a device that is managed by exchange and natively managed by a dedicated management server. Supported operation is Get. The following is a Get command sample. Implementers MUST replace "TestMDMServer" with the actual name of the configured Provider ID. The ExchangeID is per user and for Azure Active Directory (Azure AD) enrollments the value depends on the logged in user.

    <Get>
      <CmdID>12</CmdID>
        <Item>
          <Target>
            <LocURI>./Vendor/MSFT/DMClient/<ProviderID>/TestMDMServer/ExchangeID</LocURI>
        </Target>
      </Item>
    </Get>

ProviderID/LinkedEnrollment/Enroll: The LinkedEnrollment/Enroll command will trigger an enrollment in a Declared Configuration environment. This is an enrollment type that exists side-by-side with the existing enrollment, and which provides instruction to the device using the Declared Configuration format. This uses the device token from the device which MUST be joined to Azure AD. Supported operation is Exec.<4>

ProviderID/LinkedEnrollment/UnEnroll: The LinkedEnrollment/Unenroll command will trigger a silent unenrollment from a side-by-side Declared Configuration environment. When the device is unenrolled all settings and resources provisioned by the Declared Configuration environment MUST be rolled back or removed. Supported operation is Exec.<5>

ProviderID/LinkedEnrollment/EnrollStatus: Required. LinkedEnrollment/EnrollStatus is an integer value used to check whether a device has a linked enrollment in a Declared Configuration environment. The value MUST be one of those in the following table.<6>

Name	Value
Undefined	0
NotStarted	1
InProgress	2
Failed	3
Succeeded	4

ProviderID/LinkedEnrollment/LastError: Optional. The integer value that indicates the HRESULT of the last enrollment error code. Supported operation is Get.<7>

ProviderID/LinkedEnrollment/DiscoveryEndpoint: Optional. The DiscoveryEndpoint is a URL that indicates the location of a specific discovery service (section 3.1). If present, the value indicates the discovery service that is used to create a linked Declared Configuration enrollment. If the value is not present, then the client will return an empty string. Supported operations are Set, Get, and Delete.<8>

The following is an example of the SyncML for setting the discovery endpoint for LinkedEnrollment/Enroll:

    <SyncML xmlns="SYNCML:SYNCML1.1">  
        <SyncBody>  
            <Replace>  
               <CmdID>2</CmdID>  
                <Item>  
                    <Target>  
                        <LocURI>./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/DiscoveryEndpoint</LocURI>  
                    </Target>  
             <Data>https://contoso.com/declaredconfigrationendpoint?api-version=1.0</Data>  
                </Item>  
            </Replace>  
            <Final/>  
        </SyncBody>  
    </SyncML>  
    <SyncML xmlns="SYNCML:SYNCML1.1">  
        <SyncBody>  
            <Exec>  
                <CmdID>2</CmdID>  
                <Item>  
                    <Target>  
                        <LocURI>./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/Enroll</LocURI>  
                    </Target>  
               </Item>  
            </Exec>  
            <Final/>  
        </SyncBody>  
 </SyncML>

ProviderID/PublisherDeviceID: (Only for phones). Optional. The PublisherDeviceID is a device-unique ID created based on the enterprise Publisher ID. Publisher ID is created based on the enterprise application token and enterprise ID via ./Vendor/MSFT/EnterpriseAppManagement/<enterprise id>/EnrollmentToken. It is to ensure that for one enterprise, each device has a unique ID associated with it. For the same device, if it has multiple enterprises' applications, each enterprise is identified differently. Supported operation is Get.

ProviderID/SignedEntDMID: Optional. The character string that contains the device ID. This node and the nodes CertRenewTimeStamp and SignedCertRenewStamp can be used by the mobile device management server to verify client identity in order to update the registration record after the device certificate is renewed. The device signs the EntDMID with the old client certificate during the certificate renewal process and saves the signature locally. Supported operation is Get.

ProviderID/CertRenewTimeStamp: Optional. The time in OMA DM standard time format. This node and the SignedCertRenewTimeStamp node are designed to reduce the risk of the certificate being used by another device. The device records the time that the new certificate was created. Supported operation is Get.

ProviderID/ManagementServiceAddress: Required. The character string that contains the device management server address. It can be updated during an OMA DM session by the management server to allow the server to load balance to another server in situations where too many devices are connected to the server.

The DMClient configuration service provider saves the address to the same location used by the w7 and DMS configuration service providers, to ensure that the management client has a single place to retrieve the current server address.

The initial value for this node is the same server address value that is bootstrapped via the w7 APPLICATION configuration service provider. Supported operations are Get and Replace.

This node supports multiple server addresses in the format <URL1><URL2><URL3><9>. If there is only a single URL, then the angle brackets are not required. This is supported for both desktop and mobile devices.

During a DM session, the device will use the first address on the list, and then process the list until a successful connection is achieved. The DM client caches the successfully connected server URL for the next session.

ProviderID/UPN: Optional. Allows the management server to update the user principal name (UPN) of the enrolled user. This is useful in scenarios where the user email address changes in the identity system, or in the scenario where the user enters an invalid UPN during enrollment, and fixes the UPN during federated authentication. The UPN is recorded and the UX displays the updated UPN. Supported operations are Delete, Get, and Replace.

ProviderID/HelpPhoneNumber: Optional. A character string value that contains the customized help phone number that the end user can use if they need help or support. Supported operations are Get, Replace, and Delete.

ProviderID/HelpWebsite: Optional. A character string value that contains the customized help website that the end user can use if they need help or support. Supported operations are Delete, Get, and Replace.

ProviderID/HelpEmailAddress: Optional. A character string value that contains the customized help email address that the end user can use if they need help or support. Supported operations are Get, Replace, and Delete.

ProviderID/RequireMessageSigning: Optional. Boolean type. Primarily used for SSL bridging mode where firewalls and proxies are deployed and where device client identity is required. When enabled, every SyncML message from the device will carry an additional HTTP header named MDM-Signature. This header contains Base64-encoded Cryptographic Message Syntax using a Detached Signature of the complete SyncML message SHA-2 (inclusive of the SyncHdr and SyncBody tags). Signing is performed using the private key of the management session certificate that was enrolled as part of the MDE2 enrollment process. The device's public key and PKCS9 UTC (Coordinated Universal Time) signing time stamp are included as part of the authenticated attributes in the signature. For more information on PKCS9 see [RFC2985].

The default value is false, where the device management client does not include authentication information in the management session HTTP header. Optionally set to true, where client authentication information is provided in the management session HTTP header.

When enabled, the MDM server validates the signature and the timestamp using the device identify certificate enrolled as part of MDE2, ensure the certificate and time are valid, and verify that the signature is trusted by the MDM server. Supported operations are Delete, Get, and Replace.

ProviderID/SyncApplicationVersion: Optional. Allows the management server to set the maximum current version of the management session protocol. A management server can update this if it detects a newer MaxSyncApplicationVersion that the client and server support. All changes to the MaxSyncApplicationVersion go into effect on the next session. Supported operations are Add and Get. Once this value is set to 2.0, it cannot be re-set to 1.0.

ProviderID/MaxSyncApplicationVersion: Optional. Returns a character string that is the highest supported management session protocol version supported by the current platform. Supported operation is Get.

ProviderID/AADResourceID: Optional. This is the ResourceID used when requesting the user token from the OMA DM session for Azure AD enrollments (AAD Join or Add Accounts). The token is audience specific, which allows for different service principals (enrollment vs. device management). It can be an application ID or the endpoint that you are trying to access.

ProviderID/EnableOmaDmKeepAliveMessage: A boolean value that specifies whether the DM client sends a request pending alert if the device client response to a DM request is too slow. By default, the MDM client does not send an alert that a DM request is pending.<10>

When the server sends a configuration request, sometimes it takes the client longer than the HTTP timeout to get all information together and then the session ends unexpectedly due to timeout

To work around the timeout, this setting can be used to keep the session alive by sending a heartbeat message back to the server. This is achieved by sending a SyncML message with a specific device alert element in the body until the client can respond back to the server with the requested information.

Here is an example of DM message sent by the device when it is in pending state.

 <SyncML xmlns="SYNCML:SYNCML1.2">
   <SyncHdr>
     <VerDTD>1.2</VerDTD>
       <VerProto>DM/1.2</VerProto>
       <SessionID>10</SessionID>
       <MsgID>2</MsgID>
     <Target>
       <LocURI>https://www.contoso.com/mgmt-server</LocURI>
     </Target>
     <Source>
       <LocURI>{unique device ID}</LocURI>
     </Source>
   </SyncHdr>
   <SyncBody>
 <Alert>
   <CmdID>2</CmdID>
   <Data>1224</Data> 
   <Item>
     <Meta>
       <Type xmlns="syncml:metinf">Reversed-Domain-Name:com.microsoft.mdm.requestpending</Type>
     </Meta>
     <Data>1</Data>
   </Item>
 </Alert>
   </SyncBody>
 </SyncML>

ProviderID/AADDeviceID: Returns the device ID for the Azure Active Directory device registration. Supported operation is Get.<11>

ProviderID/EnrollmentType: Returns the enrollment type (Device, Full, or AppManagement). Supported operation is Get.<12>

ProviderID/HWDevID: Returns the hardware device ID. Supported operation is Get.<13>

ProviderID/CommercialID: Configures the identifier used to uniquely associate this telemetry data of this device as belonging to a given organization. <14> If your organization is participating in a program that requires this device to be identified as belonging to your organization then use this setting to provide that identification. The value for this setting will be provided by Microsoft as part of the onboarding process for the program. If you disable or do not configure this policy setting, then Microsoft will not be able to use this identifier to associate this machine and its telemetry data with your organization. Supported operations are Add, Delete, Get, and Replace.

ProviderID/ManagementServerAddressList: The list of management server URLs in the format <URL1<URL2><URL3>, etc.<15> If there is only one, the angle brackets (<>) are not required. Not that the < and > should be escaped.

   <Replace>
     <CmdID>101</CmdID>
     <Item>
       <Target>
         <LocURI>
           ./Vendor/MSFT/DMClient/Provider/TestServer/ManagementServerAddressList
         </LocURI>
       </Target>
       <Data>&lt;https://server1&gt;&lt;https:// server2&gt; </Data>
     </Item>
   </Replace>

If ManagementServerAddressList node is set, the device will only use the server URL configured in this node.

When the server is not responding after a specified number of retries, the device tries to use the next server URL in the list until it gets a successful connection. After the server list is updated, the client uses the updated list at the next session starting with the first on in the list. Supported operations are Get and Replace. Value type is string.

ProviderID/Poll: Optional. Polling schedules MUST utilize the DMClient CSP, see [MSDOCS-DMClient-CSP]. Supported operations are Add and Get.

There are three schedules managed under the Poll node which enable a rich polling schedule experience to provide greater flexibility in managing the way in which devices poll the management server. There are a variety of ways in which polling schedules are set. If an invalid polling configuration is set, the device will correct or remove the schedules in order to restore the polling schedules back to a valid configuration.

If there is no infinite schedule set, then a 24-hour schedule is created and scheduled to launch in the maintenance window.

Valid poll schedule: sigmoid polling schedule with infinite schedule (Recommended)

Schedule name	Schedule set by the server	Actual value queried on device
IntervalForFirstSetOfRetries	15	15
NumberOfFirstRetries	5	5
IntervalForSecondSetOfRetries	60	60
NumberOfSecondRetries	10	10
IntervalForRemainingScheduledRetries	1440	1440
NumberOfRemainingScheduledRetries	0	0

Valid poll schedule: initial enrollment only [no infinite schedule]

Schedule name	Schedule set by the server	Actual value queried on device
IntervalForFirstSetOfRetries	15	15
NumberOfFirstRetries	5	5
IntervalForSecondSetOfRetries	60	60
NumberOfSecondRetries	10	10
IntervalForRemainingScheduledRetries	0	0
NumberOfRemainingScheduledRetries	0	0

Invalid poll schedule: disable all poll schedules

Note: Disabling poll schedules results in UNDEFINED behavior and enrollment MAY fail if poll schedules are all set to zero.

Schedule name	Schedule set by the server	Actual value queried on device
IntervalForFirstSetOfRetries	0	0
NumberOfFirstRetries	0	0
IntervalForSecondSetOfRetries	0	0
NumberOfSecondRetries	0	0
IntervalForRemainingScheduledRetries	0	0
NumberOfRemainingScheduledRetries	0	0

Invalid poll schedule: two infinite schedules

Schedule name	Schedule set by server	Actual schedule set on device	Actual experience
IntervalForFirstSetOfRetries	15	15	Device polls
NumberOfFirstRetries	5	5	Device polls
IntervalForSecondSetOfRetries	1440	1440	Device polls the server once in 24 hours
NumberOfSecondRetries	0	0	Device polls the server once in 24 hours
IntervalForRemainingScheduledRetries	1440	0	Third schedule is disabled
NumberOfRemainingScheduledRetries	0	0	Third schedule is disabled

If the device was previously enrolled in MDM with a polling schedule directly configured via registry key values the MDM server that supports using DMClient CSP to update polling schedule sends an Add command to add a ./Vendor/MSFT/DMClient/Enrollment/<ProviderID>/Poll node before it sends a Get or Replace command to query or update polling parameters via DMClient CSP. When using the DMClient CSP to configure polling schedule parameters, the server MUST NOT set all 6 polling parameters to 0 and MUST NOT set all 3 number of retries nodes to 0 because it will cause a configuration failure.

ProviderID/Poll/IntervalForFirstSetOfRetries: Optional. The waiting time (in minutes) for the initial set of retries as specified by the number of retries in <ProviderID>/Poll/NumberOfFirstRetries. If IntervalForFirstSetOfRetries is not set, then the default value is used. The default value is 15. If the value is set to 0, this schedule is disabled. The supported operations are Get and Replace.

ProviderID/Poll/NumberOfFirstRetries: Optional. The number of times the device management client can retry to connect to the server when the client is initially configured or enrolled to communicate with the server. If the value is set to 0 and the IntervalForFirstSetOfRetries value is not 0, then the schedule will be set to repeat an infinite number of times and second set will not set in this case. The default value is 10. The supported operations are Get and Replace.

The first set of retries is intended to give the management server some buffered time to be ready to send policies and settings configuration to the device. It is best practice to not have the first set of retries go beyond a few hours. The server MUST NOT set NumberOfFirstRetries to 0. RemainingScheduledRetries is used for the long run device polling schedule.

ProviderID/Poll/IntervalForSecondSetOfRetries: Optional. The waiting time (in minutes) for the second set of retries as specified by the number of retries in /<ProviderID>/Poll/NumberOfSecondRetries. Default value is 0. If this value is set to zero, then this schedule is disabled. The supported operations are Get and Replace.

ProviderID/Poll/NumberOfSecondRetries: Optional. The number of times the device management client can retry a second round of connecting to the server when the client is initially configured/enrolled to communicate with the server. Default value is 0. If the value is set to 0 and IntervalForSecondSetOfRetries is not set to 0 AND the first set of retries is not set as infinite retries, then the schedule repeats an infinite number of times. However, if the first set of retries is set at infinite, then this schedule is disabled. Supported operations are Get and Replace.

IntervalForSecondSetOfRetries SHOULD be longer than IntervalForFirstSetOfRetries. The total duration of retries can be more than 24 hours. RemainingScheduledRetries is used for the long run device polling schedule.

ProviderID/Poll/IntervalForRemainingScheduledRetries: Optional. The waiting time (in minutes) for the initial set of retries as specified by the number of retries in /<ProviderID>/Poll/NumberOfRemainingScheduledRetries. Default value is 0. If IntervalForRemainingScheduledRetries is set to 0, then this schedule is disabled. Supported operations are Get and Replace.

The IntervalForRemainingScheduledRetries replaces the deprecated HKLM\Software\Microsoft\Enrollment\OmaDmRetry\Aux2RetryInterval path that previously utilized the Registry CSP.

ProviderID/Poll/NumberOfRemainingScheduledRetries: Optional. The number of times the device management client can retry connecting to the server when the client is initially configured/enrolled to communicate with the server. Default value is 0. If the value is set to 0 and IntervalForRemainingScheduledRetries AND the first and second set of retries are not set as infinite retries, then the schedule will be set to repeat for an infinite number of times. However, if either or both of the first and second set of retries are set as infinite, then this schedule will be disabled. Supported operations are Get and Replace.

The NumberOfRemainingScheduledRetries replaces the deprecated HKLM\Software\Microsoft\Enrollment\OmaDmRetry\Aux2NumRetries path that previously utilized the Registry CSP.

RemainingScheduledRetries is used for the long run device polling schedule. IntervalForRemainingScheduledRetries MUST NOT be smaller than 1440 minutes (24 hours).

ProviderID/Poll/PollOnLogin: Optional. Allows the IT admin to require the device to start a management session on any user login, regardless of whether the user has previously logged in. Login is not the same as device unlock. Default value is false, where polling is disabled on first login. Supported values are true or false. Supported operations are Add, Get and Replace.

ProviderID/Poll/AllUsersPollOnFirstLogin: Optional. Allows the IT admin to require the device to start a management session on first user login for all NT users. A session is only kicked off the first time a user logs in to the system; subsequent logins will not trigger an MDM session. Login is not the same as device unlock. Default value is false, where polling is disabled on first login. Supported values are true or false. Supported operations are Add, Get and Replace.

ProviderID/Push: Optional. Not configurable during Wireless Application Protocol (WAP) Provisioning XML ([WBXML1.2]). If removed, DM sessions triggered by Push will no longer be supported. Supported operations are Add and Delete.

ProviderID/Push/PFN: Required. The Package Family Name (PFN) is a string used to register a device for push notifications. The server MUST use the same PFN as the devices it is managing. Supported operations are Add, Get, and Replace.

ProviderID/Push/ChannelURI: Required. A string that contains the channel that the Windows Notification Service (WNS) client has negotiated for the OMA DM client on the device based on the PFN that was provided. If no valid PFN is currently set, ChannelURI will return null. Supported operation is Get.

ProviderID/Push/Status: Required. An integer that maps to a known error state or condition on the system. The status error mapping is listed below. Supported operation is Get.

Status	Description
0	Success!
1	Failure: invalid PFN
2	Failure: invalid or expired device authentication with MSA (MS Account)
3	Failure: WNS client registration failed due to an invalid or revoked PFN
4	Failure: no Channel URI assigned
5	Failure: Channel URI has expired
6	Failure: Channel URI failed to be revoked
7	Failure: Push notification received, but unable to establish an OMA DM session due to power or connectivity limitations.
8	Push Not Available On the SKU

ProviderID/Unenroll: Required. The node accepts unenrollment requests by way of the OMA DM Exec command and calls the enrollment client to unenroll the device from the management server whose provider ID is specified in the <Data> tag under the <Item> element. Scope is permanent. Supported operations are Get and Exec.

Note: <LocURI>/Vendor/MSFT/DMClient/Unenroll</LocURI> is supported for backward compatibility.

The following SyncML shows how to remotely unenroll the device. Note that this command can be inserted in the general DM packages sent from the server to the device.

    <Exec>
      <CmdID>2</CmdID>
      <Item>
        <Target>
          <LocURI>./Vendor/MSFT/DMClient/Provider/<ProviderID>/TestMDMServer/Unenroll</LocURI>
        </Target>
          <Meta>
             <Format xmlns="syncml:metinf">chr</Format>
          </Meta>
          <Data>TestMDMServer</Data>
          <!-- Data Field in Threshold is now IGNORED node -->
      </Item>
    </Exec>

2.2.9.3 DMClient Configuration Service Provider

Additional resources