diff --git a/windows/client-management/declared-configuration-discovery.md b/windows/client-management/declared-configuration-discovery.md index b2d548ff93..f5799106bd 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** +| 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 | -- `"(MS-CV: %s)"` - - Required: false - - Description: Correlation vector for enrollment +### HTTP Request Body (JSON) -- `"(client-request-id: %s)"` - - Required: false - - Description: Request ID +| 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. | -**Content-Type Header** +### HTTP DS Response Body (JSON) -- `"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 +| 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. +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. -- Microsoft Entra joined devices use 'Federated' authentication (Entra device token) -- Microsoft Entra registered devices use 'Certificate' authentication (MDM certificate provisioned for the parent enrollment). +- **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 -Rules are: +- **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] `"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 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 (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. +- **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 bea26d63cf..9e7e2c3c5b 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 7b1f9991f8..660308e800 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 df463687d9..050d03d6f2 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 8853724d33..1a2347025d 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 3cbe25c38c..7c6638b572 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