Custom CSP configuration

Introduction #

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

With the new custom configuration feature in Relution, any combination of CSP policies can be defined and applied to Windows devices as one more “Custom CSP” configurations. This means that the functionality available through the MDM interface is oly limited by the capabilities of the supported CSPs. Microsoft continuously adds new CSP policies. An overview of these can be found here in the official Microsoft documentation.

Important Notes #

When working with custom CSP configuration, please note that the configurations are not implemented by Relution. As such, Relution cannot guarantee their effectiveness or we prevent potential damage to devices. Please carefully review and test the CSPs before applying them to a device. For further guidance, see Best practices.

Also note that some CSPs may already be used internally by Relution. In such cases, conflicts can occur that may compromise Relution-managed configurations.

Functionality #

General #

Not all CSP policies can be applied to every device. They depend on the Windows edition and operating system version. Relevant details are provided in the documentation of each individual CSP. If a device does not meet the requirements, deployment of the CSP policy will fail.

CSP policies can be applied in the device context or user manual. Please note that the user context only applies to the user who enrolled the device. Therefore, it is generally recommended to use CSP policies in the device context.

Not all SyncML commands are supported for every CSP. Some CSPs may be read-only and only support 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 several specifics that need to be considered for the deployment of the configuration.

Some CSP policies must initially be applied using the Add command. For subsequent deployments of the configuration (updates), the Add command may fail if the setting already exists. In such cases, the Replace command must be sent instead, see also Best Practices.

Delete #

A CSP policy can be removed by issuing a Delete command on the specific node. In some cases, it is also possible to deleta a parent or root node. In these cases, all CSP policies under the deleted node will be removed.

If the deletion fails, the affected CSP policies remain active on the device. In that case, the Delete SyncML must be adjusted accordingly. After that, the policy should be reapplied and then removed again.

Atomic and Sequence #

The Sequence command allows multiple CSP policies to be grouped and executed sequentially within it. However, if one policy fails, the remaining ones will still applied. This can lead to inconsistent or unintended behavior. Additionally, the failed CSP policy may need to be explicitly removed.

When the SyncML is executed within an Atomic command, the entire command will be rolled back if any single CSP policy fails. This ensures that either all changes are applied or none at all. Therefore, the Atomic command is preferred and, for the time being, is the only one supported.

In Relution #

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

Each configuration requires two SyncML commands: one for installing or updating the configuration, and one for removing it. When publishing the configuration multiple times, ensure that the Install SyncML command is updated accordingly.

The “Custom CSP” configuration includes the following properties:

Relution automatically extends the specified SyncML to ensure the configuration can be properly applied, evaluated, and its status displayed in Relution:

• If the specified SyncML contains <Format> or <Type>, the required namespace will be added automatically after saving the configuration.
• An Atomic will be wrapped around the specified SyncML. This is necessary to associate the device response withe the correct configuration. This occurs when the configuration is delivered. In the future, there will be an option to wrap the specified SyncML in a Sequence instead of an Atomic. This might be required for the use of certain CSPs that are not compatible with an Atomic.
• The SyncML will be automatically wrapped with the required SyncBody, SyncHdr, and SyncML elements to ensure the message is complianct and can be processed by the device. This also occurs at the time of delivery.

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>0</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>
  </Item>
</Delete>

Best Practices #

• An update of the configuration can be applied thrby creating a new policy version (possibly with an adjusted Install SyncML).
• If deletion fails, the included CSP policies will remain active on the device. AIn this case, the Delete SyncML mus be revised, and the policy should be reapplied and then removed again.
• It is recommended to use Replace instead of Add unless the corresponding CSP policy does not support it.
• If a Replace command is not permitted for the initial deployment of a CSP policy, it is recommended to first apply the configuration using an Add command. Afterwards, update the configuration’s Install SyncML (use Replace instead of Add) and deploy it again using a new policy version.
• It is recommended to extensively test the desired behavior on suitable test devices. At a minimum, the following scenarios should be tested:
  • Initial deployment of the configuration
  • Updating the configuration
  • Deleting the configuration

Sample Policies #

A comprehensive example of custom policies has been published on the Relution Community Board: Relution Community Board - Custom CSP.

Many thanks to the community for this valuable contribution.