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.

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.

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 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 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.