# How to deploy custom configuration profiles to iOS devices?

Deploy Custom Configuration in Hexnode UEM uploads and distributes Apple configuration profiles to managed iOS and iPadOS devices over the air. A configuration profile is a non-encrypted .mobileconfig, .xml, or .plist file containing Apple property list payloads that configure device behavior. IT administrators use this workflow when Hexnode UEM does not provide a dedicated policy setting for a required Apple payload, or when an organization needs to distribute a validated custom profile across multiple enrolled devices.

 Note: 
You can deploy non-encrypted .mobileconfig, .xml, or .plist files across iOS/iPadOS devices.

 

How Custom Configuration Profile Deployment Works in Hexnode UEM
----------------------------------------------------------------

Custom configuration profiles are created outside Hexnode UEM using Apple Configurator, profile editor apps, or similar tools that can generate Apple configuration profile payloads. After the profile is created and verified, upload it to a Hexnode UEM policy under **iOS > Configurations > Deploy Custom Configuration** and associate the policy with the required targets.

Hexnode UEM distributes the uploaded profile to the selected devices, device groups, users, user groups, or domains. The profile applies only to devices that match the supported platform and supervision requirements defined by the payload.

Deploy a Custom Configuration Profile from Hexnode UEM
------------------------------------------------------

 Use the following steps to upload a custom configuration profile and distribute it through a Hexnode UEM policy.

1. Log in to the Hexnode UEM console.
2. Go to **Policies** > **New Policy**.
3. Enter a policy name and, optionally, a description.
4. Go to **iOS** > **Configurations** > **Deploy Custom Configuration**.
5. Click **Configure**, and then select **Choose File**.
6. Upload a new file by clicking **Choose file** followed by **Upload**, or select a custom configuration profile that is already uploaded to the Hexnode UEM portal.
7. Click **OK**.
8. Navigate to **Policy Targets**.
9. Associate the policy with the required devices, device groups, users, user groups, or domains, and click **OK**.
10. Click **Save**.

Sample .plist File for an AirDrop Configuration Profile
-------------------------------------------------------

The following sample .plist configuration profile illustrates the expected Apple property list format for enforcing Contacts Only for AirDrop.

 Note: 
The UUIDs in this sample are placeholders in the required UUID format and are not associated with any iOS device.

 

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>PayloadContent</key> <array> <dict> <key>DiscoverableMode</key> <string>Contacts Only</string> <key>PayloadEnabled</key> <true/> <key>PayloadIdentifier</key> <string>com.apple.sharingd.abcd1234-ab01-12ab-ab0c-acbdef123456</string> <key>PayloadType</key> <string>com.apple.sharingd</string> <key>PayloadUUID</key> <string>abcd1234-ab01-12ab-ab0c-abcdef123456</string> <key>PayloadVersion</key> <integer>1</integer> </dict> </array> <key>PayloadDescription</key> <string>Lock Airdrop to Contacts Only</string> <key>PayloadDisplayName</key> <string>Airdrop Settings</string> <key>PayloadIdentifier</key> <string>com.apple.sharingd</string> <key>PayloadOrganization</key> <string>TEST</string> <key>PayloadRemovalDisallowed</key> <true/> <key>PayloadScope</key> <string>System</string> <key>PayloadType</key> <string>Configuration</string> <key>PayloadUUID</key> <string>00a12345-b0c1-23d4-1234-ef0g1h2ij345</string> <key>PayloadVersion</key> <integer>1</integer> </dict> </plist> 

   1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

  <?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

<key>PayloadContent</key>

<array>

<dict>

<key>DiscoverableMode</key>

<string>Contacts Only</string>

<key>PayloadEnabled</key>

<true/>

<key>PayloadIdentifier</key>

<string>com.apple.sharingd.abcd1234-ab01-12ab-ab0c-acbdef123456</string>

<key>PayloadType</key>

<string>com.apple.sharingd</string>

<key>PayloadUUID</key>

<string>abcd1234-ab01-12ab-ab0c-abcdef123456</string>

<key>PayloadVersion</key>

<integer>1</integer>

</dict>

</array>

<key>PayloadDescription</key>

<string>Lock Airdrop to Contacts Only</string>

<key>PayloadDisplayName</key>

<string>Airdrop Settings</string>

<key>PayloadIdentifier</key>

<string>com.apple.sharingd</string>

<key>PayloadOrganization</key>

<string>TEST</string>

<key>PayloadRemovalDisallowed</key>

<true/>

<key>PayloadScope</key>

<string>System</string>

<key>PayloadType</key>

<string>Configuration</string>

<key>PayloadUUID</key>

<string>00a12345-b0c1-23d4-1234-ef0g1h2ij345</string>

<key>PayloadVersion</key>

<integer>1</integer>

</dict>

</plist> 

   

 

  

Requirements and Limitations for Custom Configuration Profiles
--------------------------------------------------------------

- If a custom configuration profile is associated with a device belonging to another platform, the **Action History** tab shows the status as **Success**. However, the policy configuration applies only to devices that match the prescribed platform.
- Configurations meant for supervised devices fail when applied to unsupervised devices. The device **Action History** tab displays a **Failed** status for that deployment.
- While defining a profile, ensure that it contains all mandatory payload keys, including `PayloadUUID`, `PayloadType`, `PayloadVersion`, and `PayloadIdentifier`.
- Binary `.plist` files cannot be used to deploy custom configuration profiles. Convert binary `.plist` files to XML property list format before uploading them. For example, use `plutil -convert xml1 <name-of-the-plist-file>`.
- Generic `.plist` files alone cannot be used to deploy custom configuration profiles. Choose an appropriate payload, add [Apple profile-specific payload keys](https://developer.apple.com/documentation/devicemanagement/profile-specific-payload-keys) to the configuration profile, and verify the profile before uploading it.
- Before distributing configuration profiles to devices, make sure that conflicting configurations are not pushed to the same target.
- You can use Hexnode UEM [wildcards](https://www.hexnode.com/mobile-device-management/help/how-to-pass-device-and-user-information-using-the-wildcards-supported-by-hexnode-mdm/#) for custom configuration profiles while deploying custom configuration profiles.

Validate and Troubleshoot Custom Configuration Profile Deployment
-----------------------------------------------------------------

After saving the policy, use the device **Action History** tab in Hexnode UEM to verify whether the custom configuration profile deployment succeeded or failed.

### Profile Shows Success but Does Not Apply to the Device

If the policy is associated with devices from unsupported platforms, Hexnode UEM may show **Success** in **Action History**, but the custom configuration profile applies only to devices that match the payload platform. Review the policy targets and confirm that the selected devices are iOS/iPadOS devices supported by the uploaded profile.

### Profile Fails on an Unsupervised Device

If a payload requires supervision and the target device is unsupervised, Hexnode UEM shows a **Failed** status in the device **Action History** tab. Verify the supervision requirement for the payload before deploying it to production devices.

### Profile Upload or Installation Fails Because of Payload Format

A custom configuration profile must include the required Apple payload keys and use a supported non-encrypted file format. Check the profile for mandatory keys such as `PayloadUUID`, `PayloadType`, `PayloadVersion`, and `PayloadIdentifier`, and convert binary `.plist` files to XML property list format before uploading them.