diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md new file mode 100644 index 00000000000..aabd1dd644c --- /dev/null +++ b/windows/client-management/declared-configuration-discovery.md @@ -0,0 +1,197 @@ +--- +title: Windows declared configuration discovery +description: Learn more about configuring discovery for Windows declared configuration enrollment. +ms.date: 09/12/2024 +ms.topic: how-to +--- + +# Declared configuration discovery + +Windows Declared configuration (WinDC) discovery uses a dedicated JSON schema to query enrollment details from the [discovery service endpoint (DS)](/openspecs/windows_protocols/ms-mde2/60deaa44-52df-4a47-a844-f5b42037f7d3#gt_8d76dac8-122a-452b-8c97-b25af916f19b). This process involves sending HTTP requests with specific headers and a JSON body containing details such as user domain, tenant ID, and OS version. The DS responds with the necessary enrollment service URLs and authentication policies based on the enrollment type (Microsoft Entra joined or registered devices). + +This article outlines the schema structure for the HTTP request and response bodies, and provides examples to guide the implementation. + +## Schema structure + +### HTTP request headers + +| Header | Required | Description | +|----------------------------------|----------|-----------------------------------| +| `MS-CV: %s` | No | Correlation vector for enrollment | +| `client-request-id: %s` | No | Request ID | +| `Content-Type: application/json` | Yes | HTTP Content-Type | + +### HTTP request body (JSON) + +| Field | Required | Description | +|--|--|--| +| `userDomain` | No | Domain name of the enrolled account | +| `upn` | No | User Principal Name (UPN) of the enrolled account | +| `tenantId` | No | Tenant ID of the enrolled account | +| `emmDeviceId` | No | Enterprise mobility management (EMM) device ID of the enrolled account | +| `enrollmentType` | Entra joined: No
Entra registered: Yes | Enrollment type of the enrolled account.

Supported Values:
- `Device`: Indicates the parent enrollment type is Entra joined (DS response should specify "AuthPolicy": "Federated").
- `User`: Indicates parent enrollment type is Entra registered (DS response should specify "AuthPolicy": "Certificate").
- Legacy case (Entra joined only): If the `enrollmentType` parameter isn't included in the request body, the device should be treated as Entra joined. | +| `osVersion` | Yes | OS version on the device. The DS can use the `osVersion` to determine if the client platform supports WinDC enrollment. Review [supported platforms](declared-configuration.md#supported-platforms) for details. | + +### HTTP DS response body (JSON) + +| Field | Required | Description | +|------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `EnrollmentServiceUrl` | Yes | URL of the WinDC enrollment service | +| `EnrollmentVersion` | No | Enrollment version | +| `EnrollmentPolicyServiceUrl` | Yes | Enrollment Policy Service URL | +| `AuthenticationServiceUrl` | Yes | Authentication Service URL | +| `ManagementResource` | No | Management Resource | +| `TouUrl` | No | Terms of use URL | +| `AuthPolicy` | Yes | Authentication policy. Supported values:
- `Federated` (required for Entra joined)
- `Certificate` (required for Entra registered) | +| `errorCode` | No | Error code | +| `message` | No | Status message | + +## Examples + +### Discovery request + +**Headers** + +`Content-Type: application/json` + +**Body** + +1. Single template approach: Client sends the **UPN** value in the initial request, along with the **tenantId** parameter. + + 1. Microsoft Entra joined: + + ```json + { + "userDomain" : "contoso.com", + "upn" : "johndoe@contoso.com", + "tenantId" : "00000000-0000-0000-0000-000000000000", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "Device", + "osVersion" : "10.0.00000.0" + } + ``` + + 1. Microsoft Entra registered: + + ```json + { + + "userDomain" : "contoso.com", + "upn" : "johndoe@contoso.com", + "tenantId" : "00000000-0000-0000-0000-000000000000", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "Device", + "osVersion" : "10.0.00000.0" + } + ``` + +1. No UPN (legacy) + + 1. Microsoft Entra joined: + + ```json + { + "userDomain" : "contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "Device", + "osVersion" : "10.0.00000.0" + } + ``` + + 1. Microsoft Entra registered: + + ```json + { + "userDomain" : "contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "User", + "osVersion" : "10.0.00000.0" + } + ``` + +1. UPN requested by the server (legacy format). Review [error handling](#error-handling) for details on how the server can request UPN data if it isn't provided in the initial request. + + 1. Microsoft Entra joined: + + ```json + { + "upn" : "johndoe@contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "Device", + "osVersion" : "10.0.00000.0" + } + ``` + + 1. Microsoft Entra registered: + + ```json + { + "upn" : "johndoe@contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "User", + "osVersion" : "10.0.00000.0" + } + ``` + +### Discovery response + +**Headers** + +`Content-Type: application/json` + +**Body** + +1. Microsoft Entra joined (requires `"AuthPolicy": "Federated"`): + + ```json + { + "EnrollmentServiceUrl" : "https://manage.contoso.com/Enrollment/Discovery", + "EnrollmentPolicyServiceUrl" : "https://manage.contoso.com/Enrollment/GetPolicies", + "AuthenticationServiceUrl" : "https://manage.contoso.com/Enrollment/AuthService", + "AuthPolicy" : "Federated", + "ManagementResource":"https://manage.contoso.com", + "TouUrl" : "https://manage.contoso.com/Enrollment/tou.aspx" + } + ``` + +1. Microsoft Entra registered (requires `"AuthPolicy": "Certificate"`): + + ```json + { + "EnrollmentServiceUrl" : "https://manage.contoso.com/Enrollment/Discovery", + "EnrollmentPolicyServiceUrl" : "https://manage.contoso.com/Enrollment/GetPolicies", + "AuthenticationServiceUrl" : "https://manage.contoso.com/Enrollment/AuthService", + "AuthPolicy" : "Certificate", + "ManagementResource":"https://manage.contoso.com", + "TouUrl" : "https://manage.contoso.com/Enrollment/tou.aspx" + } + ``` + +### Authentication + +WinDC enrollment requires different authentication mechanisms for Microsoft Entra joined and registered devices. The WinDC DS must integrate with the authentication model by specifying the appropriate `AuthPolicy` value in the discovery response, based on the `enrollmentType` property of the request. + +- **Microsoft Entra joined devices** use **Federated** authentication (Entra device token). +- **Microsoft Entra registered devices** use **Certificate** authentication (MDM certificate provisioned for the parent enrollment). + +#### Rules + +- **For Microsoft Entra joined devices**: + - **Discovery request**: `"enrollmentType": "Device"` + - **Discovery response**: `"AuthPolicy": "Federated"` + - **Authentication**: The client uses the Entra device token to authenticate with the WinDC enrollment server. + +- **For legacy cases (where `enrollmentType` value is empty)**: + - **Discovery request**: `"enrollmentType": ""` + - **Discovery response**: `"AuthPolicy": "Federated"` + - **Authentication**: The client uses the Entra device token to authenticate with the WinDC enrollment server. + +- **For Microsoft Entra registered devices**: + - **Discovery request**: `"enrollmentType": "User"` + - **Discovery response**: `"AuthPolicy": "Certificate"` + - **Authentication**: The client uses the MDM certificate from the parent enrollment to authenticate with the WinDC enrollment server. + +## Error handling + +- **UPNRequired**: If no UPN value is provided in the discovery request, the DS can set the `errorCode` to **UPNRequired** in the response to trigger the client to retry the request with a UPN value, if available. +- **WINHTTP_QUERY_RETRY_AFTER**: The server can set this flag to configure the client request to retry after a specified delay. This flag is useful for handling timeout or throttling scenarios. \ No newline at end of file diff --git a/windows/client-management/declared-configuration-enrollment.md b/windows/client-management/declared-configuration-enrollment.md new file mode 100644 index 00000000000..45ba4643d23 --- /dev/null +++ b/windows/client-management/declared-configuration-enrollment.md @@ -0,0 +1,51 @@ +--- +title: Windows declared configuration enrollment +description: Learn more about configuring enrollment for Windows declared configuration protocol. +ms.date: 09/12/2024 +ms.topic: how-to +--- + +# Declared configuration enrollment + +Windows declared configuration (WinDC) enrollment uses new [DMClient CSP](mdm/dmclient-csp.md) policies to facilitate dual enrollment for Windows devices. This process involves setting specific configuration service provider (CSP) policies and executing SyncML commands to manage the enrollment state. + +The key CSP policies used for WinDC enrollment include: + +- [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll) +- [LinkedEnrollment/Unenroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentunenroll) +- [LinkedEnrollment/EnrollStatus](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenrollstatus) +- [LinkedEnrollment/LastError](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentlasterror) +- [LinkedEnrollment/DiscoveryEndpoint](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentdiscoveryendpoint) + +The following SyncML example sets **LinkedEnrolment/DiscoveryEndpoint** and triggers **LinkedEnrollment/Enroll**: + +```xml + + + + 2 + + + ./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/DiscoveryEndpoint + + https://discovery.dm.microsoft.com/EnrollmentConfiguration?api-version=1.0 + + + + + + + + + + 2 + + + ./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/Enroll + + + + + + +``` diff --git a/windows/client-management/declared-configuration-extensibility.md b/windows/client-management/declared-configuration-extensibility.md index 7b1f9991f82..bb2faea5f1d 100644 --- a/windows/client-management/declared-configuration-extensibility.md +++ b/windows/client-management/declared-configuration-extensibility.md @@ -1,13 +1,13 @@ --- -title: Declared configuration extensibility -description: Learn more about declared configuration extensibility through native WMI providers. -ms.date: 07/08/2024 +title: Windows declared configuration extensibility +description: Learn more about Windows declared configuration extensibility through native WMI providers. +ms.date: 09/12/2024 ms.topic: how-to --- -# Declared configuration extensibility providers +# Declared configuration extensibility -The declared configuration enrollment, which supports the declared configuration client stack, offers extensibility through native WMI providers. This feature instantiates and interfaces with a Windows Management Instrumentation (WMI) provider that implements a management infrastructure (MI) interface. The interface must implement GetTargetResource, TestTargetResource, and SetTargetResource methods, and can implement any number of string properties. +The Windows declared configuration (WinDC) enrollment offers extensibility through native WMI providers. This feature instantiates and interfaces with a Windows Management Instrumentation (WMI) provider that implements a management infrastructure (MI) interface. The interface must implement GetTargetResource, TestTargetResource, and SetTargetResource methods, and can implement any number of string properties. > [!NOTE] > Only string properties are currently supported by extensibility providers. @@ -58,7 +58,7 @@ To create a native WMI provider, follow the steps outlined in [How to implement 5. Copy the generated files into the provider's project folder. 6. Start the development process. -## Example +## Example MI provider This example provides more details about each step to demonstrate how to implement a sample native resource named `MSFT_FileDirectoryConfiguration`. @@ -235,15 +235,180 @@ The `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource` function does the 1. Clean up resources, for example, free allocated memory. +## WinDC document + +> [!IMPORTANT] +> The target of the scenario settings can only be device wide for extensibility. The CSP **scope** defined in `` and WinDC **context** must be `Device`. + +The value of the `Document` leaf node in the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md) is an XML document that describes the request. Here's a sample WinDC document with the configuration data specified for extensibility. + +```xml + + + c:\data\test\bin\ut_extensibility.tmp + TestFileContent1 + + +``` + +Only supported values for `osdefinedscenario` can be used. Unsupported values result in an error message similar to `Invalid scenario name`. + +| osdefinedscenario | Description | +|--------------------------------------|----------------------------------------------| +| MSFTExtensibilityMIProviderConfig | Used to configure MI provider settings. | +| MSFTExtensibilityMIProviderInventory | Used to retrieve MI provider setting values. | + +Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInventory` scenarios that require the same tags and attributes. + +- The `` 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 `` 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 `` content. + + This tag has the following attributes: + + | Attribute | Description | + |--|--| + | `name` | Specifies the name of an MI provider parameter. | + +- The `` 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 `` content. + + This tag has the following attributes: + + | Attribute | Description | + |--|--| + | `name` | Specifies the name of an MI provider parameter. | + +## SyncML examples + +The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration CSP operations such as **Replace**, **Add**, and **Delete**. The payload of the SyncML's `` 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 SyncML examples. + +### Configuration request + +This example demonstrates how to send a configuration request using the `MSFT_FileDirectoryConfiguration` MI provider with the `MSFTExtensibilityMIProviderConfig` scenario. + +```xml + + + + + 14 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document + + + + c:\data\test\bin\ut_extensibility.tmp + TestFileContent1 + + + ]]> + + + + +``` + +### Inventory request + +This example demonstrates how to send an inventory request using the MSFT_FileDirectoryConfiguration MI provider with the MSFTExtensibilityMIProviderInventory scenario. + +```xml + + + + + 15 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/12345678-1234-1234-1234-123456789012/Document + + + + c:\data\test\bin\ut_extensibility.tmp + + + ]]> + + + + +``` + +### Retrieve results + +This example retrieves the results of a configuration or inventory request: + +**Request**: + +```xml + + + + 2 + + + chr + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document + + + + + + +``` + +**Response**: + +```xml + + 2 + 1 + 2 + Get + 200 + + + 3 + 1 + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document + + + + + + + + + + + +``` + ## MI implementation references -- [Introducing the management infrastructure (MI) API](/archive/blogs/wmi/introducing-new-management-infrastructure-mi-api) -- [Implementing MI provider (1) - Overview](/archive/blogs/wmi/implementing-mi-provider-1-overview) -- [Implementing MI provider (2) - Define schema](/archive/blogs/wmi/implementing-mi-provider-2-define-schema) -- [Implementing MI provider (3) - Generate code](/archive/blogs/wmi/implementing-mi-provider-3-generate-code) -- [Implementing MI provider (4) - Generate code (continue)](/archive/blogs/wmi/implementing-mi-provider-4-generate-code-continute) -- [Implementing MI provider (5) - Implement](/archive/blogs/wmi/implementing-mi-provider-5-implement) -- [Implementing MI provider (6) - Build, register, and debug](/archive/blogs/wmi/implementing-mi-provider-6-build-register-and-debug) +- [Management infrastructure (MI) API](/archive/blogs/wmi/introducing-new-management-infrastructure-mi-api) +- [MI provider (1) - Overview](/archive/blogs/wmi/implementing-mi-provider-1-overview) +- [MI provider (2) - Define schema](/archive/blogs/wmi/implementing-mi-provider-2-define-schema) +- [MI provider (3) - Generate code](/archive/blogs/wmi/implementing-mi-provider-3-generate-code) +- [MI provider (4) - Generate code (continue)](/archive/blogs/wmi/implementing-mi-provider-4-generate-code-continute) +- [MI provider (5) - Implement](/archive/blogs/wmi/implementing-mi-provider-5-implement) +- [MI provider (6) - Build, register, and debug](/archive/blogs/wmi/implementing-mi-provider-6-build-register-and-debug) - [MI interfaces](/previous-versions/windows/desktop/wmi_v2/mi-interfaces) - [MI datatypes](/previous-versions/windows/desktop/wmi_v2/mi-datatypes) - [MI structures and unions](/previous-versions/windows/desktop/wmi_v2/mi-structures-and-unions) diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md new file mode 100644 index 00000000000..d414e05b958 --- /dev/null +++ b/windows/client-management/declared-configuration-resource-access.md @@ -0,0 +1,463 @@ +--- +title: Windows declared configuration resource access +description: Learn more about configuring resource access using Windows declared Configuration. +ms.date: 09/12/2024 +ms.topic: how-to +--- + +# Declared configuration resource access + +Windows declared configuration (WinDC) resource access is used to manage device configurations and enforce policies to ensure the devices remain in a desired state. It's crucial for maintaining security, compliance, and operational efficiency in organizations. WinDC cloud service is used to send the desired state of a resource to the device where correspondingly the device has the responsibility to enforce and maintain the resource configuration state. + +[Configuration Service Providers (CSPs)](mdm/index.yml) play a vital role for configuring Resource access and act as an interface between the device and the WinDC protocol. They provide a consistent and standardized approach to deploying and enforcing configurations. CSPs support various resource access scenarios, including: + +- [VPNv2 CSP](mdm/vpnv2-csp.md) and [VPN CSP](mdm/vpn-csp.md) +- [Wi-Fi CSP](mdm/wifi-csp.md) +- [ClientCertificateInstall CSP](mdm/clientcertificateinstall-csp.md) +- [ActiveSync CSP](mdm/activesync-csp.md) +- [WiredNetwork CSP](mdm/wirednetwork-csp.md) +- [RootCACertificates CSP](mdm/rootcacertificates-csp.md) + +The WinDC stack on the device processes configuration requests and maintains the desired state, which is key to RA. The efficiency, accuracy, and enforcement of configuration requests are critical for effective RA. Resource access integrates seamlessly with WinDC, providing an extended method for managing devices through the cloud with enhanced scalability and efficiency. + +- **Efficiency**: Batch-based processing minimizes server resource usage and reduces latency. +- **Accuracy**: WinDC client stack understands the device's configuration surface area, enabling effective handling of continuous updates. It ensures precise execution of configuration changes communicated by the cloud service. +- **Policy Enforcement**: Apply and maintain organizational policies across devices consistently and at scale, ensuring compliance and uniform configuration. This aspect allows organizations to maintain the desired security posture across devices. + +## Resource access guidelines + +These guidelines provide best practices and examples for developers and testers to implement resource access (RA) configurations in a secure, efficient, and consistent manner. They aim to enhance network security and optimize resource access for end users while adhering to policies and compliance requirements. + +- **Configuration Integrity**: To support uninterrupted and secure resource access, ensure consistent configurations across devices and users. +- **State Validation**: Monitor the state of configurations to verify the correct application of resource access settings. +- **Profile Management**: Effectively manage user profiles by adding, updating, and deleting as needed, to control access to resources and maintain security. +- **Log and Audit**: Utilize logs and audit trails for operations and changes to aid in troubleshooting and compliance. +- **Drift Detection and Remediation**: To maintain compliance with RA policies, continuously monitor drift (changes in configuration or behavior) and take corrective action. +- **Security and Privacy**: To protect user data and resources, implement strong security and privacy measures in configurations. + +By following these guidelines and understanding the syntax of the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md), you can effectively implement and manage RA configurations while maintaining security and compliance. + +## WinDC document + +The value of the `Document` leaf node in the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md) is an XML document that describes the request. Here's a sample WinDC document with the configuration data specified for resource access. + +```xml + + + 2 + outbound + + +``` + +Only supported values for `osdefinedscenario` can be used. Unsupported values result in an error message similar to `Invalid scenario name`. + +| osdefinedscenario | Recommended using with | +|------------------------------|-------------------------------| +| MSFTWiredNetwork | WiredNetwork | +| MSFTResource | ActiveSync | +| MSFTVPN | VPN and VPNv2 | +| MSFTWifi | Wifi | +| MSFTInventory | Certificate inventory | +| MSFTClientCertificateInstall | SCEP, PFX, Bulk Template Data | + +These `osdefinedscenario` values require the following tags and attributes. + +- The `` XML tag describes the CSP being targeted. + + This tag has the following attributes: + + | Attribute | Description | + |--|--| + | `name` | Specifies the targeted CSP OMA-URI. | + +- The `` XML tag specifies the CSP setting node along with the desired value. + + This tag has the following attributes: + + | Attribute | Description | + |-----------|-------------------| + | `path` | Setting path | + | `type` | Setting data type | + +> [!NOTE] +> The target of the scenario settings must match the WinDC context. The CSP **scope** defined in `` and WinDC **context** must both be either `Device` or `User`. +> +> :::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="WinDC resource access syntax"::: + +### osdefinedscenario examples + +- Partial `MSFTWifi` example for Wifi: + + ```xml + + + ``` + +- Partial `MSFTResource` example for ActiveSync: + + ```xml + + + ``` + +## SyncML examples + +The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration CSP operations such as **Replace**, **Add**, and **Delete**. The payload of the SyncML's `` 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 SyncML examples. + +### Configure a VPNv2 profile for resource access + +This example demonstrates how to use the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile named **Test_SonicWall** on the device in the **User** scope. + +```xml + + + + 2 + + + chr + text/plain + + + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + 2 + outbound + 6 + 43-54 + 243-456 + outbound + wip.contoso.com + true + true + https://auto.proxy.com + true + false + 23.54.3.6;server1,vpn.contoso.com;server2 + <custom></custom> + SonicWALL.MobileConnect_e5kpm93dbe93j + + + ]]> + + + + + +``` + + + +### Updating a VPNv2 profile for resource access + +This example demonstrates how to use the same WinDC **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile. + +```xml + + + + 2 + + + chr + text/plain + + + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + 2 + outbound + wip.contoso.com + true + false + https://auto.proxy.com + true + false + 23.54.3.8;server1,vpn2.contoso.com;server2 + SonicWALL.MobileConnect_e5kpm93dbe93j + + + ]]> + + + + + +``` + +### Getting the VPNv2 profile + +This example demonstrates how to use `` to retrieve the results of the WinDC request. + +```xml + + + + + 1 + + + chr + text/plain + + + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + + +``` + +**Response**: + +```xml + + + + + 1 + 1 + 0 + SyncHdr + 200 + + + 2 + 1 + 2 + Get + 200 + + + 3 + 1 + 2 + + + ./User/Vendor/MSFT/DeclaredConfiguration/Host/BulkTemplate/Results/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + <DeclaredConfigurationResult context="user" schema="1.0" id="DCA000B5-397D-40A1-AABF-40B25078A7F9" osdefinedscenario="MSFTVPN" checksum="A3" result_checksum="9D2ED497C12D2FCEE1C45158D1F7ED8E2DACE210A0B8197A305417882991C978" result_timestamp="2024-08-06T13:54:38Z" operation="Set" state="60"><CSP name="./Vendor/MSFT/VPNv2" state="60"><URI path="Test_SonicWallNew/TrafficFilterList/0/Protocol" status="200" state="60" type="int" /><URI path="Test_SonicWallNew/TrafficFilterList/0/Direction" status="200" state="60" type="chr" /><URI path="Test_SonicWallNew/EdpModeId" status="200" state="60" type="chr" /><URI path="Test_SonicWallNew/RememberCredentials" status="200" state="60" type="bool" /><URI path="Test_SonicWallNew/AlwaysOn" status="200" state="60" type="bool" /><URI path="Test_SonicWallNew/Proxy/AutoConfigUrl" status="200" state="60" type="chr" /><URI path="Test_SonicWallNew/DeviceCompliance/Enabled" status="200" state="60" type="bool" /><URI path="Test_SonicWallNew/DeviceCompliance/Sso/Enabled" status="200" state="60" type="bool" /><URI path="Test_SonicWallNew/PluginProfile/ServerUrlList" status="200" state="60" type="chr" /><URI path="Test_SonicWallNew/PluginProfile/PluginPackageFamilyName" status="200" state="60" type="chr" /></CSP></DeclaredConfigurationResult> + + + + + +``` + +> [!TIP] +> To understand the state values, see [WinDC states](mdm/declaredconfiguration-csp.md#windc-states). + +### Deleting the VPNv2 profile + +This example demonstrates how to use `` to remove the configuration request to set the VPNv2 profile. + +```xml + + + + + 1 + + + chr + text/plain + + + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + + +``` + +## Resource ownership + +MDM-managed resources, such as a VPN profile, are transferred/migrated to WinDC management when a WinDC document is sent to the device for the same resource. This resource stays under WinDC management until the WinDC document is [deleted](mdm/declaredconfiguration-csp.md#delete-a-windc-document) or [abandoned](mdm/declaredconfiguration-csp.md#abandon-a-windc-document). Otherwise, when MDM tries to manage the same resource via the legacy MDM channel using SyncML, it fails with error 0x86000031. + +`MDM ConfigurationManager: Command failure status. Configuraton Source ID: (29c383c5-6e2d-43bf-a741-c63cb7516bb4), Enrollment Type: (MDMDeviceWithAAD), CSP Name: (ActiveSync), Command Type: (Add: from Replace or Add), CSP URI: (./User/Vendor/MSFT/ActiveSync/Accounts/{3b8b9d4d-a24e-4c6d-a460-034d0bfb9316}), Result: (Unknown Win32 Error code: 0x86000031).` + +## Bulk template data + +The Bulk template data scenario extends beyond the regular [ClientCertificateInstall CSP](mdm/clientcertificateinstall-csp.md). It uses a special bulk template document type. This section covers the structure, specification, and results of using the bulk template data. + +### Template document + +A PFXImport template document contains the structure necessary for importing certificates in bulk. The document should define the necessary fields, and the format required for the bulk import. + +- The document type must be `BulkTemplate`. +- The URI path is different than the regular URIs by using the `@#pfxThumbprint#` syntax, it declares that it's a dynamic node. [Instance data](#template-data) for dynamic nodes is sent later using `BulkVariables`. Each dynamic node might contain dynamic subnodes, such as the `@#pfxBlob#` and `#@pfxPassword#` nodes in this example. + +```xml + + + + + 2 + + + chr + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/BulkTemplate/Documents/47e88660-1861-4131-96e8-f32e85011e55/Document + + + + + foovalue + barvalue + + + 2 + @#pfxBlob# + @#pfxPassword# + True + 0 + SomeValue + + + + ]]> + + + + + +``` + +### Template data + +The bulk template data specifies the certificates to be imported in a base64 encoded format using the `BulkVariables` URI under the `BulkTemplate`. The template data document can contain multiple instances. Each instance must specify all the subinstance data. + +In this example, there are two instances. Each instance defines values for **pfxThumbprint**, a **pfxBlob, and a **pfxPassword**. + +```xml + + + + + 3 + + + chr + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/BulkTemplate/Documents/47e88660-1861-4131-96e8-f32e85011e55/BulkVariables/Value + + + + 813A171D7341E1DA90D4A01878DD5328D3519006 + pfxbase64BlobValue1 + Password1 + + + 813A171D7341E1DA90D4A01878DD5328D3519007 + pfxbase64BlobValue2 + Password2 + + + ]]> + + + + + +``` + +### Template results + +When the bulk template data document is successfully processed, the specified certificates are imported into the defined stores with the provided passwords and key locations. + +- Successful Import: The certificates are correctly imported into the device's certificate stores. +- Error Handling: Any errors encountered during the import process include relevant status codes or messages for troubleshooting. + +**Request**: + +```xml + + + + + 2 + + + chr + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/BulkTemplate/Results/47e88660-1861-4131-96e8-f32e85011e55/Document + + + + + + +``` + +**Response**: + +```xml + + + + + 1 + 1 + 0 + SyncHdr + 200 + + + 2 + 1 + 2 + Get + 200 + + + 3 + 1 + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/BulkTemplate/Results/47e88660-1861-4131-96e8-f32e85011e55/Document + + <DeclaredConfigurationResult context="Device" schema="1.0" id="47e88660-1861-4131-96e8-f32e85011e55" osdefinedscenario="MSFTResource" checksum="FF356C2C71F6A41F9AB4A601AD00C8B5BC7531576233010B13A221A9FE1BE7A0" result_checksum="DD8C1C422D50A410C2949BA5F495C2C42CC4B0C7B498D1B43318C503F6CEF491" result_timestamp="2024-08-06T13:26:23Z" operation="Set" state="60"> + <CSP name="./Vendor/MSFT/ClientCertificateInstall" state="60"> + <URI path="PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D3519006/KeyLocation" status="200" state="60" type="int" /> + <URI path="PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D3519006/PFXCertBlob" status="200" state="60" type="chr" /> + <URI path="PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D3519006/PFXCertPassword" status="200" state="60" type="chr" /> + <URI path="PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D3519006/PFXKeyExportable" status="200" state="60" type="bool" /> + </CSP><CSP name="./Vendor/MSFT/ClientCertificateInstall" state="60"> + <URI path="PFXCertInstall/CertPFX1/KeyLocation" status="200" state="60" type="int" /> + <URI path="PFXCertInstall/CertPFX1/PFXCertBlob" status="200" state="60" type="chr" /> + <URI path="PFXCertInstall/CertPFX1/PFXCertPassword" status="200" state="60" type="chr" /> + <URI path="PFXCertInstall/CertPFX1/PFXKeyExportable" status="200" state="60" type="bool" /> + </CSP> + </DeclaredConfigurationResult> + + + + + + +``` diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index e12a89b7cae..a0a28f91ae1 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -1,65 +1,132 @@ --- -title: Declared configuration protocol -description: Learn more about using declared configuration protocol for desired state management of Windows devices. -ms.date: 07/08/2024 +title: Windows declared configuration protocol +description: Learn more about using Windows declared configuration (WinDC) protocol for desired state management of Windows devices. +ms.date: 09/12/2024 ms.topic: overview --- -# What is the declared configuration protocol +# Windows declared configuration protocol overview -The declared configuration protocol is based on a desired state device configuration model, though it still uses the underlying OMA-DM Syncml protocol. Through a dedicated OMA-DM server, it provides all the settings in a single batch through this protocol. The device's declared configuration client stack can reason over the settings to achieve the desired scenario in the most efficient and reliable manner. +The Windows declared configuration (WinDC) protocol is a desired state device configuration model designed for efficient and reliable management of Windows devices. It uses the OMA-DM SyncML protocol to provide all necessary settings in a single batch through a dedicated OMA-DM server. The WinDC client stack on the device processes these settings to achieve the desired state in the most efficient and reliable manner. -The declared configuration protocol requires that a device has a separate [OMA-DM enrollment](mdm-overview.md), which is dependent on the device being enrolled with the primary OMA-DM server. The desired state model is a different model from the current model where the server is responsible for the device's desire state. This dual enrollment is only allowed if the device is already enrolled into a primary MDM server. This other enrollment separates the desired state management functionality from the primary functionality. The declared configuration enrollment's first desired state management model feature is called [extensibility](declared-configuration-extensibility.md). +WinDC protocol requires that a device has a separate [OMA-DM enrollment](mdm-overview.md), which is dependent on the device being enrolled with the primary OMA-DM server. The desired state model is a different model from the current model where the server is responsible for the device's desire state. This dual enrollment is only allowed if the device is already enrolled into a primary mobile device management (MDM) server. This other enrollment separates the desired state management functionality from the primary functionality. -:::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the declared configuration model."::: +WinDC enrollment involves two phases: -With the [Declared Configuration CSP](mdm/declaredconfiguration-csp.md), the OMA-DM server can provide the device with the complete collection of setting names and associated values based on a specified scenario. The declared configuration stack on the device is responsible for handling the configuration request, and maintaining its state including updates to the scenario. +- [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the WinDC protocol uses a dedicated JSON schema to query enrollment details from the [discovery service endpoint (DS)](/openspecs/windows_protocols/ms-mde2/60deaa44-52df-4a47-a844-f5b42037f7d3#gt_8d76dac8-122a-452b-8c97-b25af916f19b). This phase involves sending HTTP requests with specific headers and a JSON body containing details such as user domain, tenant ID, and OS version. The DS responds with the necessary enrollment service URLs and authentication policies based on the enrollment type (Microsoft Entra joined or registered devices). +- [Declared configuration enrollment](declared-configuration-enrollment.md): The enrollment phase uses the [MS-MDE2 protocol](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and new [DMClient CSP](mdm/dmclient-csp.md) policies for dual enrollment. This phase involves setting the `LinkedEnrollment/DiscoveryEndpoint` and triggering the `LinkedEnrollment/Enroll` using SyncML commands. The device can then manage its configuration state by interacting with the OMA-DM server through these policies. -The benefit of the declared configuration desired state model is that it's efficient and accurate, especially since it's the responsibility of the declared configuration client to configure the device. The efficiency of declared configuration is because the client can asynchronously process batches of scenario settings, which free up the server resources to do other work. Thus the declared configuration protocol has low latency. As for configuration quality and accuracy, the declared configuration client stack has detailed knowledge of the configuration surface area of the device. This behavior includes the proper handling of continuous device updates that affect the configuration scenario. +WinDC enrollment offers these desired state management features: -## Declared configuration enrollment +- [Resource access](declared-configuration-resource-access.md): Provides access to necessary resources for configuration. +- [Extensibility](declared-configuration-extensibility.md): Allows for extending the configuration capabilities as needed. -[Mobile Device Enrollment Protocol version 2](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) describes enrollment including discovery, which covers the primary and declared configuration enrollments. The device uses the following new [DMClient CSP](mdm/dmclient-csp.md) policies for declared configuration dual enrollment: +:::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the WinDC model."::: -- [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll) -- [LinkedEnrollment/Unenroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentunenroll) -- [LinkedEnrollment/EnrollStatus](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenrollstatus) -- [LinkedEnrollment/LastError](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentlasterror) -- [LinkedEnrollment/DiscoveryEndpoint](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentdiscoveryendpoint) +After a device is enrolled, the OMA-DM server can send a complete collection of setting names and values for a specified scenario using the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md). The WinDC stack on the device is responsible for handling the configuration request, and maintaining its state including updates to the scenario. -The following SyncML example sets **LinkedEnrolment/DiscoveryEndpoint** and triggers **LinkedEnrollment/Enroll**: +The benefit of the WinDC desired state model is that it's efficient and accurate, especially since it's the responsibility of the WinDC client stack to configure the device. The efficiency of WinDC is because the client can asynchronously process batches of scenario settings, which free up the server resources to do other work. Thus the WinDC protocol has low latency. As for configuration quality and accuracy, the WinDC client stack has detailed knowledge of the configuration surface area of the device. This behavior includes the proper handling of continuous device updates that affect the configuration scenario. -```xml - - +## Supported platforms + +WinDC enrollment for [Microsoft Entra joined devices](/entra/identity/devices/concept-directory-join) is supported for all versions of Windows 10/11. + +WinDC enrollment for [Microsoft Entra registered devices](/entra/identity/devices/concept-device-registration) is supported for Windows 10/11 with the following updates: + +- Windows 11, version 24H2 with [KB5040529](https://support.microsoft.com/help/5040529) (OS Build 26100.1301) +- Windows 11, version 23H2 with [KB5040527](https://support.microsoft.com/help/5040527) (OS Build 22631.3958) +- Windows 11, version 22H2 with [KB5040527](https://support.microsoft.com/help/5040527) (OS Build 22621.3958) +- Windows 10, version 22H2 with [KB5040525](https://support.microsoft.com/help/5040525) (OS Build 19045.4717) + +## Refresh interval + +The WinDC refresh schedule is created whenever there's a WinDC document present on the device and there's currently no schedule task for refresh. The task runs every 4 hours by default and can be configured. Each time the WinDC refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the WinDC documents. If there are any drifts, WinDC engine tries to reapply the WinDC documents to fix it. In case where a WinDC document can't be reapplied due to instance data missing, the WinDC document is marked in drifted state and a new sync session is triggered to notify there's a drift. + +To identify, adjust or remove the refresh schedule, use the **RefreshInterval** URI: + +- Identify current schedule: + + ```xml + + + + + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/ManagementServiceConfiguration/RefreshInterval + + + + + + + ``` + +- Adjust current schedule: + + ```xml + + + - 2 - - - ./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/DiscoveryEndpoint - - https://discovery.dm.microsoft.com/EnrollmentConfiguration?api-version=1.0 - + 2 + + + int + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/ManagementServiceConfiguration/RefreshInterval + + 30 + - - - - - - - - 2 - - - ./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/Enroll - - - - - - -``` - -## Related content - -- [Declared Configuration extensibility](declared-configuration-extensibility.md) + + + + ``` + +- Delete the current schedule and use system default: + + ```xml + + + + + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/ManagementServiceConfiguration/RefreshInterval + + + + + + + ``` + +## Troubleshooting + +If the processing of declared configuration document fails, the errors are logged to Windows event logs: + +- Admin events: `Application and Service Logs\Microsoft\Windows\DeviceManagement-Enterprise-Diagnostics-Provider\Admin`. +- Operational events: `Application and Service Logs\Microsoft\Windows\DeviceManagement-Enterprise-Diagnostics-Provider\Operational`. + +### Common errors + +- If the `` uses **Device** scope, while DeclaredConfiguration document specifies **User** context, Admin event log shows an error message similar to: + + `MDM ConfigurationManager: Command failure status. Configuration Source ID: (DAD70CC2-365B-450D-A8AB-2EB23F4300CC), Enrollment Name: (MicrosoftManagementPlatformCloud), Provider Name: (DeclaredConfiguration), Command Type: (SetValue: from Replace), CSP URI: (./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document), Result: (The system cannot find the file specified.)` + +- If the Document ID doesn't match between the `` and inside DeclaredConfiguration document, Admin event log shows an error message similar to: + + `MDM Declared Configuration: End document parsing from CSP: Document Id: (DCA000B5-397D-40A1-AABF-40B25078A7F91), Scenario: (MSFTVPN), Version: (A0), Enrollment Id: (DAD70CC2-365B-450D-A8AB-2EB23F4300CC), Current User: (S-1-5-21-3436249567-4017981746-3373817415-1001), Schema: (1.0), Download URL: (), Scope: (0x1), Enroll Type: (0x1A), File size: (0xDE2), CSP Count: (0x1), URI Count: (0xF), Action Requested: (0x0), Model: (0x1), Result:(0x8000FFFF) Catastrophic failure.` + +- Any typo in the OMA-URI results in a failure. In this example, `TrafficFilterList` is specified instead of `TrafficFilterLists`, and Admin event log shows an error message similar to: + + `MDM ConfigurationManager: Command failure status. Configuraton Source ID: (DAD70CC2-365B-450D-A8AB-2EB23F4300CC), Enrollment Type: (MicrosoftManagementPlatformCloud), CSP Name: (vpnv2), Command Type: (Add: from Replace or Add), CSP URI: (./user/vendor/msft/vpnv2/Test_SonicWall/TrafficFilterLists), Result: (Unknown Win32 Error code: 0x86000002).` + + There's also another warning message in operational channel: + + `MDM Declared Configuration: Function (DeclaredConfigurationExtension_PolicyCSPConfigureGivenCurrentDoc) operation (ErrorAtDocLevel: one or more CSPs failed) failed with (Unknown Win32 Error code: 0x82d00007)` \ No newline at end of file diff --git a/windows/client-management/images/declared-configuration-ra-syntax.png b/windows/client-management/images/declared-configuration-ra-syntax.png new file mode 100644 index 00000000000..6ab42b77bf4 Binary files /dev/null and b/windows/client-management/images/declared-configuration-ra-syntax.png differ diff --git a/windows/client-management/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index 5614e38ee49..4251c9ab443 100644 --- a/windows/client-management/mdm/declaredconfiguration-csp.md +++ b/windows/client-management/mdm/declaredconfiguration-csp.md @@ -1,7 +1,7 @@ --- title: DeclaredConfiguration CSP description: Learn more about the DeclaredConfiguration CSP. -ms.date: 01/18/2024 +ms.date: 09/12/2024 --- @@ -15,13 +15,13 @@ ms.date: 01/18/2024 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). @@ -730,107 +730,51 @@ The Document node's value is an XML based document containing a collection of se -## 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 `` 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 - - - c:\data\test\bin\ut_extensibility.tmp - TestFileContentBlah - + + ... {Configuration Data} ... ``` -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 `` 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: - -```xml - - - - - 14 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/99988660-9080-3433-96e8-f32e85011999/Document - - - - - c:\data\test\bin\ut_extensibility.tmp - TestFileContentBlah - - ]]> - - - - - - -``` - -### DeclaredConfiguration XML document tags +The `` 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. -Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInventory` are OS-defined scenarios that require the same tags and attributes. +This tag has the following attributes: -- The `` 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. +| 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. | - This tag has the following attributes: +The DeclaredConfiguration CSP synchronously validates the batch of settings described by the `` 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. - | 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`. | +The actual processing of the request pivots around the `osdefinedscenario` tag and the configuration data specified within the document. For more information, see: -- The `` 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. +- [WinDC document for resource access](../declared-configuration-resource-access.md#windc-document) +- [WinDC document for extensibility](../declared-configuration-extensibility.md#windc-document) - This tag has the following attributes: +## WinDC generic alert - | Attribute | Description | - |--|--| - | `namespace` | Specifies the targeted MI provider namespace. | - | `classname` | The targeted MI provider. | - -- The `` 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 `` content. - - This tag has the following attributes: - - | Attribute | Description | - |--|--| - | `name` | Specifies the name of an MI provider parameter. | - -- The `` 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 `` 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 @@ -853,9 +797,13 @@ On every client response to the server's request, the client constructs a declar ``` -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. + +## WinDC states -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 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: - - ```xml - - - - 2 - - - chr - text/plain - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document - - - - - - - ``` - - ```xml - - 2 - 1 - 2 - Get - 200 - - - 3 - 1 - 2 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document - - - - - - - - - - - - ``` - -- Replace a configuration or inventory request - - ```xml - - - - 14 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document - - - - - c:/temp/foobar.tmp - - - ]]> - - - - - - - ``` - - ```xml - - 2 - 1 - 2 - Get - 200 - - 3 - 1 - 2 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/99998660-9080-3433-96e8-f32e85019999/Document - - - - - c:/temp/foobar.tmp - TestFileContent - - - - - - ``` +- [SyncML examples for resource access](../declared-configuration-resource-access.md#syncml-examples) +- [SyncML examples for extensibility](../declared-configuration-extensibility.md#syncml-examples) -- 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. +### Abandon a WinDC document - ```xml - - - - 2 - - +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. + +This example demonstrates how to abandon a WinDC document, by setting the **Abandoned** property to **1**. + +```xml + + + + 2 + + int text/plain - - + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Properties/Abandoned - - 1 + + 1 + + + + + +``` + +### 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 + + + + + 10 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned + + + int + + 0 + + + + + +``` + +### 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 + + + + + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document + - + - - ``` - -- 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 - - - - - 2 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document - - - - - - - ``` + +``` diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index 68a0a5c8d49..eba37a1745f 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -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