diff --git a/windows/client-management/declared-configuration-resource-access.md b/windows/client-management/declared-configuration-resource-access.md index 52d285342c..df463687d9 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. +Only supported values for `osdefinedscenario` 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 +| osdefinedscenario | Recommended using with | +|------------------------------|-------------------------------| +| MSFTWiredNetwork | WiredNetwork | +| MSFTResource | ActiveSync | +| MSFTVpn | VPN and VPNv2 | +| MSFTWifi | Wifi | +| MSFTInventory | Certificate inventory | +| MSFTClientCertificateInstall | SCEP, PFX, Bulk Template Data | -### Adding a VPNv2 profile for resource access +Examples: -This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to enable the **Always On** mode for a VPN Profile on the device. +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 e12a89b7ca..db039f3109 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 5614e38ee4..48de402dbf 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