Custom Configuration

What is Custom Configuration

Custom Configuration allows you to deploy raw Apple Property List (plist) XML as a configuration profile payload. This is the escape hatch for any setting that Apple's MDM protocol supports but that does not have a dedicated UI in the Blueprint editor.

Every configuration profile Apple devices consume is an XML plist. The Blueprint editor abstracts the most common payload types (Passcode, Restrictions, WiFi, etc.) into form fields. Custom Configuration skips the abstraction — you write the plist payload directly.

When to Use It

• Apple Configurator 2 workflows — You have an existing .mobileconfig file exported from Apple Configurator 2. Paste the relevant payload section into Custom Configuration instead of rebuilding it field by field.
• Advanced settings not in the UI — Apple adds new payload keys with every OS release. The Blueprint editor may not yet have a form for a newly introduced key. Custom Configuration bridges that gap immediately.
• Nested or complex payloads — Some payloads (e.g., custom XML, raw JSON embedded in a plist) are impractical to represent as individual form fields.
• Third-party MDM extensions — Vendor-specific payloads that extend Apple's schema.

How to Create a Custom Plist Payload

1. Navigate to Configuration Management > Blueprints and open the target Blueprint.
2. Click Add Configuration and select Custom Configuration.
3. Choose the target platform (iOS/iPadOS, macOS, tvOS).
4. Paste your plist XML into the editor.

The payload must be a valid Apple plist dictionary. At minimum it requires a PayloadType and PayloadIdentifier:

<?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>PayloadType</key>
    <string>com.apple.security.firewall</string>
    <key>PayloadIdentifier</key>
    <string>com.example.firewall.custom</string>
    <key>PayloadUUID</key>
    <string>a1b2c3d4-e5f6-7890-abcd-ef1234567890</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadDisplayName</key>
    <string>Custom Firewall Rules</string>
    <!-- Your payload-specific keys here -->
</dict>
</plist>

Key Fields

Key	Required	Description
PayloadType	Yes	The Apple payload type identifier (e.g., com.apple.security.firewall, com.apple.applicationaccess)
PayloadIdentifier	Yes	A reverse-DNS unique identifier for this payload
PayloadUUID	Yes	A unique UUID for this payload instance
PayloadVersion	Yes	Payload version number (typically 1)
PayloadDisplayName	No	Human-readable name shown on the device in Settings > General > VPN & Device Management
PayloadDescription	No	Description shown on the device
PayloadOrganization	No	Organization name shown on the device

Finding Payload Types

Apple publishes the full list of supported payload types and their keys in the Apple Configuration Profile Reference. Common types include:

PayloadType	Purpose
com.apple.applicationaccess	Restrictions
com.apple.security.firewall	macOS firewall
com.apple.MCX	macOS preference mapping
com.apple.wifi.managed	Wi-Fi network
com.apple.vpn.managed	VPN configuration
com.apple.security.scep	SCEP certificate enrollment
com.apple.dnsSettings.managed	DNS settings

XML Syntax Validation in the Editor

The Custom Configuration editor includes built-in XML syntax validation. As you type, the editor checks for:

• Well-formed XML — Matching tags, proper nesting, valid characters.
• Plist structure — The root element must be a <plist> with a <dict> child.
• Required keys — PayloadType, PayloadIdentifier, PayloadUUID, and PayloadVersion must be present.

Invalid XML is flagged with an inline error indicator. The Blueprint cannot be saved while a Custom Configuration payload has syntax errors.

Testing and Deploying Custom Configurations

1. Validate in the editor — Ensure no syntax errors are shown before saving.
2. Save the Blueprint — The system compiles the Blueprint into a configuration profile and queues it for delivery.
3. Assign to a test group — Deploy to a small group of test devices first.
4. Verify on device — Check that the profile installed under Settings > General > VPN & Device Management (iOS) or System Settings > Privacy & Security > Profiles (macOS).
5. Check MDM logs — Review the device command logs in the dashboard to confirm the profile was delivered and installed without errors.
6. Roll out broadly — Once verified, assign the Blueprint to production groups.

Warning: Advanced Feature

Custom Configuration is an advanced feature intended for administrators who understand Apple's configuration profile schema. Mistakes in the plist XML can cause:

• Profile installation failures
• Unexpected device behavior
• Settings that cannot be removed without wiping the profile

Know what you are doing. If you are unsure about a payload key or value, test on a non-production device first. When a supported UI exists for a setting, prefer the form-based configuration over raw XML — it provides validation, guardrails, and future-proofing against schema changes.