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

Merge branch 'main' into patch-8

Browse Source
This commit is contained in:
Kevin Sheehan
2024-09-25 12:50:56 -04:00
committed by GitHub
parent 09b9e439d4 502ecd2268
commit 21de3f0cd7
25 changed files with 1233 additions and 348 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
windows/client-management/mdm/declaredconfiguration-csp.md
View File

@ -1,7 +1,7 @@
---
title: DeclaredConfiguration CSP
description: Learn more about the DeclaredConfiguration CSP.
ms.date: 01/18/2024
ms.date: 09/12/2024
---
<!-- Auto-Generated CSP Document -->
@ -15,13 +15,13 @@ ms.date: 01/18/2024
<!-- Add any additional information about this policy here. Anything outside this section will get overwritten. -->
The primary MDM model is one where the MDM server is solely responsible for orchestration and continuous maintenance of the state of the device for configuration scenarios. This behavior results in intensive network traffic and high network latency due to the synchronous configuration model based on the OMA-DM Syncml standard. It's also error-prone given that the server needs deep knowledge of the client.
The declared configuration device management model requires the server to deliver all the setting values to the device for the scenario configuration. The server sends them asynchronously in batches through the client declared configuration CSP.
The Windows declared configuration (WinDC) device management model requires the server to deliver all the setting values to the device for the scenario configuration. The server sends them asynchronously in batches through the DeclaredConfiguration CSP.
- During the client-initiated OMA-DM session, the declared configuration server sends a configuration or an inventory declared configuration document to the client through the [Declared Configuration CSP URI](#declared-configuration-oma-uri). If the device verifies the syntax of the document is correct, the client stack pushes the request to its orchestrator to process the request asynchronously. The client stack then exits, and returns control back to the declared configuration service. This behavior allows the device to asynchronously process the request.
- During the client-initiated OMA-DM session, the WinDC server sends a configuration or an inventory WinDC document to the client through the [DeclaredConfiguration CSP URI](#declaredconfiguration-oma-uri). If the device verifies the syntax of the document is correct, the client stack pushes the request to its orchestrator to process the request asynchronously. The client stack then exits, and returns control back to the WinDC service. This behavior allows the device to asynchronously process the request.
- On the client, if there are any requests in process or completed, it sends a [generic alert](#declared-configuration-generic-alert) to the server. This alert summarizes each document's status, state, and progress. Every client HTTPS request to the declared configuration OMA-DM server includes this summary.
- On the client, if there are any requests in process or completed, it sends a [generic alert](#windc-generic-alert) to the server. This alert summarizes each document's status, state, and progress. Every client HTTPS request to the WinDC OMA-DM server includes this summary.
- The declared configuration server uses the generic alert to determine which requests are completed successfully or with errors. The server can then synchronously retrieve the declared configuration document process results through the [Declared Configuration CSP URI](#declared-configuration-oma-uri).
- The WinDC server uses the generic alert to determine which requests are completed successfully or with errors. The server can then synchronously retrieve the WinDC document process results through the [DeclaredConfiguration CSP URI](#declaredconfiguration-oma-uri).
<!-- DeclaredConfiguration-Editable-End -->
<!-- DeclaredConfiguration-Tree-Begin -->
@ -730,107 +730,51 @@ The Document node's value is an XML based document containing a collection of se
<!-- DeclaredConfiguration-CspMoreInfo-Begin -->
<!-- Add any additional information about this CSP here. Anything outside this section will get overwritten. -->
## Declared configuration OMA URI
## DeclaredConfiguration OMA URI
A declared configuration request is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/[Complete|Inventory]/Documents/{DocID}/Document`.
A WinDC request is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/[Complete|Inventory]/Documents/{DocID}/Document`.
- The URI is prefixed with a targeted scope. The target of the scenario settings can only be device wide for extensibility. The scope should be `Device`.
- The URI is prefixed with a targeted scope (`User` or `Device`).
- `{DocID}` is a unique identifier for the desired state of the configuration scenario. Every document must have an ID, which must be a GUID.
- The request can be a **Configuration**, **Inventory**, or **Complete** request.
- The request can be a **Inventory**, or **Complete** request.
The following URI is an example of a **Complete** request: `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document`
## DeclaredConfiguration document XML
The value of the leaf node `Document` is an XML document that describes the request. The actual processing of the request pivots around the `osdefinedscenario` tag:
- `MSFTExtensibilityMIProviderConfig`: Used to configure MI provider settings.
- `MSFTExtensibilityMIProviderInventory`: Used to retrieve MI provider setting values.
The DeclaredConfiguration CSP synchronously validates the batch of settings described by the `<DeclaredConfiguration>` element, which represents the declared configuration document. It checks for correct syntax based on the declared configuration XML schema. If there's a syntax error, the CSP returns an error immediately back to the server as part of the current OMA-DM session. If the syntax check passes, then the request is passed on to a Windows service. The Windows service asynchronously attempts the desired state configuration of the specified scenario. This process frees up the server to do other work thus the low latency of this declared configuration protocol. The Windows client service, the orchestrator, is responsible for driving the configuration of the device based on the server supplied desire state. The service also maintains this state throughout its lifetime, until the server removes or modifies it.
The following example uses the built-in, native MI provider `MSFT_FileDirectoryConfiguration` with the OS-defined scenario `MSFTExtensibilityMIProviderConfig`:
## WinDC document
```xml
<DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" osdefinedscenario="MSFTExtensibilityMIProviderConfig">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
<Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
<Value name="Contents">TestFileContentBlah</Value>
</DSC>
<DeclaredConfiguration
schema="1.0"
context="Device"
id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2"
checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999"
osdefinedscenario="MSFTExtensibilityMIProviderConfig">
... {Configuration Data} ...
</DeclaredConfiguration>
```
The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration CSP operations such as **Replace**, **Set**, and **Delete**. The payload of the SyncML's `<Data>` element must be XML-encoded. For this XML encoding, there are various online encoders that you can use. To avoid encoding the payload, you can use [CDATA Section](https://www.w3.org/TR/REC-xml/#sec-cdata-sect) as shown in the following example:
The `<DeclaredConfiguration>` XML tag specifies the details of the WinDC document to process. The document could be part of a configuration request or an inventory request. The DeclaredConfiguration CSP has two URIs to allow the specification of a [configuration](#hostcomplete) or an [inventory](#hostinventory) request.
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>14</CmdID>
<Item>
<Target>
<LocURI> ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/99988660-9080-3433-96e8-f32e85011999/Document</LocURI>
</Target>
<Data>
<![CDATA[<DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" osdefinedscenario="MSFTExtensibilityMIProviderConfig">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
<Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
<Value name="Contents">TestFileContentBlah</Value>
</DSC>
</DeclaredConfiguration>]]>
</Data>
</Item>
</Replace>
<Final/>
</SyncBody>
</SyncML>
```
This tag has the following attributes:
### DeclaredConfiguration XML document tags
| Attribute | Description |
|---------------------|----------------------------------------------------------------------------------------|
| `schema` | The schema version of the xml. Currently `1.0`. |
| `context` | States whether the document is targeting the device or user. |
| `id` | The unique identifier of the document set by the server. This value should be a GUID. |
| `checksum` | This value is the server-supplied version of the document. |
| `osdefinedscenario` | The named scenario that the client should configure with the given configuration data. |
Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInventory` are OS-defined scenarios that require the same tags and attributes.
The DeclaredConfiguration CSP synchronously validates the batch of settings described by the `<DeclaredConfiguration>` element, which represents the WinDC document. It checks for correct syntax based on the WinDC XML schema. If there's a syntax error, the CSP returns an error immediately back to the server as part of the current OMA-DM session. If the syntax check passes, then the request is passed on to a Windows service. The Windows service asynchronously attempts the desired state configuration of the specified scenario. This process frees up the server to do other work thus the low latency of the WinDC protocol. The Windows client service, the orchestrator, is responsible for driving the configuration of the device based on the server supplied desire state. The service also maintains this state throughout its lifetime, until the server removes or modifies it.
- The `<DeclaredConfiguration>` XML tag specifies the details of the declared configuration document to process. The document could be part of a configuration request or an inventory request. The DeclaredConfiguration CSP has two URIs to allow the specification of a configuration or an inventory request.
The actual processing of the request pivots around the `osdefinedscenario` tag and the configuration data specified within the document. For more information, see:
This tag has the following attributes:
- [WinDC document for resource access](../declared-configuration-resource-access.md#windc-document)
- [WinDC document for extensibility](../declared-configuration-extensibility.md#windc-document)
| Attribute | Description |
|--|--|
| `schema` | The schema version of the xml. Currently `1.0`. |
| `context` | States that this document is targeting the device. The value should be `Device`. |
| `id` | The unique identifier of the document set by the server. This value should be a GUID. |
| `checksum` | This value is the server-supplied version of the document. |
| `osdefinedscenario` | The named scenario that the client should configure with the given configuration data. For extensibility, the scenario is either `MSFTExtensibilityMIProviderConfig` or `MSFTExtensibilityMIProviderInventory`. |
## WinDC generic alert
- The `<DSC>` XML tag describes the targeted WMI provider expressed by a namespace and class name along with the values either to be applied to the device or queried by the MI provider.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `namespace` | Specifies the targeted MI provider namespace. |
| `classname` | The targeted MI provider. |
- The `<Key>` XML tag describes the required parameter name and value. It only needs a value for configuration. The name is an attribute and the value is `<Key>` content.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the name of an MI provider parameter. |
- The `<Value>` XML tag describes the optional parameter name and value. It only needs a value for configuration. The name is an attribute and the value is `<Value>` content.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the name of an MI provider parameter. |
## Declared configuration generic alert
On every client response to the server's request, the client constructs a declared configuration alert. This alert summarizes the state of each of the documents that the Windows service has processed. The following XML is an example alert:
On every client response to the server's request, the client constructs a WinDC alert. This alert summarizes the state of each of the documents that the Windows service has processed. The following XML is an example alert:
```xml
<Alert>
@ -853,9 +797,13 @@ On every client response to the server's request, the client constructs a declar
</Alert>
```
In this example, there's one declared configuration document listed in the alert summary. The alert summary lists every document that the client stack is processing, either a configuration or inventory request. It describes the context of the document that specifies the scope of how the document is applied. The **context** value should be `Device`.
In this example, there's one WinDC document listed in the alert summary. The alert summary lists every document that the client stack is processing, either a configuration or inventory request. It describes the context of the document that specifies the scope of how the document is applied. The **context** value should be `Device`.
The **state** attribute has a value of `60`, which indicates that the document was processed successfully. The following class defines the other state values:
The **state** attribute has a value of `60`, which indicates that the document was processed successfully.
## WinDC states
The following class defines the state values:
```csharp
enum class DCCSPURIState :unsigned long
@ -889,150 +837,83 @@ enum class DCCSPURIState :unsigned long
## SyncML examples
- Retrieve the results of a configuration or inventory request:
- [SyncML examples for resource access](../declared-configuration-resource-access.md#syncml-examples)
- [SyncML examples for extensibility](../declared-configuration-extensibility.md#syncml-examples)
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Get>
<CmdID>2</CmdID>
<Item>
<Meta>
<Format>chr</Format>
<Type>text/plain</Type>
</Meta>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
</Target>
</Item>
</Get>
<Final />
</SyncBody>
</SyncML>
```
### Abandon a WinDC document
```xml
<Status>
<CmdID>2</CmdID>
<MsgRef>1</MsgRef>
<CmdRef>2</CmdRef>
<Cmd>Get</Cmd>
<Data>200</Data>
</Status>
<Results>
<CmdID>3</CmdID>
<MsgRef>1</MsgRef>
<CmdRef>2</CmdRef>
<Item>
<Source>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
</Source>
<Data>
<DeclaredConfigurationResult context="Device" schema="1.0" id="99988660-9080-3433-96e8-f32e85011999" osdefinedscenario="MSFTPolicies" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" result_checksum="EE4F1636201B0D39F71654427E420E625B9459EED17ACCEEE1AC9B358F4283FD" operation="Set" state="60">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration" status="200" state="60">
<Key name="DestinationPath" />
<Value name="Contents" />
</DSC>
</DeclaredConfigurationResult>
</Data>
</Item>
</Results>
```
Abandoning a resource occurs when certain resources are no longer targeted to a user or group. Instead of deleting the resource on the device, the server can choose to abandon the WinDC document. An abandoned resource stays on the device but stops refreshing the WinDC document that handles drift control. Also the [resource ownership](../declared-configuration-resource-access.md#resource-ownership) is transferred to MDM, which means the same resource can be modified via legacy MDM channel again.
- Replace a configuration or inventory request
This example demonstrates how to abandon a WinDC document, by setting the **Abandoned** property to **1**.
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>14</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
</Target>
<Data>
<![CDATA[<DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99995209110918B67FE962460137AA3440AFF4DB6ABBE15C8F49968245799999" osdefinedscenario="MSFTExtensibilityMIProviderInventory">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
<Key name="DestinationPath">c:/temp/foobar.tmp</Key>
<Value name="Contents"></Value>
</DSC>
</DeclaredConfiguration>]]>
</Data>
</Item>
</Replace>
<Final />
</SyncBody>
</SyncML>
```
```xml
<Status>
<CmdID>2</CmdID>
<MsgRef>1</MsgRef>
<CmdRef>2</CmdRef>
<Cmd>Get</Cmd>
<Data>200</Data>
</Status><Results>
<CmdID>3</CmdID>
<MsgRef>1</MsgRef>
<CmdRef>2</CmdRef>
<Item>
<Source>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/99998660-9080-3433-96e8-f32e85019999/Document</LocURI>
</Source>
<Data>
<DeclaredConfigurationResult context="Device" schema="1.0" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" osdefinedscenario="MSFTExtensibilityMIProviderInventory" checksum="99995209110918B67FE962460137AA3440AFF4DB6ABBE15C8F49968245799999" result_checksum="A27B0D234CBC2FAC1292F1E8FBDF6A90690F3988DEDC9D716829856C9ACE0E20" operation="Get" state="80">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration" status="200" state="80">
<Key name="DestinationPath">c:/temp/foobar.tmp</Key>
<Value name="Contents">TestFileContent</Value>
</DSC>
</DeclaredConfigurationResult>
</Data>
</Item>
</Results>
```
- Abandon a configuration or inventory request. This process results in the client tracking the document but not reapplying it. The alert has the `Abandoned` property set to `1`, which indicates that the document is no longer managed by the declared configuration server.
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>2</CmdID>
<Item>
<Meta>
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>2</CmdID>
<Item>
<Meta>
<Format>int</Format>
<Type>text/plain</Type>
</Meta>
<Target>
</Meta>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Properties/Abandoned</LocURI>
</Target>
<Data>1</Data>
</Target>
<Data>1</Data>
</Item>
</Replace>
<Final/>
</SyncBody>
</SyncML>
```
### Unabandon a WinDC document
Unabandoning the document causes the document to be applied right away, transferring the [resource ownership](../declared-configuration-resource-access.md#resource-ownership) back to WinDC management and blocking legacy MDM channel from managing the channels again.
This example demonstrates how to unabandon a WinDC document, by setting the **Abandoned** property to **0**.
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>10</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned</LocURI>
</Target>
<Meta>
<Format xmlns="syncml:metinf">int</Format>
</Meta>
<Data>0</Data>
</Item>
</Replace>
<Final />
</SyncBody>
</SyncML>
```
### Delete a WinDC document
The SyncML deletion of the document only removes the document but any settings persist on the device. This example demonstrates how to delete a document.
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Delete>
<CmdID>2</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
</Target>
</Item>
</Replace>
</Delete>
<Final/>
</SyncBody>
</SyncML>
```
- Deletion of configuration or inventory request. The SyncML deletion of the document only removes the document but any extensibility settings persist on the device (tattoo).
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Delete>
<CmdID>2</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
</Target>
</Item>
</Delete>
<Final/>
</SyncBody>
</SyncML>
```
</SyncML>
```
<!-- DeclaredConfiguration-CspMoreInfo-End -->
<!-- DeclaredConfiguration-End -->

20
windows/client-management/mdm/toc.yml
View File

@ -27,7 +27,7 @@ items:
items:
- name: Using PowerShell scripting with the WMI Bridge Provider
href: ../using-powershell-scripting-with-the-wmi-bridge-provider.md
- name: WMI providers supported in Windows 10
- name: WMI providers supported in Windows
href: ../wmi-providers-supported-in-windows.md
- name: Understanding ADMX policies
href: ../understanding-admx-backed-policies.md
@ -43,11 +43,21 @@ items:
href: ../structure-of-oma-dm-provisioning-files.md
- name: Server requirements for OMA DM
href: ../server-requirements-windows-mdm.md
- name: Declared Configuration protocol
href: ../declared-configuration.md
- name: Declared Configuration
items:
- name: Declared Configuration extensibility
- name: Protocol
expanded: true
items:
- name: Overview
href: ../declared-configuration.md
- name: Discovery
href: ../declared-configuration-discovery.md
- name: Enrollment
href: ../declared-configuration-enrollment.md
- name: Extensibility
href: ../declared-configuration-extensibility.md
- name: Resource access
href: ../declared-configuration-resource-access.md
- name: DeclaredConfiguration CSP
href: declaredconfiguration-csp.md
- name: DMClient CSP
@ -377,7 +387,7 @@ items:
href: policy-csp-authentication.md
- name: Autoplay
href: policy-csp-autoplay.md
- name: Bitlocker
- name: BitLocker
href: policy-csp-bitlocker.md
- name: BITS
href: policy-csp-bits.md