deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-15 18:33:43 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Formatting

Browse Source
This commit is contained in:
Mandi Ohlinger
2021-11-16 14:50:50 -05:00
committed by GitHub
parent 85e675b07a
commit 54bbdfdd5e
1 changed files with 39 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
windows/client-management/mdm/oma-dm-protocol-support.md
View File

@ -17,20 +17,6 @@ ms.date: 06/26/2017
The OMA DM client communicates with the server over HTTPS and uses DM Sync (OMA DM v1.2) as the message payload. This topic describes the OMA DM functionality that the DM client supports in general. The full description of the OMA DM protocol v1.2 can be found at the [OMA website](https://www.openmobilealliance.org/release/DM/V1_2-20070209-A/OMA-TS-DM_Protocol-V1_2-20070209-A.pdf).
## In this topic
- [OMA DM standards](#oma-dm-standards)
- [OMA DM protocol common elements](#protocol-common-elements)
- [Device management session](#device-management-session)
- [User targeted vs. Device targeted configuration](#user-targeted-vs-device-targeted-configuration)
- [SyncML response codes](#syncml-response-codes)
## OMA DM standards
The following table shows the OMA DM standards that Windows uses.
@ -39,11 +25,11 @@ The following table shows the OMA DM standards that Windows uses.
|--- |--- |
|Data transport and session|<li>Client-initiated remote HTTPS DM session over SSL.<li>Remote HTTPS DM session over SSL.<li>Remote DM server initiation notification using WAP Push over Short Message Service (SMS). Not used by enterprise management.<li>Remote bootstrap by using WAP Push over SMS. Not used by enterprise management.|
|Bootstrap XML|OMA Client Provisioning XML.|
|DM protocol commands|The following list shows the commands that are used by the device. For more information about the OMA DM command elements, see "[OMA website](https://www.openmobilealliance.org/release/DM/V1_1_2-20031209-A/)" available from the OMA website.<li>Add (Implicit Add supported)<li>Alert (DM alert): Generic alert (1226) is used by enterprise management client when the user triggers an MDM unenrollment action from the device or when a CSP finishes some asynchronous actions. Device alert (1224) is used to notify the server some device triggered event.<li>Atomic: Performing an Add command followed by Replace on the same node within an atomic element is not supported. Nested Atomic and Get commands are not allowed and will generate error code 500.<li>Delete: Removes a node from the DM tree, and the entire subtree beneath that node if one exists<li>Exec: Invokes an executable on the client device<li>Get: Retrieves data from the client device; for interior nodes, the child node names in the Data element are returned in URI-encoded format<li>Replace: Overwrites data on the client device<li>Result: Returns the data results of a Get command to the DM server<li>Sequence: Specifies the order in which a group of commands must be processed<li>Status: Indicates the completion status (success or failure) of an operation<br>If an XML element that is not a valid OMA DM command is under one of the following elements, the status code 400 is returned for that element:<li>SyncBody<li>Atomic<li>Sequence<br>If no CmdID is provided in the DM command, the client returns blank in the status element and the status code 400.<br>If Atomic elements are nested, the following status codes are returned:<li>The nested Atomic command returns 500.<li>The parent Atomic command returns 507.<br>For more information about the Atomic command, see OMA DM protocol common elements.<br>Performing an Add command followed by Replace on the same node within an Atomic element is not supported.<br>LocURI cannot start with "/".<br>Meta XML tag in SyncHdr is ignored by the device.|
|DM protocol commands|The following list shows the commands that are used by the device. For more information about the OMA DM command elements, see "[OMA website](https://www.openmobilealliance.org/release/DM/V1_1_2-20031209-A/)" available from the OMA website.<br/><li>Add (Implicit Add supported)<li>Alert (DM alert): Generic alert (1226) is used by enterprise management client when the user triggers an MDM unenrollment action from the device or when a CSP finishes some asynchronous actions. Device alert (1224) is used to notify the server some device triggered event.<li>Atomic: Performing an Add command followed by Replace on the same node within an atomic element is not supported. Nested Atomic and Get commands are not allowed and will generate error code 500.<li>Delete: Removes a node from the DM tree, and the entire subtree beneath that node if one exists<li>Exec: Invokes an executable on the client device<li>Get: Retrieves data from the client device; for interior nodes, the child node names in the Data element are returned in URI-encoded format<li>Replace: Overwrites data on the client device<li>Result: Returns the data results of a Get command to the DM server<li>Sequence: Specifies the order in which a group of commands must be processed<li>Status: Indicates the completion status (success or failure) of an operation<br/><br/>If an XML element that is not a valid OMA DM command is under one of the following elements, the status code 400 is returned for that element:<br/><li>SyncBody<li>Atomic<li>Sequence<br><br/>If no CmdID is provided in the DM command, the client returns blank in the status element and the status code 400.<br/><br/>If Atomic elements are nested, the following status codes are returned:<br/><li>The nested Atomic command returns 500.<li>The parent Atomic command returns 507.<br/><br/>For more information about the Atomic command, see OMA DM protocol common elements.<br>Performing an Add command followed by Replace on the same node within an Atomic element is not supported.<br><br/>LocURI cannot start with `/`.<br/><br/>Meta XML tag in SyncHdr is ignored by the device.|
|OMA DM standard objects|DevInfo<li>DevDetail<li>OMA DM DMS account objects (OMA DM version 1.2)|
|Security|<li>Authenticate DM server initiation notification SMS message (not used by enterprise management)<li>Application layer Basic and MD5 client authentication<li>Authenticate server with MD5 credential at application level<li>Data integrity and authentication with HMAC at application level<li>SSL level certificate-based client/server authentication, encryption, and data integrity check|
|Nodes|In the OMA DM tree, the following rules apply for the node name:<li>"" can be part of the node name.<li>The node name cannot be empty.<li>The node name cannot be only the asterisk (*) character.|
|Provisioning Files|Provisioning XML must be well formed and follow the definition in SyncML Representation Protocol](https://go.microsoft.com/fwlink/p/?LinkId=526905).<br>If an XML element that is not a valid OMA DM command is under SyncBody, the status code 400 is returned for that element.<div class="alert">**Note**<br>To represent a Unicode string as a URI, first encode the string as UTF-8. Then encode each of the UTF-8 bytes using URI encoding.</div>|
|Nodes|In the OMA DM tree, the following rules apply for the node name:<br/><li>"." can be part of the node name.<li>The node name cannot be empty.<li>The node name cannot be only the asterisk (*) character.|
|Provisioning Files|Provisioning XML must be well formed and follow the definition in SyncML Representation Protocol](https://go.microsoft.com/fwlink/p/?LinkId=526905).<br/><br/>If an XML element that is not a valid OMA DM command is under SyncBody, the status code 400 is returned for that element.<div class="alert">**Note**<br>To represent a Unicode string as a URI, first encode the string as UTF-8. Then encode each of the UTF-8 bytes using URI encoding.</div>|
|WBXML support|Windows supports sending and receiving SyncML in both XML format and encoded WBXML format. This is configurable by using the DEFAULTENCODING node under the w7 APPLICATION characteristic during enrollment. For more information about WBXML encoding, see section 8 of the [SyncML Representation Protocol](https://go.microsoft.com/fwlink/p/?LinkId=526905) specification.|
|Handling of large objects|In Windows 10, version 1511, client support for uploading large objects to the server was added.|
@ -86,17 +72,25 @@ A DM session can be divided into two phases:
1. **Setup phase**: In response to a trigger event, a client device sends an initiating message to a DM server. The device and server exchange needed authentication and device information. This phase is represented by steps 1, 2, and 3 in the following table.
2. **Management phase**: The DM server is in control. It sends management commands to the device and the device responds. Phase two ends when the DM server stops sending commands and terminates the session. This phase is represented by steps 3, 4, and 5 in the following table.
The following table shows the sequence of events during a typical DM session.
The following information shows the sequence of events during a typical DM session.
|Step|Action|Description|
|--- |--- |--- |
|1|DM client is invoked to call back to the management server<br><br>Enterprise scenario – The device task schedule invokes the DM client.|The MO server sends a server trigger message to invoke the DM client.<br><br>The trigger message includes the server ID and tells the client device to initiate a session with the server. The client device authenticates the trigger message and verifies that the server is authorized to communicate with it.<br><br>Enterprise scenario - At the scheduled time, the DM client is invoked periodically to call back to the enterprise management server over HTTPS.|
|2|The device sends a message, over an IP connection, to initiate the session.|This message includes device information and credentials. The client and server do mutual authentication over an SSL channel or at the DM application level.|
|3|The DM server responds, over an IP connection (HTTPS).|The server sends initial device management commands, if any.|
|4|The device responds to server management commands.|This message includes the results of performing the specified device management operations.|
|5|The DM server terminates the session or sends another command.|The DM session ends, or Step 4 is repeated.|
1. DM client is invoked to call back to the management server<br><br>Enterprise scenario – The device task schedule invokes the DM client.
The step numbers in the table do not represent message identification numbers (MsgID). All messages from the server must have a MsgID that is unique within the session, starting at 1 for the first message, and increasing by an increment of 1 for each extra message. For more information about MsgID and OMA SyncML protocol, see "OMA Device Management Representation Protocol" (DM_RepPro-V1_2-20070209-A) available from the [OMA website](https://www.openmobilealliance.org/release/DM/V1_2-20070209-A/).
The MO server sends a server trigger message to invoke the DM client.
The trigger message includes the server ID and tells the client device to initiate a session with the server. The client device authenticates the trigger message and verifies that the server is authorized to communicate with it.<br><br>Enterprise scenario - At the scheduled time, the DM client is invoked periodically to call back to the enterprise management server over HTTPS.
2. The device sends a message, over an IP connection, to initiate the session.
This message includes device information and credentials. The client and server do mutual authentication over an SSL channel or at the DM application level.
3. The DM server responds, over an IP connection (HTTPS). The server sends initial device management commands, if any.
4. The device responds to server management commands. This message includes the results of performing the specified device management operations.
5. The DM server terminates the session or sends another command. The DM session ends, or Step 4 is repeated.
The step numbers don't represent message identification numbers (MsgID). All messages from the server must have a MsgID that is unique within the session, starting at 1 for the first message, and increasing by an increment of 1 for each extra message. For more information about MsgID and OMA SyncML protocol, see [OMA Device Management Representation Protocol (DM_RepPro-V1_2-20070209-A)](https://www.openmobilealliance.org/release/DM/V1_2-20070209-A/).
During OMA DM application level mutual authentication, if the device response code to Cred element in the server request is 212, no further authentication is needed for the remainder of the DM session. In the case of the MD5 authentication, the Chal element can be returned. Then the next nonce in Chal must be used for the MD5 digest when the next DM session is started.
@ -117,7 +111,7 @@ The data part of this alert could be one of following strings:
Below is an alert example:
```
```xml
<Alert>
<CmdID>1</CmdID>
<Data>1224</Data>
@ -143,37 +137,27 @@ The following LocURL shows a per device CSP node configuration: **./device/vendo
When using SyncML in OMA DM, there are standard response status codes that are returned. The following table lists the common SyncML response status codes you are likely to see. For more information about SyncML response status codes, see section 10 of the [SyncML Representation Protocol](https://openmobilealliance.org/release/Common/V1_2_2-20090724-A/OMA-TS-SyncML-RepPro-V1_2_2-20090724-A.pdf) specification.
| Status code | Description |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 200 | The SyncML command completed successfully. |
| 202 | Accepted for processing. This is usually an asynchronous operation, such as a request to run a remote execution of an application. |
| Status code | Description |
|---|----|
| 200 | The SyncML command completed successfully. |
| 202 | Accepted for processing. This is usually an asynchronous operation, such as a request to run a remote execution of an application. |
| 212 | Authentication accepted. Normally you'll only see this in response to the SyncHdr element (used for authentication in the OMA-DM standard). You may see this if you look at OMA DM logs, but CSPs do not typically generate this. |
| 214 | Operation canceled. The SyncML command completed successfully, but no more commands will be processed within the session. |
| 215 | Not executed. A command was not executed as a result of user interaction to cancel the command. |
| 216 | `Atomic` roll back OK. A command was inside an `Atomic` element and `Atomic` failed. This command was rolled back successfully. |
| 400 | Bad request. The requested command could not be performed because of malformed syntax. CSPs do not usually generate this error, however you might see it if your SyncML is malformed. |
| 401 | Invalid credentials. The requested command failed because the requestor must provide proper authentication. CSPs do not usually generate this error. |
| 403 | Forbidden. The requested command failed, but the recipient understood the requested command. |
| 404 | Not found. The requested target was not found. This code will be generated if you query a node that does not exist. |
| 405 | Command not allowed. This respond code will be generated if you try to write to a read-only node. |
| 406 | Optional feature not supported. This response code will be generated if you try to access a property that the CSP doesn't support. |
| 415 | Unsupported type or format. This response code can result from XML parsing or formatting errors. |
| 418 | Already exists. This response code occurs if you attempt to add a node that already exists. |
| 425 | Permission Denied. The requested command failed because the sender does not have adequate access control permissions (ACL) on the recipient. "Access denied" errors usually get translated to this response code. |
| 214 | Operation canceled. The SyncML command completed successfully, but no more commands will be processed within the session. |
| 215 | Not executed. A command was not executed as a result of user interaction to cancel the command. |
| 216 | `Atomic` roll back OK. A command was inside an `Atomic` element and `Atomic` failed. This command was rolled back successfully. |
| 400 | Bad request. The requested command could not be performed because of malformed syntax. CSPs do not usually generate this error, however you might see it if your SyncML is malformed. |
| 401 | Invalid credentials. The requested command failed because the requestor must provide proper authentication. CSPs do not usually generate this error. |
| 403 | Forbidden. The requested command failed, but the recipient understood the requested command. |
| 404 | Not found. The requested target was not found. This code will be generated if you query a node that does not exist. |
| 405 | Command not allowed. This respond code will be generated if you try to write to a read-only node. |
| 406 | Optional feature not supported. This response code will be generated if you try to access a property that the CSP doesn't support. |
| 415 | Unsupported type or format. This response code can result from XML parsing or formatting errors. |
| 418 | Already exists. This response code occurs if you attempt to add a node that already exists. |
| 425 | Permission Denied. The requested command failed because the sender does not have adequate access control permissions (ACL) on the recipient. "Access denied" errors usually get translated to this response code. |
| 500 | Command failed. Generic failure. The recipient encountered an unexpected condition which prevented it from fulfilling the request. This response code will occur when the SyncML DPU cannot map the originating error code. |
| 507 | `Atomic` failed. One of the operations in an `Atomic` block failed. |
| 516 | `Atomic` roll back failed. An `Atomic` operation failed and the command was not rolled back successfully. |
| 507 | `Atomic` failed. One of the operations in an `Atomic` block failed. |
| 516 | `Atomic` roll back failed. An `Atomic` operation failed and the command was not rolled back successfully. |
## Related topics
[Configuration service provider reference](configuration-service-provider-reference.md)