From 508b0d32a7fe0a19281463c0d2f7643080d86448 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Wed, 31 Jul 2024 10:33:46 -0600 Subject: [PATCH 01/15] Add new content for Resource access --- .../declared-configuration-resource-access.md | 213 ++++++++++++++++++ .../declared-configuration-ra-syntax.png | Bin 0 -> 54931 bytes windows/client-management/mdm/toc.yml | 2 + 3 files changed, 215 insertions(+) create mode 100644 windows/client-management/declared-configuration-resource-access.md create mode 100644 windows/client-management/images/declared-configuration-ra-syntax.png 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..b20cc0cd97b --- /dev/null +++ b/windows/client-management/declared-configuration-resource-access.md @@ -0,0 +1,213 @@ +--- +title: Resource access overview +description: Learn more about configuring resource access using Declared Configuration +ms.date: 07/29/2024 +ms.topic: overview +--- + +# Resource access + +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. Declared Configuration 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) play a vital role for configuring Resource access by acting as an interface between the device and the Declared Configuration 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): The VPNv2 CSP allows the Mobile Device Management (MDM) server to configure the VPN profile of the device. VPN profiles are crucial for secure remote access, enabling devices to access corporate resources safely over public networks. Organizations can enforce secure VPN connections to ensure resource access adheres to security and compliance standards, while protecting data traffic and user privacy. + +- [Wi-Fi CSP](mdm/wifi-csp.md): The Wi-Fi CSP provides the functionality to add or delete Wi-Fi networks on a Windows device. Efficient Wi-Fi connectivity is essential for devices to access resources quickly and securely. By managing Wi-Fi networks and ensuring they're configured according to security standards, the Wi-Fi CSP supports stable and secure resource access for devices connected to corporate networks. + +- [ClientCertificateInstall CSP](mdm/clientcertificateinstall-csp.md): The ClientCertificateInstall CSP handles personal certificate configurations and manages the import of certificates for secure communication and authentication. Properly provisioning and managing certificates are essential for secure resource access. Certificates provide identity verification and encrypted communication, ensuring authorized users can access resources securely. + +- [ActiveSync CSP](mdm/activesync-csp.md) + +- [WiredNetwork CSP](mdm/wirednetwork-csp.md) + +- [RootCACertificates CSP](mdm/rootcacertificates-csp.md) + +## Handling Configuration Requests + +The [Declared Configuration](declared-configuration.md) stack on the device processes configuration requests and maintains the desired state, which is key to Resource access. The efficiency and accuracy of handling configuration requests are critical for effective Resource access. + +- **Efficiency**: Batch-based processing minimizes server resource usage and reduces latency. +- **Accuracy**: Declared Configuration client stack understands the device's configuration surface area, enabling effective handling of continuous updates. This ensures precise execution of configuration changes communicated by the cloud service. + +[Declared Configuration](declared-configuration.md) enhances Resource access by offering cloud-based device management capabilities, allowing for remote configuration, monitoring, and policy enforcement. Resource access integrates seamlessly with Declared Configuration, providing an extended method for managing devices through the cloud with enhanced scalability and efficiency. + +- **Remote Configuration**: Administrators can manage device configurations remotely using Declared Configuration's cloud capabilities, providing flexibility in maintaining devices from anywhere. This allows administrators to make changes and updates to devices efficiently. +- **Monitoring**: Observe device performance and health from a centralized cloud platform, ensuring devices operate smoothly and efficiently. Monitoring can detect and address any issues with device resource configurations. +- **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. + +## Resource Access Configuration with Examples + +Resource access configuration utilizes the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md). A declared configuration request for configuring resource access is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Document`. + +- The URI is prefixed with a targeted scope. The `` and the DeclaredConfiguration Context need to match. For example, when `LocURI` starts with **Device**, Context should be **Device** as well. When `LocURI` doesn't start with **Device**, Context should be **User**. +- `{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 must be a **Complete** request. + +:::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="Declared Configuration resource access syntax"::: + +Only supported osdefinedscenarios can be used. Unsupported values result in a failure. + +- msftpolicies +- msftfirewall +- msftdefender +- msftnetworkproxy +- msftnetworkqospolicy +- msftpassportforwork +- msftwirednetwork +- msftdefaultproperties +- msftextensibilitymiproviderconfig +- msftadmxconfig +- msftresource +- msftvpn +- msftwifi +- msfttransaction +- msftinventory +- msftcertinventory +- msftsecuredcorestateinventory +- msftextensibilitymiproviderinventory +- msftonetime +- msftadmxinstall +- msftrootcatrustedcertificates +- msftcertificatestore +- msftscep +- msftclientcertificateinstall +- msftenterprisemodernappmanagementstoreinstall +- msftenterprisemodernappmanagementhostedinstall +- msftextensibilitymiproviderInstall +- msftadmxinstall + +### Adding a VPNv2 Profile for Resource Access + +This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to enable the **Always On** mode for a VPN Profile on the device. + +```xml + + + + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + chr + text/plain + + + + + + 2 + + ]]> + + + + + + +``` + +> [!NOTE] +> +> - Format of the `` and `` follow the [Declared Configuration CSP](mdm/declaredconfiguration-csp.md) syntax. +> - The `id` of `` should be a unique string. +> - `` of `` should be `chr` and `` should be `text/plain`. + +### Updating a VPNv2 Profile for Resource Access + +This example is the same as previous example, except that it uses `` instead of ``. + +```xml + + + + + 1 + + + chr + text/plain + + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + + 2 + + ]]> + + + + + +``` + +### Getting the VPNv2 Profile + +This example uses `` to retrieve the results of the Declared configuration request to verify the **Always On** mode of the VPNv2 profile. + +```xml + + + + + 1 + + + chr + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + + +``` + +### Deleting a VPNv2 Profile + +This example uses `` to remove the configuration request to set the VPNv2 profile. + +```xml + + + + + 1 + + + chr + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + + + + + + +``` 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 0000000000000000000000000000000000000000..6ab42b77bf4a0b7a8fe8bbf6d8407d475630072b GIT binary patch literal 54931 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 literal 0 HcmV?d00001 diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index f6ca93aa95f..32895686e45 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -34,6 +34,8 @@ items: items: - name: Declared Configuration 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 From c8cafb9386f539df8a34db437cdbd2a7bef2ffbd Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Wed, 31 Jul 2024 10:40:39 -0600 Subject: [PATCH 02/15] Acro-updates --- windows/client-management/mdm/toc.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index 32895686e45..9f584a9d361 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -13,7 +13,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 @@ -56,9 +56,9 @@ items: href: policies-in-policy-csp-supported-by-group-policy.md - name: Policies supported by HoloLens 2 href: policies-in-policy-csp-supported-by-hololens2.md - - name: Policies supported by HoloLens (1st gen) Commercial Suite + - name: Policies supported by HoloLens (first gen) Commercial Suite href: policies-in-policy-csp-supported-by-hololens-1st-gen-commercial-suite.md - - name: Policies supported by HoloLens (1st gen) Development Edition + - name: Policies supported by HoloLens (first gen) Development Edition href: policies-in-policy-csp-supported-by-hololens-1st-gen-development-edition.md - name: Policies supported by Windows 10 IoT Core href: policies-in-policy-csp-supported-by-iot-core.md @@ -381,7 +381,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 From 1c788ae124bfa66c43aa6348cebfcdc91bfc3704 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Wed, 31 Jul 2024 10:47:37 -0600 Subject: [PATCH 03/15] chore: Update resource access configuration guidelines and examples --- .../declared-configuration-resource-access.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index b20cc0cd97b..52d285342c9 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -23,7 +23,7 @@ Configuration Service Providers (CSPs) play a vital role for configuring Resourc - [RootCACertificates CSP](mdm/rootcacertificates-csp.md) -## Handling Configuration Requests +## Handling configuration requests The [Declared Configuration](declared-configuration.md) stack on the device processes configuration requests and maintains the desired state, which is key to Resource access. The efficiency and accuracy of handling configuration requests are critical for effective Resource access. @@ -36,7 +36,7 @@ The [Declared Configuration](declared-configuration.md) stack on the device proc - **Monitoring**: Observe device performance and health from a centralized cloud platform, ensuring devices operate smoothly and efficiently. Monitoring can detect and address any issues with device resource configurations. - **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 +## 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. @@ -49,7 +49,7 @@ These guidelines provide best practices and examples for developers and testers 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. -## Resource Access Configuration with Examples +## Resource access configuration with examples Resource access configuration utilizes the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md). A declared configuration request for configuring resource access is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Document`. @@ -90,7 +90,7 @@ Only supported osdefinedscenarios can be used. Unsupported values result in a fa - msftextensibilitymiproviderInstall - msftadmxinstall -### Adding a VPNv2 Profile for Resource Access +### Adding a VPNv2 profile for resource access This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to enable the **Always On** mode for a VPN Profile on the device. @@ -129,7 +129,7 @@ This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to enable the **Always On** > - The `id` of `` should be a unique string. > - `` of `` should be `chr` and `` should be `text/plain`. -### Updating a VPNv2 Profile for Resource Access +### Updating a VPNv2 profile for resource access This example is the same as previous example, except that it uses `` instead of ``. @@ -162,7 +162,7 @@ This example is the same as previous example, except that it uses `` in ``` -### Getting the VPNv2 Profile +### Getting the VPNv2 profile This example uses `` to retrieve the results of the Declared configuration request to verify the **Always On** mode of the VPNv2 profile. @@ -187,7 +187,7 @@ This example uses `` to retrieve the results of the Declared configuration ``` -### Deleting a VPNv2 Profile +### Deleting the VPNv2 profile This example uses `` to remove the configuration request to set the VPNv2 profile. From 9acadb6e2aa7c7c87c426f84a95f25ecc813fc0c Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Thu, 8 Aug 2024 11:03:53 -0600 Subject: [PATCH 04/15] Updates --- .../declared-configuration-resource-access.md | 443 ++++++++++++++---- .../declared-configuration.md | 72 ++- .../mdm/declaredconfiguration-csp.md | 4 +- 3 files changed, 430 insertions(+), 89 deletions(-) diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index 52d285342c9..df463687d92 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -1,39 +1,27 @@ --- title: Resource access overview description: Learn more about configuring resource access using Declared Configuration -ms.date: 07/29/2024 -ms.topic: overview +ms.date: 08/07/2024 +ms.topic: how-to --- # Resource access -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. Declared Configuration 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. +Resource Access (RA) 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. Declared Configuration 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) play a vital role for configuring Resource access by acting as an interface between the device and the Declared Configuration 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): The VPNv2 CSP allows the Mobile Device Management (MDM) server to configure the VPN profile of the device. VPN profiles are crucial for secure remote access, enabling devices to access corporate resources safely over public networks. Organizations can enforce secure VPN connections to ensure resource access adheres to security and compliance standards, while protecting data traffic and user privacy. - -- [Wi-Fi CSP](mdm/wifi-csp.md): The Wi-Fi CSP provides the functionality to add or delete Wi-Fi networks on a Windows device. Efficient Wi-Fi connectivity is essential for devices to access resources quickly and securely. By managing Wi-Fi networks and ensuring they're configured according to security standards, the Wi-Fi CSP supports stable and secure resource access for devices connected to corporate networks. - -- [ClientCertificateInstall CSP](mdm/clientcertificateinstall-csp.md): The ClientCertificateInstall CSP handles personal certificate configurations and manages the import of certificates for secure communication and authentication. Properly provisioning and managing certificates are essential for secure resource access. Certificates provide identity verification and encrypted communication, ensuring authorized users can access resources securely. +[Configuration Service Providers (CSPs)](mdm/index.yml) play a vital role for configuring Resource access by acting as an interface between the device and the Declared Configuration 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) -## Handling configuration requests - -The [Declared Configuration](declared-configuration.md) stack on the device processes configuration requests and maintains the desired state, which is key to Resource access. The efficiency and accuracy of handling configuration requests are critical for effective Resource access. +The [Declared Configuration](declared-configuration.md) 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 Declared Configuration, 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**: Declared Configuration client stack understands the device's configuration surface area, enabling effective handling of continuous updates. This ensures precise execution of configuration changes communicated by the cloud service. - -[Declared Configuration](declared-configuration.md) enhances Resource access by offering cloud-based device management capabilities, allowing for remote configuration, monitoring, and policy enforcement. Resource access integrates seamlessly with Declared Configuration, providing an extended method for managing devices through the cloud with enhanced scalability and efficiency. - -- **Remote Configuration**: Administrators can manage device configurations remotely using Declared Configuration's cloud capabilities, providing flexibility in maintaining devices from anywhere. This allows administrators to make changes and updates to devices efficiently. -- **Monitoring**: Observe device performance and health from a centralized cloud platform, ensuring devices operate smoothly and efficiently. Monitoring can detect and address any issues with device resource configurations. +- **Accuracy**: Declared Configuration 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 @@ -55,69 +43,76 @@ Resource access configuration utilizes the [DeclaredConfiguration CSP](mdm/decla - The URI is prefixed with a targeted scope. The `` and the DeclaredConfiguration Context need to match. For example, when `LocURI` starts with **Device**, Context should be **Device** as well. When `LocURI` doesn't start with **Device**, Context should be **User**. - `{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 must be a **Complete** request. :::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="Declared Configuration resource access syntax"::: -Only supported osdefinedscenarios can be used. Unsupported values result in a failure. - -- msftpolicies -- msftfirewall -- msftdefender -- msftnetworkproxy -- msftnetworkqospolicy -- msftpassportforwork -- msftwirednetwork -- msftdefaultproperties -- msftextensibilitymiproviderconfig -- msftadmxconfig -- msftresource -- msftvpn -- msftwifi -- msfttransaction -- msftinventory -- msftcertinventory -- msftsecuredcorestateinventory -- msftextensibilitymiproviderinventory -- msftonetime -- msftadmxinstall -- msftrootcatrustedcertificates -- msftcertificatestore -- msftscep -- msftclientcertificateinstall -- msftenterprisemodernappmanagementstoreinstall -- msftenterprisemodernappmanagementhostedinstall -- msftextensibilitymiproviderInstall -- msftadmxinstall - -### Adding a VPNv2 profile for resource access - -This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to enable the **Always On** mode for a VPN Profile on the device. +Only supported values for `osdefinedscenario` can be used. Unsupported values result in a failure. + +| osdefinedscenario | Recommended using with | +|------------------------------|-------------------------------| +| MSFTWiredNetwork | WiredNetwork | +| MSFTResource | ActiveSync | +| MSFTVpn | VPN and VPNv2 | +| MSFTWifi | Wifi | +| MSFTInventory | Certificate inventory | +| MSFTClientCertificateInstall | SCEP, PFX, Bulk Template Data | + +Examples: + +1. MSFTWifi (snippet) for Wifi: + + ```xml + + + ``` + +1. MSFTTResource (snippet) for ActiveSync: + + ```xml + + + ``` + +### Configure a VPNv2 profile for resource access + +This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile named **Test_SonicWall** on the device in the **User** scope. ```xml - + - + 2 - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document - - chr + chr text/plain - - - - - 2 - - ]]> - + + ./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 + + + ]]> - + @@ -131,30 +126,37 @@ This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to enable the **Always On** ### Updating a VPNv2 profile for resource access -This example is the same as previous example, except that it uses `` instead of ``. +This example uses the same Declared Configuration **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile. ```xml - - 1 + 2 chr text/plain - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document - + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document - - - 2 - - ]]> + + + 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 + + + ]]> @@ -164,7 +166,7 @@ This example is the same as previous example, except that it uses `` in ### Getting the VPNv2 profile -This example uses `` to retrieve the results of the Declared configuration request to verify the **Always On** mode of the VPNv2 profile. +This example uses `` to retrieve the results of the Declared configuration request. ```xml @@ -178,7 +180,7 @@ This example uses `` to retrieve the results of the Declared configuration text/plain - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document @@ -187,6 +189,45 @@ This example uses `` to retrieve the results of the Declared configuration ``` +**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 [Declared configuration states](mdm/declaredconfiguration-csp.md#declared-configuration-states). + ### Deleting the VPNv2 profile This example uses `` to remove the configuration request to set the VPNv2 profile. @@ -203,7 +244,7 @@ This example uses `` to remove the configuration request to set the VPNv text/plain - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document + ./User/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Document @@ -211,3 +252,233 @@ This example uses `` to remove the configuration request to set the VPNv ``` + + +## Resource Ownership + +MDM-managed resources, such as a VPN profile, are transferred/migrated to Windows Declared Configuration management when a Declared Configuration document is sent to the device for the same resource. This resource stays under Declared Configuration management until the Windows Declared Configuration document is deleted or abandoned. 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).` + +### Abandon Workflow + +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 Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration document that handles drift control. Also the resource ownership is transferred back to MDM, which means the same resource can be modified via legacy MDM channel again. + +Example: Abandoning a Windows Declared Configuration Document, by setting the **Abandoned** property to **1**. + +```xml + + + + + 10 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned + + + int + + 1 + + + + + +``` + +### Unabandon workflow + +Unabandoning the document causes the document to be applied right away, transferring the resource ownership back to Declared Configuration management and blocking legacy MDM channel from managing the channels again. + +Example: Unabandoning a Windows Declared Configuration 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 + + + + + +``` + +## 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 for dynamic nodes is sent later by the server. 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 should be documented and 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..db039f3109d 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -1,7 +1,7 @@ --- title: Declared configuration protocol description: Learn more about using declared configuration protocol for desired state management of Windows devices. -ms.date: 07/08/2024 +ms.date: 08/07/2024 ms.topic: overview --- @@ -17,9 +17,77 @@ With the [Declared Configuration CSP](mdm/declaredconfiguration-csp.md), the OMA 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. +## Declared configuration refresh interval + +The Declared Configuration refresh schedule is created whenever there is a Declared Configuration doc present on the device and there is currently no schedule task for refresh. The task runs every 4 hours by default and can be configured. Each time the Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine will try to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc cannot be reapplied due to instance data missing, the Declared Configuration doc will be marked as drifted state and a new sync session will be triggered to notify there is 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 + + + int + text/plain + + + ./Device/Vendor/MSFT/DeclaredConfiguration/ManagementServiceConfiguration/RefreshInterval + + 30 + + + + + + ``` + +- Delete the current schedule and use system default: + + ```xml + + + + + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/ManagementServiceConfiguration/RefreshInterval + + + + + + + ``` + ## Declared configuration enrollment -[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: +The device uses new [DMClient CSP](mdm/dmclient-csp.md) policies for declared configuration dual enrollment: - [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll) - [LinkedEnrollment/Unenroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentunenroll) diff --git a/windows/client-management/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index 5614e38ee49..48de402dbfd 100644 --- a/windows/client-management/mdm/declaredconfiguration-csp.md +++ b/windows/client-management/mdm/declaredconfiguration-csp.md @@ -801,7 +801,7 @@ Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInvento | `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`. | + | `osdefinedscenario` | The named scenario that the client should configure with the given configuration data. For extensibility, the scenario is either `MSFTExtensibilityMIProviderConfig` or `MSFTExtensibilityMIProviderInventory`. | - 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. @@ -855,6 +855,8 @@ 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`. +## Declared configuration 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: ```csharp From f63164b3a638b01c8f373d57fdddbf630e375367 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Mon, 12 Aug 2024 13:25:56 -0600 Subject: [PATCH 05/15] Mo-updates --- .../declared-configuration-discovery.md | 266 ++++++++++++++++++ .../declared-configuration-enrollment.md | 49 ++++ .../declared-configuration.md | 57 +--- windows/client-management/mdm/toc.yml | 4 + 4 files changed, 330 insertions(+), 46 deletions(-) create mode 100644 windows/client-management/declared-configuration-discovery.md create mode 100644 windows/client-management/declared-configuration-enrollment.md diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md new file mode 100644 index 00000000000..b2d548ff933 --- /dev/null +++ b/windows/client-management/declared-configuration-discovery.md @@ -0,0 +1,266 @@ +--- +title: Declared configuration discovery +description: Learn more about configuring discovery for declared configuration enrollment. +ms.date: 08/12/2024 +ms.topic: how-to +--- + +# Declared configuration discovery + +Declared configuration 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). + +## Supported platforms + +Declared Configuration enrollment for [Microsoft Entra joined devices](/entra/identity/devices/concept-directory-join) is supported for all versions of Windows 10/11. + +Declared Configuration 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) + +## Schema structure + +### HTTP request headers + +**Correlation Headers** + +- `"(MS-CV: %s)"` + - Required: false + - Description: Correlation vector for enrollment + +- `"(client-request-id: %s)"` + - Required: false + - Description: Request ID + +**Content-Type Header** + +- `"Content-Type: application/json"` + - Required: true + - Description: HTTP Content-Type + +### HTTP request body (JSON) + +- `"userDomain" : "%s"` + - Required: false + - Description: Domain name of the enrolled account + + - `"upn" : "%s"` + - Required: false + - Description: User Principal Name (UPN) of the enrolled account + + - `"tenantId" : "%s"` + - Required: false + - Description: Tenant ID of the enrolled account + + - `"emmDeviceId" : "%s"` + - Required: false + - Description: Enterprise mobility management (EMM) device ID of the enrolled account + + - `"enrollmentType" : "%s"` + - Required: + - AADJ: false + - WPJ: true + - Description: Enrollment type of the enrolled account + - Supported Values: + - "Device": Indicates the parent enrollment type is AADJ (DS response should specify "AuthPolicy": "Federated"). + - "User": Indicates parent enrollment type is WPJ (DS response should specify "AuthPolicy": "Certificate") + - Legacy case (AADJ only): If the "enrollmentType" parameter isn't included in the request body, the device should be treated as AADJ. + +- `"osVersion" : "%d.%d.%d.%d"` + - Required: true + - Description: OS version on the device. The DS can use the `osVersion` to determine if the client platform supports Declared Configuration enrollment. Review [Supported platforms](#supported-platforms) for details. + +### HTTP DS response body (JSON) + +- `"EnrollmentServiceUrl" : "%s"` + - Required: true + - Description: URL of the Declared Configuration enrollment service + +- `"EnrollmentVersion" : "%s"` + - Required: false + - Description: Enrollment version + +- `"EnrollmentPolicyServiceUrl" : "%s"` + - Required: true + - Description: Enrollment Policy Service URL + +- `"AuthenticationServiceUrl" : "%s"` + - Required: true + - Description: Authentication Service URL + +- `"ManagementResource" : "%s"` + - Required: false + - Description: Management Resource + +- `"TouUrl" : "%s"` + - Required: false + - Description: Terms of use URL + +- `"AuthPolicy" : "%s"` + - Required: true + - Description: Authentication policy + - Supported values: "Federated" (required for AADJ), "Certificate" (required for WPJ) + +- `"errorCode" : "%s"` + - Required: false + - Description: Status code. An errorCode value of **UPNRequired** triggers the client to send a subsequent request with a value for the UPN property, if available. + +- `"message" : "%s"` + - Required: false + - Description: Status message + +## Examples + +### Declared Configuration 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. AADJ + + ```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. WPJ + + ```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. AADJ + + ```json + { + "userDomain" : "contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "Device", + "osVersion" : "10.0.00000.0" + } + ``` + + 1. WPJ + + ```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. AADJ + + ```json + { + "upn" : "johndoe@contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "Device", + "osVersion" : "10.0.00000.0" + } + ``` + + 1. WPJ + + ```json + { + "upn" : "johndoe@contoso.com", + "emmDeviceId" : "00000000-0000-0000-0000-000000000000", + "enrollmentType" : "WPJ", + "osVersion" : "10.0.00000.0" + } + ``` + +### Declared Configuration discovery response + +**Headers** + +`Content-Type: application/json` + +**Body** + +1. Microsoft Entra joined devices (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 devices (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 + +Declared Configuration enrollment requires different authentication mechanisms for Microsoft Entra joined and registered devices. + +- Microsoft Entra joined devices use 'Federated' authentication (Entra device token) +- Microsoft Entra registered devices use 'Certificate' authentication (MDM certificate provisioned for the parent enrollment). + +The Declared Configuration 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. + +Rules are: + +- [Discovery request] `"enrollmentType": "Device"` (Microsoft Entra joined devices) + - [Discovery response] `"AuthPolicy": "Federated"` + - -> The client uses the Entra device token to authenticate with the Declared Configuration enrollment server. + +- [Discovery request (legacy case where enrollmentType value is empty)] `"enrollmentType": ""` (Microsoft Entra joined devices) + - [Discovery response] `"AuthPolicy": "Federated"` + - -> The client uses the Entra device token to authenticate with the Declared Configuration enrollment server. + +- [Discovery request] `"enrollmentType": "Device"` (Microsoft Entra registered devices) + - [Discovery response] `"AuthPolicy": "Certificate"` + - -> The client uses the MDM certificate from the parent enrollment to authenticate with the Declared Configuration enrollment server. + +## Error handling + +#### UPN required + +If no UPN value is provided in the discovery request, the DS can set the errorCode property in the response as **UPNRequired** to trigger the client to retry the request with a UPN value provided. + +#### Timeout/throttling: + +The server can set the flag `WINHTTP_QUERY_RETRY_AFTER` to configure the client request to retry after a specified delay. \ 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..bea26d63cfb --- /dev/null +++ b/windows/client-management/declared-configuration-enrollment.md @@ -0,0 +1,49 @@ +--- +title: Declared configuration enrollment +description: Learn more about configuring enrollment for declared configuration protocol. +ms.date: 08/12/2024 +ms.topic: how-to +--- + +# Declared configuration enrollment + +The device uses new [DMClient CSP](mdm/dmclient-csp.md) policies for declared configuration dual enrollment: + +- [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 + + + + + + +``` \ No newline at end of file diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index db039f3109d..8853724d335 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -1,7 +1,7 @@ --- title: Declared configuration protocol description: Learn more about using declared configuration protocol for desired state management of Windows devices. -ms.date: 08/07/2024 +ms.date: 08/12/2024 ms.topic: overview --- @@ -9,7 +9,15 @@ ms.topic: 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 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). +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. + +- [Declared configuration discovery](declared-configuration-discovery.md) +- [Declared configuration enrollment](declared-configuration-enrollment.md) + +The declared configuration enrollment's offers following desired state management features + +- [Resource access](declared-configuration-resource-access.md) +- [Extensibility](declared-configuration-extensibility.md). :::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the declared configuration model."::: @@ -19,7 +27,7 @@ The benefit of the declared configuration desired state model is that it's effic ## Declared configuration refresh interval -The Declared Configuration refresh schedule is created whenever there is a Declared Configuration doc present on the device and there is currently no schedule task for refresh. The task runs every 4 hours by default and can be configured. Each time the Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine will try to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc cannot be reapplied due to instance data missing, the Declared Configuration doc will be marked as drifted state and a new sync session will be triggered to notify there is a drift. +The Declared Configuration refresh schedule is created whenever there's a Declared Configuration doc 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 Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc 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: @@ -85,49 +93,6 @@ To identify, adjust or remove the refresh schedule, use the **RefreshInterval** ``` -## Declared configuration enrollment - -The device uses new [DMClient CSP](mdm/dmclient-csp.md) policies for declared configuration dual enrollment: - -- [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 - - - - - - -``` - ## Related content - [Declared Configuration extensibility](declared-configuration-extensibility.md) diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index 2625a9778f5..3cbe25c38ce 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -46,6 +46,10 @@ items: - name: Declared Configuration protocol href: ../declared-configuration.md items: + - name: Declared Configuration discovery + href: ../declared-configuration-discovery.md + - name: Declared Configuration enrollment + href: ../declared-configuration-enrollment.md - name: Declared Configuration extensibility href: ../declared-configuration-extensibility.md - name: Resource access From e729fa47de50ffec07d82bac905421c819097994 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Wed, 14 Aug 2024 11:59:15 -0600 Subject: [PATCH 06/15] Updates --- .../declared-configuration-discovery.md | 187 ++++++------------ .../declared-configuration-enrollment.md | 8 +- .../declared-configuration-extensibility.md | 2 +- .../declared-configuration-resource-access.md | 10 +- .../declared-configuration.md | 31 +-- windows/client-management/mdm/toc.yml | 7 +- 6 files changed, 93 insertions(+), 152 deletions(-) diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md index b2d548ff933..f5799106bdd 100644 --- a/windows/client-management/declared-configuration-discovery.md +++ b/windows/client-management/declared-configuration-discovery.md @@ -1,115 +1,50 @@ --- title: Declared configuration discovery description: Learn more about configuring discovery for declared configuration enrollment. -ms.date: 08/12/2024 +ms.date: 08/14/2024 ms.topic: how-to --- # Declared configuration discovery -Declared configuration 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). +Declared configuration 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). -## Supported platforms - -Declared Configuration enrollment for [Microsoft Entra joined devices](/entra/identity/devices/concept-directory-join) is supported for all versions of Windows 10/11. - -Declared Configuration 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) +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 -**Correlation Headers** - -- `"(MS-CV: %s)"` - - Required: false - - Description: Correlation vector for enrollment - -- `"(client-request-id: %s)"` - - Required: false - - Description: Request ID - -**Content-Type Header** - -- `"Content-Type: application/json"` - - Required: true - - Description: HTTP Content-Type - -### HTTP request body (JSON) - -- `"userDomain" : "%s"` - - Required: false - - Description: Domain name of the enrolled account - - - `"upn" : "%s"` - - Required: false - - Description: User Principal Name (UPN) of the enrolled account - - - `"tenantId" : "%s"` - - Required: false - - Description: Tenant ID of the enrolled account - - - `"emmDeviceId" : "%s"` - - Required: false - - Description: Enterprise mobility management (EMM) device ID of the enrolled account - - - `"enrollmentType" : "%s"` - - Required: - - AADJ: false - - WPJ: true - - Description: Enrollment type of the enrolled account - - Supported Values: - - "Device": Indicates the parent enrollment type is AADJ (DS response should specify "AuthPolicy": "Federated"). - - "User": Indicates parent enrollment type is WPJ (DS response should specify "AuthPolicy": "Certificate") - - Legacy case (AADJ only): If the "enrollmentType" parameter isn't included in the request body, the device should be treated as AADJ. - -- `"osVersion" : "%d.%d.%d.%d"` - - Required: true - - Description: OS version on the device. The DS can use the `osVersion` to determine if the client platform supports Declared Configuration enrollment. Review [Supported platforms](#supported-platforms) for details. - -### HTTP DS response body (JSON) - -- `"EnrollmentServiceUrl" : "%s"` - - Required: true - - Description: URL of the Declared Configuration enrollment service - -- `"EnrollmentVersion" : "%s"` - - Required: false - - Description: Enrollment version - -- `"EnrollmentPolicyServiceUrl" : "%s"` - - Required: true - - Description: Enrollment Policy Service URL - -- `"AuthenticationServiceUrl" : "%s"` - - Required: true - - Description: Authentication Service URL - -- `"ManagementResource" : "%s"` - - Required: false - - Description: Management Resource - -- `"TouUrl" : "%s"` - - Required: false - - Description: Terms of use URL - -- `"AuthPolicy" : "%s"` - - Required: true - - Description: Authentication policy - - Supported values: "Federated" (required for AADJ), "Certificate" (required for WPJ) - -- `"errorCode" : "%s"` - - Required: false - - Description: Status code. An errorCode value of **UPNRequired** triggers the client to send a subsequent request with a value for the UPN property, if available. - -- `"message" : "%s"` - - Required: false - - Description: Status message +| 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 Declared Configuration enrollment. Review [supported platforms](declared-configuration.md#supported-platforms) for details. | + +### HTTP DS Response Body (JSON) + +| Field | Required | Description | +|------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `EnrollmentServiceUrl` | Yes | URL of the Declared Configuration 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 @@ -123,7 +58,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr 1. Single template approach: Client sends the **UPN** value in the initial request, along with the **tenantId** parameter. - 1. AADJ + 1. Microsoft Entra joined: ```json { @@ -136,7 +71,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr } ``` - 1. WPJ + 1. Microsoft Entra registered: ```json { @@ -152,7 +87,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr 1. No UPN (legacy) - 1. AADJ + 1. Microsoft Entra joined: ```json { @@ -163,7 +98,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr } ``` - 1. WPJ + 1. Microsoft Entra registered: ```json { @@ -176,7 +111,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr 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. AADJ + 1. Microsoft Entra joined: ```json { @@ -187,7 +122,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr } ``` - 1. WPJ + 1. Microsoft Entra registered: ```json { @@ -206,7 +141,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr **Body** -1. Microsoft Entra joined devices (requires "AuthPolicy": "Federated") +1. Microsoft Entra joined (requires `"AuthPolicy": "Federated"`): ```json { @@ -219,7 +154,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr } ``` -1. Microsoft Entra registered devices (requires "AuthPolicy": "Certificate") +1. Microsoft Entra registered (requires `"AuthPolicy": "Certificate"`): ```json { @@ -234,33 +169,29 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr ### Authentication -Declared Configuration enrollment requires different authentication mechanisms for Microsoft Entra joined and registered devices. - -- Microsoft Entra joined devices use 'Federated' authentication (Entra device token) -- Microsoft Entra registered devices use 'Certificate' authentication (MDM certificate provisioned for the parent enrollment). +Declared Configuration enrollment requires different authentication mechanisms for Microsoft Entra joined and registered devices. The Declared Configuration 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. -The Declared Configuration 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 are: +#### Rules -- [Discovery request] `"enrollmentType": "Device"` (Microsoft Entra joined devices) - - [Discovery response] `"AuthPolicy": "Federated"` - - -> The client uses the Entra device token to authenticate with the Declared Configuration enrollment server. +- **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 Declared Configuration enrollment server. -- [Discovery request (legacy case where enrollmentType value is empty)] `"enrollmentType": ""` (Microsoft Entra joined devices) - - [Discovery response] `"AuthPolicy": "Federated"` - - -> The client uses the Entra device token to authenticate with the Declared Configuration 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 Declared Configuration enrollment server. -- [Discovery request] `"enrollmentType": "Device"` (Microsoft Entra registered devices) - - [Discovery response] `"AuthPolicy": "Certificate"` - - -> The client uses the MDM certificate from the parent enrollment to authenticate with the Declared Configuration 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 Declared Configuration enrollment server. ## Error handling -#### UPN required - -If no UPN value is provided in the discovery request, the DS can set the errorCode property in the response as **UPNRequired** to trigger the client to retry the request with a UPN value provided. - -#### Timeout/throttling: - -The server can set the flag `WINHTTP_QUERY_RETRY_AFTER` to configure the client request to retry after a specified delay. \ No newline at end of file +- **UPNRequired**: If no UPN value is provided in the discovery request, the DS can set the `errorCode` in the response to trigger the client to retry the request with a UPN value provided. +- **WINHTTP_QUERY_RETRY_AFTER**: The server can set this flag to configure the client request to retry after a specified delay. This 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 index bea26d63cfb..9e7e2c3c5b0 100644 --- a/windows/client-management/declared-configuration-enrollment.md +++ b/windows/client-management/declared-configuration-enrollment.md @@ -1,13 +1,15 @@ --- title: Declared configuration enrollment description: Learn more about configuring enrollment for declared configuration protocol. -ms.date: 08/12/2024 +ms.date: 08/14/2024 ms.topic: how-to --- # Declared configuration enrollment -The device uses new [DMClient CSP](mdm/dmclient-csp.md) policies for declared configuration dual enrollment: +Declared configuration enrollment leverages 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 declared configuration enrollment include: - [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll) - [LinkedEnrollment/Unenroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentunenroll) @@ -46,4 +48,4 @@ The following SyncML example sets **LinkedEnrolment/DiscoveryEndpoint** and trig -``` \ No newline at end of file +``` diff --git a/windows/client-management/declared-configuration-extensibility.md b/windows/client-management/declared-configuration-extensibility.md index 7b1f9991f82..660308e800f 100644 --- a/windows/client-management/declared-configuration-extensibility.md +++ b/windows/client-management/declared-configuration-extensibility.md @@ -1,7 +1,7 @@ --- title: Declared configuration extensibility description: Learn more about declared configuration extensibility through native WMI providers. -ms.date: 07/08/2024 +ms.date: 08/14/2024 ms.topic: how-to --- diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index df463687d92..050d03d6f20 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -1,15 +1,15 @@ --- title: Resource access overview description: Learn more about configuring resource access using Declared Configuration -ms.date: 08/07/2024 +ms.date: 08/14/2024 ms.topic: how-to --- -# Resource access +# Declared configuration resource access Resource Access (RA) 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. Declared Configuration 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 by acting as an interface between the device and the Declared Configuration protocol. They provide a consistent and standardized approach to deploying and enforcing configurations. CSPs support various resource access scenarios, including: +[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 Declared Configuration 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) @@ -264,7 +264,7 @@ MDM-managed resources, such as a VPN profile, are transferred/migrated to Window 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 Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration document that handles drift control. Also the resource ownership is transferred back to MDM, which means the same resource can be modified via legacy MDM channel again. -Example: Abandoning a Windows Declared Configuration Document, by setting the **Abandoned** property to **1**. +This example abandons a Windows Declared Configuration Document, by setting the **Abandoned** property to **1**. ```xml @@ -291,7 +291,7 @@ Example: Abandoning a Windows Declared Configuration Document, by setting the ** Unabandoning the document causes the document to be applied right away, transferring the resource ownership back to Declared Configuration management and blocking legacy MDM channel from managing the channels again. -Example: Unabandoning a Windows Declared Configuration Document, by setting the **Abandoned** property to **0**. +This example unabandons a Windows Declared Configuration Document, by setting the **Abandoned** property to **0**. ```xml diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index 8853724d335..1a2347025db 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -1,30 +1,41 @@ --- title: Declared configuration protocol description: Learn more about using declared configuration protocol for desired state management of Windows devices. -ms.date: 08/12/2024 +ms.date: 08/14/2024 ms.topic: overview --- # What is the declared configuration protocol -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 declared configuration protocol is a desired state device configuration model designed for efficient and reliable management of Windows devices. It leverages the OMA-DM SyncML protocol to provide all necessary settings in a single batch through a dedicated OMA-DM server. The device's declared configuration client stack 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. -- [Declared configuration discovery](declared-configuration-discovery.md) -- [Declared configuration enrollment](declared-configuration-enrollment.md) +- [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the Declared Configuration 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 follows the [MS-MDE2 protocol](openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and uses 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 declared configuration enrollment's offers following desired state management features +The declared configuration enrollment offers following desired state management features: -- [Resource access](declared-configuration-resource-access.md) -- [Extensibility](declared-configuration-extensibility.md). +- [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. :::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the declared configuration model."::: -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. +Once a device is enrolled, 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. 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. +## Supported platforms + +Declared Configuration enrollment for [Microsoft Entra joined devices](/entra/identity/devices/concept-directory-join) is supported for all versions of Windows 10/11. + +Declared Configuration 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) + ## Declared configuration refresh interval The Declared Configuration refresh schedule is created whenever there's a Declared Configuration doc 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 Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc is marked in drifted state and a new sync session is triggered to notify there's a drift. @@ -92,7 +103,3 @@ To identify, adjust or remove the refresh schedule, use the **RefreshInterval** ``` - -## Related content - -- [Declared Configuration extensibility](declared-configuration-extensibility.md) diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index 3cbe25c38ce..7c6638b5725 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -43,16 +43,17 @@ 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 protocol + href: ../declared-configuration.md - name: Declared Configuration discovery href: ../declared-configuration-discovery.md - name: Declared Configuration enrollment href: ../declared-configuration-enrollment.md - name: Declared Configuration extensibility href: ../declared-configuration-extensibility.md - - name: Resource access + - name: Declared Configuration resource access href: ../declared-configuration-resource-access.md - name: DeclaredConfiguration CSP href: declaredconfiguration-csp.md From 4396f9f7f73b014afc2ec59c054fb70546d9b304 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Wed, 14 Aug 2024 12:01:58 -0600 Subject: [PATCH 07/15] Fix links --- windows/client-management/declared-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index 1a2347025db..524da532c90 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -11,8 +11,8 @@ The declared configuration protocol is a desired state device configuration mode 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. -- [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the Declared Configuration 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 follows the [MS-MDE2 protocol](openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and uses 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. +- [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the Declared Configuration 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 follows the [MS-MDE2 protocol](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and uses 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 declared configuration enrollment offers following desired state management features: From f13aa0e4da42faaa6377f73325ac95d939cb8513 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Wed, 14 Aug 2024 17:45:17 -0600 Subject: [PATCH 08/15] Split content and examples --- .../declared-configuration-extensibility.md | 167 ++++++++++- .../declared-configuration-resource-access.md | 121 ++++---- .../declared-configuration.md | 8 +- .../mdm/declaredconfiguration-csp.md | 277 +++++------------- 4 files changed, 298 insertions(+), 275 deletions(-) diff --git a/windows/client-management/declared-configuration-extensibility.md b/windows/client-management/declared-configuration-extensibility.md index 660308e800f..f3e3cec37fc 100644 --- a/windows/client-management/declared-configuration-extensibility.md +++ b/windows/client-management/declared-configuration-extensibility.md @@ -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,6 +235,171 @@ The `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource` function does the 1. Clean up resources, for example, free allocated memory. +## Declared Configuration document + +> [!IMPORTANT] +> The target of the scenario settings can only be device wide for extensibility. The CSP **scope** defined in `` and Declared Configuration **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 Declared Configuration 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) diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index 050d03d6f20..e0874b8d6fe 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -37,45 +37,77 @@ These guidelines provide best practices and examples for developers and testers 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. -## Resource access configuration with examples +## Declared Configuration document -Resource access configuration utilizes the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md). A declared configuration request for configuring resource access is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/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 Declared Configuration document with the configuration data specified for resource accecss. -- The URI is prefixed with a targeted scope. The `` and the DeclaredConfiguration Context need to match. For example, when `LocURI` starts with **Device**, Context should be **Device** as well. When `LocURI` doesn't start with **Device**, Context should be **User**. -- `{DocID}` is a unique identifier for the desired state of the configuration scenario. Every document must have an **ID**, which must be a GUID. - -:::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="Declared Configuration resource access syntax"::: +```xml + + + 2 + outbound + + +``` -Only supported values for `osdefinedscenario` can be used. Unsupported values result in a failure. +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 | +| MSFTVPN | VPN and VPNv2 | | MSFTWifi | Wifi | | MSFTInventory | Certificate inventory | | MSFTClientCertificateInstall | SCEP, PFX, Bulk Template Data | -Examples: +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. -1. MSFTWifi (snippet) for Wifi: + 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 Declared Configuration context. The CSP **scope** defined in `` and Declared Configuration **context** must both be either `Device` or `User`. +> +> :::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="Declared Configuration resource access syntax"::: + +### osdefinedscenario examples + +- Partial `MSFTWifi` example for Wifi: ```xml ``` -1. MSFTTResource (snippet) for ActiveSync: +- 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 uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile named **Test_SonicWall** on the device in the **User** scope. +This example demostrates 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 @@ -118,15 +150,17 @@ This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile n ``` + ### Updating a VPNv2 profile for resource access -This example uses the same Declared Configuration **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile. +This example demonstrates how to use the same Declared Configuration **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile. ```xml @@ -166,7 +200,7 @@ This example uses the same Declared Configuration **Document ID**, but with a ne ### Getting the VPNv2 profile -This example uses `` to retrieve the results of the Declared configuration request. +This example demonstrates how to use `` to retrieve the results of the Declared configuration request. ```xml @@ -230,7 +264,7 @@ This example uses `` to retrieve the results of the Declared configuration ### Deleting the VPNv2 profile -This example uses `` to remove the configuration request to set the VPNv2 profile. +This example demonstrates how to use `` to remove the configuration request to set the VPNv2 profile. ```xml @@ -253,67 +287,12 @@ This example uses `` to remove the configuration request to set the VPNv ``` - ## Resource Ownership -MDM-managed resources, such as a VPN profile, are transferred/migrated to Windows Declared Configuration management when a Declared Configuration document is sent to the device for the same resource. This resource stays under Declared Configuration management until the Windows Declared Configuration document is deleted or abandoned. Otherwise, when MDM tries to manage the same resource via the legacy MDM channel using SyncML, it fails with error 0x86000031. +MDM-managed resources, such as a VPN profile, are transferred/migrated to Windows Declared Configuration management when a Declared Configuration document is sent to the device for the same resource. This resource stays under Declared Configuration management until the Windows Declared Configuration document is [deleted](mdm/declaredconfiguration-csp.md#delete-a-declared-configuration-document) or [abandoned](mdm/declaredconfiguration-csp.md#abandon-a-declared-configuration-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).` -### Abandon Workflow - -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 Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration document that handles drift control. Also the resource ownership is transferred back to MDM, which means the same resource can be modified via legacy MDM channel again. - -This example abandons a Windows Declared Configuration Document, by setting the **Abandoned** property to **1**. - -```xml - - - - - 10 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned - - - int - - 1 - - - - - -``` - -### Unabandon workflow - -Unabandoning the document causes the document to be applied right away, transferring the resource ownership back to Declared Configuration management and blocking legacy MDM channel from managing the channels again. - -This example unabandons a Windows Declared Configuration 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 - - - - - -``` - ## 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. diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index 524da532c90..111b3e39d3f 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -7,14 +7,14 @@ ms.topic: overview # What is the declared configuration protocol -The declared configuration protocol is a desired state device configuration model designed for efficient and reliable management of Windows devices. It leverages the OMA-DM SyncML protocol to provide all necessary settings in a single batch through a dedicated OMA-DM server. The device's declared configuration client stack processes these settings to achieve the desired state in the most efficient and reliable manner. +The declared configuration 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 device's declared configuration client stack 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. - [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the Declared Configuration 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 follows the [MS-MDE2 protocol](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and uses 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 declared configuration enrollment offers following desired state management features: +The declared configuration enrollment offers these desired state management features: - [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. @@ -36,9 +36,9 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr - 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) -## Declared configuration refresh interval +## Refresh interval -The Declared Configuration refresh schedule is created whenever there's a Declared Configuration doc 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 Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc is marked in drifted state and a new sync session is triggered to notify there's a drift. +The Declared configuration refresh schedule is created whenever there's a Declared Configuration doc 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 Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc 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: diff --git a/windows/client-management/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index 48de402dbfd..ea3e57c5f3c 100644 --- a/windows/client-management/mdm/declaredconfiguration-csp.md +++ b/windows/client-management/mdm/declaredconfiguration-csp.md @@ -730,103 +730,47 @@ The Document node's value is an XML based document containing a collection of se -## Declared configuration OMA URI +## Declared Configuration OMA URI A declared configuration 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`: +## Declared Configuration 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 - -Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInventory` are OS-defined scenarios that require the same tags and 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](#hostcomplete) or an [inventory](#hostinventory) request. -- 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. +This tag has the following attributes: - This tag has the following attributes: +| 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. | - | 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 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 the 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 `` 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. +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: - - | 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 document for resource access](../declared-configuration-resource-access.md#declared-configuration-document) +- [Declared Configuration document for extensibility](../declared-configuration-extensibility.md#declared-configuration-document) ## Declared configuration generic alert @@ -855,9 +799,11 @@ 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`. +The **state** attribute has a value of `60`, which indicates that the document was processed successfully. + ## Declared configuration 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 @@ -891,133 +837,66 @@ 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 - - - - 2 - - - chr - text/plain - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document - - - - - - - ``` +### Abandon a Declared Configuration document - ```xml - - 2 - 1 - 2 - Get - 200 - - - 3 - 1 - 2 - - - ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document - - - - - - - - - - - - ``` +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 Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration 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 demonstrats how to abandon a Declared Configuration Document, by setting the **Abandoned** property to **1**. - ```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 - - - - - - ``` - -- 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 - - - - 2 - - +```xml + + + + 2 + + int text/plain - - + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Properties/Abandoned - - 1 - - + + 1 + + - - - ``` + + +``` + +### Unabandon a Declared Configuration 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 Declared Configuration management and blocking legacy MDM channel from managing the channels again. + +This example demonstrates how to unabandon a Windows Declared Configuration 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 Declared Configuration 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). +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 From 71b40ad58befcc9be3f3dbdcf858d86404b8a035 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Thu, 15 Aug 2024 10:20:21 -0600 Subject: [PATCH 09/15] Fix indentation --- .../mdm/declaredconfiguration-csp.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/windows/client-management/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index ea3e57c5f3c..ae7ef3991e8 100644 --- a/windows/client-management/mdm/declaredconfiguration-csp.md +++ b/windows/client-management/mdm/declaredconfiguration-csp.md @@ -898,22 +898,22 @@ This example demonstrates how to unabandon a Windows Declared Configuration Docu 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 - - - - - - - ``` +```xml + + + + + 2 + + + ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document + + + + + + +``` From e35c39b1263cf58491583207a98ab71df3c68319 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Fri, 16 Aug 2024 13:11:43 -0600 Subject: [PATCH 10/15] More updates --- .../declared-configuration-discovery.md | 26 +++++------ .../declared-configuration-enrollment.md | 10 ++-- .../declared-configuration-extensibility.md | 28 +++++------ .../declared-configuration-resource-access.md | 38 +++++++-------- .../declared-configuration.md | 32 +++++++------ .../mdm/declaredconfiguration-csp.md | 46 +++++++++---------- 6 files changed, 91 insertions(+), 89 deletions(-) diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md index f5799106bdd..ad0c3265f8b 100644 --- a/windows/client-management/declared-configuration-discovery.md +++ b/windows/client-management/declared-configuration-discovery.md @@ -1,13 +1,13 @@ --- -title: Declared configuration discovery -description: Learn more about configuring discovery for declared configuration enrollment. -ms.date: 08/14/2024 +title: Windows declared configuration discovery +description: Learn more about configuring discovery for Windows declared configuration enrollment. +ms.date: 08/16/2024 ms.topic: how-to --- # Declared configuration discovery -Declared configuration 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). +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. @@ -30,13 +30,13 @@ This article outlines the schema structure for the HTTP request and response bod | `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 Declared Configuration enrollment. Review [supported platforms](declared-configuration.md#supported-platforms) for details. | +| `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 Declared Configuration enrollment service | +| `EnrollmentServiceUrl` | Yes | URL of the WinDC enrollment service | | `EnrollmentVersion` | No | Enrollment version | | `EnrollmentPolicyServiceUrl` | Yes | Enrollment Policy Service URL | | `AuthenticationServiceUrl` | Yes | Authentication Service URL | @@ -48,7 +48,7 @@ This article outlines the schema structure for the HTTP request and response bod ## Examples -### Declared Configuration discovery request +### Discovery request **Headers** @@ -133,7 +133,7 @@ This article outlines the schema structure for the HTTP request and response bod } ``` -### Declared Configuration discovery response +### Discovery response **Headers** @@ -169,7 +169,7 @@ This article outlines the schema structure for the HTTP request and response bod ### Authentication -Declared Configuration enrollment requires different authentication mechanisms for Microsoft Entra joined and registered devices. The Declared Configuration 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. +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). @@ -179,19 +179,19 @@ Declared Configuration enrollment requires different authentication mechanisms f - **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 Declared Configuration enrollment server. + - **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 Declared Configuration enrollment server. + - **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 Declared Configuration enrollment server. + - **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` in the response to trigger the client to retry the request with a UPN value provided. -- **WINHTTP_QUERY_RETRY_AFTER**: The server can set this flag to configure the client request to retry after a specified delay. This is useful for handling timeout or throttling scenarios. \ No newline at end of file +- **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 index 9e7e2c3c5b0..cfab4852574 100644 --- a/windows/client-management/declared-configuration-enrollment.md +++ b/windows/client-management/declared-configuration-enrollment.md @@ -1,15 +1,15 @@ --- -title: Declared configuration enrollment -description: Learn more about configuring enrollment for declared configuration protocol. -ms.date: 08/14/2024 +title: Windows declared configuration enrollment +description: Learn more about configuring enrollment for Windows declared configuration protocol. +ms.date: 08/16/2024 ms.topic: how-to --- # Declared configuration enrollment -Declared configuration enrollment leverages 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. +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 declared configuration enrollment include: +The key CSP policies used for WinDC enrollment include: - [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll) - [LinkedEnrollment/Unenroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentunenroll) diff --git a/windows/client-management/declared-configuration-extensibility.md b/windows/client-management/declared-configuration-extensibility.md index f3e3cec37fc..6dcebc35b30 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: 08/14/2024 +title: Windows declared configuration extensibility +description: Learn more about Windows declared configuration extensibility through native WMI providers. +ms.date: 08/16/2024 ms.topic: how-to --- # Declared configuration extensibility providers -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. @@ -235,12 +235,12 @@ The `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource` function does the 1. Clean up resources, for example, free allocated memory. -## Declared Configuration document +## WinDC document > [!IMPORTANT] -> The target of the scenario settings can only be device wide for extensibility. The CSP **scope** defined in `` and Declared Configuration **context** must be `Device`. +> 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 Declared Configuration document with the configuration data specified for extensibility. +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 @@ -402,13 +402,13 @@ This example retrieves the results of a configuration or inventory request: ## 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 index e0874b8d6fe..6f072c16a99 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -1,15 +1,15 @@ --- -title: Resource access overview -description: Learn more about configuring resource access using Declared Configuration -ms.date: 08/14/2024 +title: Windows declared configuration resource access +description: Learn more about configuring resource access using Windows declared Configuration. +ms.date: 08/16/2024 ms.topic: how-to --- # Declared configuration resource access -Resource Access (RA) 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. Declared Configuration 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. +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 Declared Configuration protocol. They provide a consistent and standardized approach to deploying and enforcing configurations. CSPs support various resource access scenarios, including: +[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) @@ -18,10 +18,10 @@ Resource Access (RA) is used to manage device configurations and enforce policie - [WiredNetwork CSP](mdm/wirednetwork-csp.md) - [RootCACertificates CSP](mdm/rootcacertificates-csp.md) -The [Declared Configuration](declared-configuration.md) 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 Declared Configuration, providing an extended method for managing devices through the cloud with enhanced scalability and efficiency. +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**: Declared Configuration 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. +- **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 @@ -37,9 +37,9 @@ These guidelines provide best practices and examples for developers and testers 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. -## Declared Configuration document +## 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 Declared Configuration document with the configuration data specified for resource accecss. +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 @@ -81,9 +81,9 @@ These `osdefinedscenario` values require the following tags and attributes. | `type` | Setting data type | > [!NOTE] -> The target of the scenario settings must match the Declared Configuration context. The CSP **scope** defined in `` and Declared Configuration **context** must both be either `Device` or `User`. +> 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="Declared Configuration resource access syntax"::: +> :::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="WinDC resource access syntax"::: ### osdefinedscenario examples @@ -107,7 +107,7 @@ The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration C ### Configure a VPNv2 profile for resource access -This example demostrates 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. +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 @@ -153,14 +153,14 @@ This example demostrates how to use the [VPNv2 CSP](mdm/vpnv2-csp.md) to configu ### Updating a VPNv2 profile for resource access -This example demonstrates how to use the same Declared Configuration **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile. +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 @@ -200,7 +200,7 @@ This example demonstrates how to use the same Declared Configuration **Document ### Getting the VPNv2 profile -This example demonstrates how to use `` to retrieve the results of the Declared configuration request. +This example demonstrates how to use `` to retrieve the results of the WinDC request. ```xml @@ -260,7 +260,7 @@ This example demonstrates how to use `` to retrieve the results of the Decl ``` > [!TIP] -> To understand the state values, see [Declared configuration states](mdm/declaredconfiguration-csp.md#declared-configuration-states). +> To understand the state values, see [WinDC states](mdm/declaredconfiguration-csp.md#declared-configuration-states). ### Deleting the VPNv2 profile @@ -289,7 +289,7 @@ This example demonstrates how to use `` to remove the configuration requ ## Resource Ownership -MDM-managed resources, such as a VPN profile, are transferred/migrated to Windows Declared Configuration management when a Declared Configuration document is sent to the device for the same resource. This resource stays under Declared Configuration management until the Windows Declared Configuration document is [deleted](mdm/declaredconfiguration-csp.md#delete-a-declared-configuration-document) or [abandoned](mdm/declaredconfiguration-csp.md#abandon-a-declared-configuration-document). Otherwise, when MDM tries to manage the same resource via the legacy MDM channel using SyncML, it fails with error 0x86000031. +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-declared-configuration-document) or [abandoned](mdm/declaredconfiguration-csp.md#abandon-a-declared-configuration-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).` @@ -302,7 +302,7 @@ The Bulk template data scenario extends beyond the regular [ClientCertificateIns 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 for dynamic nodes is sent later by the server. Each dynamic node might contain dynamic subnodes, such as the `@#pfxBlob#` and `#@pfxPassword#` nodes in this example. +- 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 @@ -388,7 +388,7 @@ In this example, there are two instances. Each instance defines values for **pfx 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 should be documented and include relevant status codes or messages for troubleshooting. +- Error Handling: Any errors encountered during the import process include relevant status codes or messages for troubleshooting. **Request**: diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index 111b3e39d3f..ac73cd5e283 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -1,35 +1,37 @@ --- -title: Declared configuration protocol -description: Learn more about using declared configuration protocol for desired state management of Windows devices. -ms.date: 08/14/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: 08/16/2024 ms.topic: overview --- -# What is the declared configuration protocol +# Windows declared configuration protocol overview -The declared configuration 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 device's declared configuration client stack processes these settings to achieve the desired state 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. +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. -- [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the Declared Configuration 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 follows the [MS-MDE2 protocol](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and uses 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. +WinDC enrollment involves two phases: -The declared configuration enrollment offers these desired state management features: +- [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. + +WinDC enrollment offers these desired state management features: - [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. -:::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the declared configuration model."::: +:::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the WinDC model."::: -Once a device is enrolled, 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. +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 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. +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. ## Supported platforms -Declared Configuration 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 joined devices](/entra/identity/devices/concept-directory-join) is supported for all versions of Windows 10/11. -Declared Configuration enrollment for [Microsoft Entra registered devices](/entra/identity/devices/concept-device-registration) is supported for Windows 10/11 with the following updates: +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) @@ -38,7 +40,7 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr ## Refresh interval -The Declared configuration refresh schedule is created whenever there's a Declared Configuration doc 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 Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc is marked in drifted state and a new sync session is triggered to notify there's a drift. +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: diff --git a/windows/client-management/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index ae7ef3991e8..8caa0d729af 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: 08/16/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](#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 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](#declared-configuration-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](#declared-configuration-oma-uri). @@ -730,9 +730,9 @@ 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 (`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. @@ -740,7 +740,7 @@ A declared configuration request is sent using an OMA-URI similar to `./Device/V The following URI is an example of a **Complete** request: `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document` -## Declared Configuration document +## WinDC document ```xml ``` -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](#hostcomplete) or an [inventory](#hostinventory) request. +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. This tag has the following attributes: @@ -765,16 +765,16 @@ This tag has the following attributes: | `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. | -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 the 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 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. The actual processing of the request pivots around the `osdefinedscenario` tag and the configuration data specified within the document. For more information, see: -- [Declared Configuration document for resource access](../declared-configuration-resource-access.md#declared-configuration-document) -- [Declared Configuration document for extensibility](../declared-configuration-extensibility.md#declared-configuration-document) +- [WinDC document for resource access](../declared-configuration-resource-access.md#windc-document) +- [WinDC document for extensibility](../declared-configuration-extensibility.md#windc-document) -## Declared configuration generic alert +## WinDC 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 @@ -797,11 +797,11 @@ 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. -## Declared configuration states +## WinDC states The following class defines the state values: @@ -840,11 +840,11 @@ enum class DCCSPURIState :unsigned long - [SyncML examples for resource access](../declared-configuration-resource-access.md#syncml-examples) - [SyncML examples for extensibility](../declared-configuration-extensibility.md#syncml-examples) -### Abandon a Declared Configuration document +### Abandon a WinDC document -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 Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration 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. +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 demonstrats how to abandon a Declared Configuration Document, by setting the **Abandoned** property to **1**. +This example demonstrates how to abandon a WinDC document, by setting the **Abandoned** property to **1**. ```xml @@ -867,11 +867,11 @@ This example demonstrats how to abandon a Declared Configuration Document, by se ``` -### Unabandon a Declared Configuration document +### 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 Declared Configuration management and blocking legacy MDM channel from managing the channels again. +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 Windows Declared Configuration Document, by setting the **Abandoned** property to **0**. +This example demonstrates how to unabandon a WinDC document, by setting the **Abandoned** property to **0**. ```xml @@ -894,7 +894,7 @@ This example demonstrates how to unabandon a Windows Declared Configuration Docu ``` -### Delete a Declared Configuration document +### 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. From 6577dc6cdea4970aa6386fc5e6ecff2eb08bedd9 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Fri, 16 Aug 2024 13:21:16 -0600 Subject: [PATCH 11/15] Fix problems --- .../declared-configuration-resource-access.md | 4 ++-- windows/client-management/index.yml | 2 +- windows/client-management/mdm/declaredconfiguration-csp.md | 6 +++--- windows/client-management/mdm/index.yml | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index 6f072c16a99..db8eac31154 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -260,7 +260,7 @@ This example demonstrates how to use `` to retrieve the results of the WinD ``` > [!TIP] -> To understand the state values, see [WinDC states](mdm/declaredconfiguration-csp.md#declared-configuration-states). +> To understand the state values, see [WinDC states](mdm/declaredconfiguration-csp.md#windc-states). ### Deleting the VPNv2 profile @@ -289,7 +289,7 @@ This example demonstrates how to use `` to remove the configuration requ ## 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-declared-configuration-document) or [abandoned](mdm/declaredconfiguration-csp.md#abandon-a-declared-configuration-document). Otherwise, when MDM tries to manage the same resource via the legacy MDM channel using SyncML, it fails with error 0x86000031. +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).` diff --git a/windows/client-management/index.yml b/windows/client-management/index.yml index 4cee76e2bbb..f600a15201f 100644 --- a/windows/client-management/index.yml +++ b/windows/client-management/index.yml @@ -15,7 +15,7 @@ metadata: ms.author: vinpa manager: aaroncz ms.date: 07/08/2024 - localization_priority: medium + ms.localizationpriority: medium # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new diff --git a/windows/client-management/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index 8caa0d729af..fc40da1810f 100644 --- a/windows/client-management/mdm/declaredconfiguration-csp.md +++ b/windows/client-management/mdm/declaredconfiguration-csp.md @@ -17,11 +17,11 @@ The primary MDM model is one where the MDM server is solely responsible for orch 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 WinDC server sends a configuration or an inventory WinDC document to the client through the [DeclaredConfiguration 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 WinDC 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 WinDC 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 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](#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). diff --git a/windows/client-management/mdm/index.yml b/windows/client-management/mdm/index.yml index cfa99b1a5ff..f1b84cf5069 100644 --- a/windows/client-management/mdm/index.yml +++ b/windows/client-management/mdm/index.yml @@ -10,7 +10,7 @@ metadata: ms.collection: - tier1 ms.date: 10/25/2023 - localization_priority: medium + ms.localizationpriority: medium # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new From 9604be8348fa340bff325691c69f7dbb96ed22f6 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Fri, 23 Aug 2024 16:09:14 -0600 Subject: [PATCH 12/15] Updates to discovery page --- .../client-management/declared-configuration-discovery.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md index ad0c3265f8b..39961529d8c 100644 --- a/windows/client-management/declared-configuration-discovery.md +++ b/windows/client-management/declared-configuration-discovery.md @@ -29,7 +29,7 @@ This article outlines the schema structure for the HTTP request and response bod | `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. | +| `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) @@ -128,7 +128,7 @@ This article outlines the schema structure for the HTTP request and response bod { "upn" : "johndoe@contoso.com", "emmDeviceId" : "00000000-0000-0000-0000-000000000000", - "enrollmentType" : "WPJ", + "enrollmentType" : "User", "osVersion" : "10.0.00000.0" } ``` @@ -193,5 +193,5 @@ WinDC enrollment requires different authentication mechanisms for Microsoft Entr ## Error handling -- **UPNRequired**: If no UPN value is provided in the discovery request, the DS can set the `errorCode` in the response to trigger the client to retry the request with a UPN value provided. +- **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 From 63a4ac27e751bdedf6f89bcad8f2254ada0fdcaf Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Fri, 6 Sep 2024 12:45:17 -0600 Subject: [PATCH 13/15] TOC update --- windows/client-management/mdm/toc.yml | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index 7c6638b5725..dc13faca458 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -46,11 +46,14 @@ items: - name: Declared Configuration items: - name: Declared Configuration protocol - href: ../declared-configuration.md - - name: Declared Configuration discovery - href: ../declared-configuration-discovery.md - - name: Declared Configuration enrollment - href: ../declared-configuration-enrollment.md + expanded: true + items: + - name: Protocol overview + href: ../declared-configuration.md + - name: Discovery + href: ../declared-configuration-discovery.md + - name: Enrollment + href: ../declared-configuration-enrollment.md - name: Declared Configuration extensibility href: ../declared-configuration-extensibility.md - name: Declared Configuration resource access From d513e1ce430d8c232a647cbddc0bd47b295a89a1 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Fri, 6 Sep 2024 12:51:23 -0600 Subject: [PATCH 14/15] More changes --- windows/client-management/mdm/toc.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index dc13faca458..eba37a1745f 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -45,18 +45,18 @@ items: href: ../server-requirements-windows-mdm.md - name: Declared Configuration items: - - name: Declared Configuration protocol + - name: Protocol expanded: true items: - - name: Protocol overview + - name: Overview href: ../declared-configuration.md - name: Discovery href: ../declared-configuration-discovery.md - name: Enrollment href: ../declared-configuration-enrollment.md - - name: Declared Configuration extensibility + - name: Extensibility href: ../declared-configuration-extensibility.md - - name: Declared Configuration resource access + - name: Resource access href: ../declared-configuration-resource-access.md - name: DeclaredConfiguration CSP href: declaredconfiguration-csp.md From 2519c1ad713f88723de150e3ccdb445c5027fa56 Mon Sep 17 00:00:00 2001 From: "Vinay Pamnani (from Dev Box)" Date: Thu, 12 Sep 2024 10:53:28 -0600 Subject: [PATCH 15/15] Feedback from Kevin --- .../declared-configuration-discovery.md | 6 ++--- .../declared-configuration-enrollment.md | 2 +- .../declared-configuration-extensibility.md | 6 ++--- .../declared-configuration-resource-access.md | 4 +-- .../declared-configuration.md | 27 ++++++++++++++++++- .../mdm/declaredconfiguration-csp.md | 2 +- 6 files changed, 36 insertions(+), 11 deletions(-) diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md index 39961529d8c..aabd1dd644c 100644 --- a/windows/client-management/declared-configuration-discovery.md +++ b/windows/client-management/declared-configuration-discovery.md @@ -1,7 +1,7 @@ --- title: Windows declared configuration discovery description: Learn more about configuring discovery for Windows declared configuration enrollment. -ms.date: 08/16/2024 +ms.date: 09/12/2024 ms.topic: how-to --- @@ -21,7 +21,7 @@ This article outlines the schema structure for the HTTP request and response bod | `client-request-id: %s` | No | Request ID | | `Content-Type: application/json` | Yes | HTTP Content-Type | -### HTTP Request Body (JSON) +### HTTP request body (JSON) | Field | Required | Description | |--|--|--| @@ -32,7 +32,7 @@ This article outlines the schema structure for the HTTP request and response bod | `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) +### HTTP DS response body (JSON) | Field | Required | Description | |------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/windows/client-management/declared-configuration-enrollment.md b/windows/client-management/declared-configuration-enrollment.md index cfab4852574..45ba4643d23 100644 --- a/windows/client-management/declared-configuration-enrollment.md +++ b/windows/client-management/declared-configuration-enrollment.md @@ -1,7 +1,7 @@ --- title: Windows declared configuration enrollment description: Learn more about configuring enrollment for Windows declared configuration protocol. -ms.date: 08/16/2024 +ms.date: 09/12/2024 ms.topic: how-to --- diff --git a/windows/client-management/declared-configuration-extensibility.md b/windows/client-management/declared-configuration-extensibility.md index 6dcebc35b30..bb2faea5f1d 100644 --- a/windows/client-management/declared-configuration-extensibility.md +++ b/windows/client-management/declared-configuration-extensibility.md @@ -1,11 +1,11 @@ --- title: Windows declared configuration extensibility description: Learn more about Windows declared configuration extensibility through native WMI providers. -ms.date: 08/16/2024 +ms.date: 09/12/2024 ms.topic: how-to --- -# Declared configuration extensibility providers +# Declared configuration extensibility 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. @@ -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 MI Provider +## Example MI provider This example provides more details about each step to demonstrate how to implement a sample native resource named `MSFT_FileDirectoryConfiguration`. diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index db8eac31154..d414e05b958 100644 --- a/windows/client-management/declared-configuration-resource-access.md +++ b/windows/client-management/declared-configuration-resource-access.md @@ -1,7 +1,7 @@ --- title: Windows declared configuration resource access description: Learn more about configuring resource access using Windows declared Configuration. -ms.date: 08/16/2024 +ms.date: 09/12/2024 ms.topic: how-to --- @@ -287,7 +287,7 @@ This example demonstrates how to use `` to remove the configuration requ ``` -## Resource Ownership +## 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. diff --git a/windows/client-management/declared-configuration.md b/windows/client-management/declared-configuration.md index ac73cd5e283..a0a28f91ae1 100644 --- a/windows/client-management/declared-configuration.md +++ b/windows/client-management/declared-configuration.md @@ -1,7 +1,7 @@ --- title: Windows declared configuration protocol description: Learn more about using Windows declared configuration (WinDC) protocol for desired state management of Windows devices. -ms.date: 08/16/2024 +ms.date: 09/12/2024 ms.topic: overview --- @@ -105,3 +105,28 @@ To identify, adjust or remove the refresh schedule, use the **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/mdm/declaredconfiguration-csp.md b/windows/client-management/mdm/declaredconfiguration-csp.md index fc40da1810f..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: 08/16/2024 +ms.date: 09/12/2024 ---