Custom CSP configuration

Introduction #

The MDM interface utilizes Configuration Service Provider (CSP) policies for managing Windows devices. These are applied, deleted, and queried on the device using the SyncML Protocol, a special XML format. The list of available CSP policies can be found in the official Microsoft MDM documentation.

With the new custom configuration, any CSP policies can be combined into a single or multiple “Custom CSP” configurations and applied to Windows devices. Thus, the applicable functionalities via the MDM interface are only limited by the available CSP policies. Microsoft continuously adds new CSP policies. An overview of these can be found here in the official Microsoft documentation.

Important Notes #

When working with the Custom CSP configuration, the configuration is not implemented by Relution, therefore we do not guarantee against any potential damage. Please carefully check the CSPs before applying them to a device, see Best practices.

It is possible that the CSPs you are using are also used by Relution itself. In this case, there may be interactions that could damage configurations provided by Relution.

Functionality #

General #

Not all CSP policies can be applied to every device. They depend on the operating system version and edition. The relevant information can be found in the respective CSP policies. If a device is not supported, the deployment of that CSP policy will fail.

CSP policies can be applied in the device or user context. It should be noted that the user context only applies to the user who performed the enrollment. Therefore, it is recommended to use CSP policies only in the device context.

CSP policies do not support all SyncML commands. Some CSP policies may only be used for querying (e.g., the Get command).

Example: To allow or block Cortana on a device (already included in the Relution configuration Restrictions), the following CSP can be used. Policy CSP/Experience/AllowCortana

• This CSP can be used for all editions and from version 1507 onwards.
• Only the device context is supported.
• These SyncML commands are allowed: Add (Add), Delete (Delete), Get (Get), Replace (Replace)

SyncML Specifics #

Add and Replace #

SyncML contains various specifics that need to be considered for the deployment of the configuration.

Some CSP policies must be added with the Add command when applied for the first time. For all subsequent deployments of the configuration (updates), this Add command might fail. Instead, a Replace command must be sent, see also Best Practices.

Delete #

Deleting a CSP policy can either be done directly on the respective CSP policy. In some cases, a Delete command is also possible on the parent or root node. In these cases, all CSP policies under the deleted node will be removed.

If the deletion fails, the contained CSP policies remain active on the device. Adjustment of the Delete SyncML is required, as well as reapplying and then removing the policy.

Atomic and Sequence #

With the Sequence command, individual CSP policies can be grouped and executed sequentially within it. However, if a single CSP policy within it fails, all other CSP policies will still be applied. This can lead to undesired behavior, and the failed CSP policy may need to be explicitly removed.

If the SyncML is executed within an Atomic command, the entire command will be rolled back if any single CSP policy fails. Thus, either the entire configuration is applied, or none of it is. Therefore, the Atomic command is preferred.

In Relution #

In Relution, the new configuration must be created and added to a device group in order to be applied to a Windows device.

The configuration requires two SyncML commands. One for installing or updating the configuration and one for deleting the configuration. When repeatedly publishing the configuration, ensure that the values of the installation command have been adjusted accordingly.

The “Custom CSP” configuration includes the following properties:

Relution must extend the specified SyncML to apply the configuration on the device, evaluate it afterwards, and display a status in Relution.

• If the specified SyncML contains <Format> or <Type>, these will be expanded with a required namespace. This happens automatically after saving the configuration.
• An Atomic or Sequence will be wrapped around the specified SyncML. This is necessary to identify which configuration the device’s response belongs to. This occurs when the configuration is delivered.
• The SyncML will be extended with SyncBody, SyncHdr, and SyncML so that the SyncML can be sent to the device in a compliant manner. This occurs when the configuration is delivered.

Examples #

Policy CSP/Experience/AllowCortana

• Allow Cortana

Install SyncML:

<Replace>
  <CmdID>1</CmdID>
  <Item>
    <Target>
      <LocURI>./Device/Vendor/MSFT/Policy/Config/Experience/AllowCortana</LocURI>
    </Target>
    <Meta>
      <Format>int</Format>
    </Meta>
    <Data>1</Data>
  </Item>
</Replace>

• Block Cortana

Install SyncML:

<Replace>
  <CmdID>1</CmdID>
  <Item>
    <Target>
      <LocURI>./Device/Vendor/MSFT/Policy/Config/Experience/AllowCortana</LocURI>
    </Target>
    <Meta>
      <Format>int</Format>
    </Meta>
    <Data>1</Data>
  </Item>
</Replace>

• Remove the CSP policy AllowCortana from the device

Delete SyncML:

<Delete>
  <CmdID>1</CmdID>
  <Item>
    <Target>
      <LocURI>./Device/Vendor/MSFT/Policy/Config/Experience/AllowCortana</LocURI>
    </Target>
</Delete>

Best practices #

• An update of the configuration can be applied through a new policy version (possibly with adjusted Install SyncML).
• If deletion fails, the included CSP policies remain active on the device. An adjustment of the Delete SyncML is required, as well as reapplying and then removing the policy.
• It is recommended to always use Wrap in Atomic to maintain the rollback behavior for this configuration, see Atomic and Sequence.
• It is recommended to use Replace instead of Add unless it is not supported for the corresponding CSP policy.
• If a Replace command is not allowed for the initial deployment of a CSP policy, it is recommended to initially apply this configuration using an Add command. Then update the configuration’s Install SyncML (use Replace instead of Add) and apply it on the device through a new policy version.
• It is recommended to extensively test the desired behavior on suitable test devices. At a minimum, the following behaviors should be tested:
  • Initial deployment of the configuration
  • Updating the configuration
  • Deleting the configuration