Skip to content

Managed Preferences

Jump to bottom
MDM Magic edited this page Nov 11, 2026 · 2 revisions

Managed Preferences

Configure Magic Toolbox for every Mac in your organisation with a configuration profile. Use it to activate a licence, turn on Entra ID sign-in, choose which tools people can see, require a PIN for risky tools, pre-fill your Jamf Pro server, brand reports, lock the appearance and add app shortcuts to the Home screen.

These settings need Magic Toolbox 1.1.0 or later.

Settings from a profile are managed: they win over anything set on the Mac, and people can't change them. Where a managed setting also appears in Preferences, it's shown with a Managed lock and can't be edited.
Preference domain au.mdmmagic.MagicToolbox
Payload type Custom Settings (com.apple.ManagedClient.preferences)
Scope Computer level

Every key is optional. Leave a key out and the app behaves as it does without a profile.

Build the profile in Jamf Pro

  1. Copy the example plist below into a text editor, and save it as au.mdmmagic.MagicToolbox.plist.
  2. Change the values to suit your organisation: your tenant and client IDs, your Entra group names and the tools each group gets. Remove any keys you don't need. The key reference explains each one.
  3. Check the file is valid. In Terminal: 
    plutil -lint au.mdmmagic.MagicToolbox.plist
    It should say OK.
  4. In Jamf Pro, go to Computers → Configuration Profiles and click New.
  5. On the General payload, give the profile a name, for example Magic Toolbox Settings, and set Level to Computer Level.
  6. Choose the Application & Custom Settings payload, then Upload, and click Add.
  7. For Preference Domain, enter au.mdmmagic.MagicToolbox exactly. Upload your plist, or paste its contents into the property list field.
  8. On the Scope tab, add the Macs or groups that use Magic Toolbox, then click Save.

Settings apply the next time Magic Toolbox opens. If it's already open, quit it from the menu bar icon and open it again.

Tip: keep the plist in source control. Group names and tool lists are easy to get wrong, and a history makes it easy to see what changed.

Build the profile for another MDM

If your MDM wants a whole .mobileconfig file, wrap your keys in a Custom Settings payload like this:

<?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>PayloadContent</key>
            <dict>
                <key>au.mdmmagic.MagicToolbox</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <!-- Your keys go here, for example: -->
                                <key>EntraTenantID</key>
                                <string>00000000-0000-0000-0000-000000000000</string>
                                <key>EntraClientID</key>
                                <string>11111111-1111-1111-1111-111111111111</string>
                                <key>EntraGroupMappings</key>
                                <dict>
                                    <key>MT-FullAccess</key>
                                    <array>
                                        <string>*</string>
                                    </array>
                                </dict>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
            <key>PayloadDisplayName</key>
            <string>Magic Toolbox Preferences</string>
            <key>PayloadIdentifier</key>
            <string>au.mdmmagic.MagicToolbox.prefs</string>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadUUID</key>
            <string>REPLACE-WITH-UUIDGEN-OUTPUT-1</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
        </dict>
    </array>
    <key>PayloadDisplayName</key>
    <string>Magic Toolbox Configuration</string>
    <key>PayloadIdentifier</key>
    <string>au.mdmmagic.MagicToolbox.config</string>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>REPLACE-WITH-UUIDGEN-OUTPUT-2</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>
  • Replace the two PayloadUUID values with two different UUIDs. Run uuidgen in Terminal once for each.
  • Check the file with plutil -lint, then open it in Profile Inspector to see every setting it contains.
  • To sign it, use Profile Signer.

Test on one Mac first

You can try a plist on your own Mac before deploying it. macOS treats a file in /Library/Managed Preferences the same way as one delivered by MDM:

sudo cp au.mdmmagic.MagicToolbox.plist "/Library/Managed Preferences/"
sudo chmod 644 "/Library/Managed Preferences/au.mdmmagic.MagicToolbox.plist"

Quit Magic Toolbox and open it again. If the settings don't show up, run sudo killall cfprefsd, then open the app again.

To remove it:

sudo rm "/Library/Managed Preferences/au.mdmmagic.MagicToolbox.plist"

On a Mac that's enrolled in MDM, the MDM can replace or remove this file at any time, so use a test Mac that isn't receiving a Magic Toolbox profile.

Check what a Mac has received

defaults read "/Library/Managed Preferences/au.mdmmagic.MagicToolbox"

This shows the managed settings exactly as the app sees them. If nothing comes back, the profile hasn't reached the Mac, or the preference domain is spelled wrong.

Key reference

Entra ID

See Entra ID for setting up the app registration and groups.

Key Type What it does
EntraTenantID String Your Entra tenant ID (a GUID) or a verified domain such as example.onmicrosoft.com. Required for Entra sign-in
EntraClientID String The Application (client) ID of your Magic Toolbox app registration. Required for Entra sign-in
EntraGroupMappings Dictionary Maps Entra group names to the tools members can use. Each key is a group's display name. Each value is an array of tool names, or * for every tool. Someone in several groups gets every tool from all of them
ShowEntraSignIn Boolean Shows (true) or hides (false) the Sign In button in the title bar. Leave it out to let people choose in Preferences. The default is true

Entra sign-in is switched on only when both EntraTenantID and EntraClientID are set. Once it is, nobody sees any tools until they sign in.

Don't set ShowEntraSignIn to false unless people are already signed in. Without the button, nobody can sign in, so nobody sees any tools.

Tool visibility

Key Type What it does
AllowedTools Array of strings Only these tools appear. Every other tool is hidden. Leave it out for no restriction
HiddenCategories Array of strings Hides whole categories: Jamf Pro Tools, Audit & Health Check, Profile Builders or Content & Packages
LockedTools Array of strings These tools always ask for the Tool Lock PIN before they open, every time. They show a shield lock on the Home screen

About LockedTools: the PIN is the Tool Lock PIN set on that Mac. If no PIN has been set, a locked tool can't be opened until someone sets one in Preferences → Tool Lock. Like Tool Lock itself, this protects against casual use. It isn't a security boundary.

Appearance and the title bar

Key Type What it does
LockAppearance String auto (follow macOS), light or dark. Hides the appearance button in the title bar, and the Appearance setting in Preferences has no effect
HideDebugLog Boolean true hides the Debug Log button in the title bar. Debug logging is still available from Preferences
HideAdditionalTools Boolean true hides the Additional MDM Magic Tools section on the Home screen
HidePreferences Boolean true hides the About (?) button in the title bar. Preferences can still be opened with ⌘, and from the menu bar icon

Custom Applications

Key Type What it does
CustomApplications Array of dictionaries App shortcuts that always appear in the Custom Applications section on the Home screen. Each entry needs a name (the tile label) and a path (the full path to the .app). People can't remove them
AllowUserCustomApps Boolean false stops people adding their own shortcuts, so only the apps in CustomApplications appear. The default is true

If an app in CustomApplications isn't installed on a Mac, its tile is still shown but marked as not installed.

Licensing

Key Type What it does
LicenseKey String A licence key in the form MAGIC-XXXXXXXX-XXXXXXXX-XXXXXXXX. Magic Toolbox activates it automatically when it opens, and people can't change or deactivate it

How it works:

  • At each launch, if the key in the profile isn't the one already active on this Mac, the app activates it in the background. Activation needs an internet connection and works the same way as entering a key by hand: it links the key to this Mac.
  • Once it's active, the toolbar badge shows Licensed, and About (?) shows Organisation License: Managed by your IT department. The key isn't shown, and there's no Deactivate button.
  • The licence is then checked and renewed like any other. See Working offline.
  • If activation fails, for example because the Mac is offline or the key is in use on another Mac, no error is shown. The badge keeps showing the trial, and the app tries again at the next launch. Once the trial has ended, the activation screen appears.

Each key is active on one Mac at a time. A profile with one LicenseKey scoped to ten Macs activates on the first Mac that opens the app, and fails on the other nine. Give each Mac its own key. See Deploying a key to each Mac.

Removing the key. If you remove LicenseKey from the profile, the licence stays active on the Mac, and the normal licence controls come back in About (?). To free the key for another Mac, remove it from the profile, then click Deactivate in About (?) on that Mac while it's online.

Changing the key. If you change LicenseKey to a different key, the new key is activated at the next launch, but the old one isn't released and stays linked to that Mac. To reuse the old key elsewhere, remove LicenseKey from the profile and deactivate the old key first, then deploy the new one.

Keep keys private. Anyone who can log in to a Mac can read its managed preferences, including the licence key. Scope each key only to the Mac it belongs to.

Deploying a key to each Mac

In Jamf Pro, you can give every Mac its own key from one profile with a payload variable:

  1. Create a computer extension attribute, for example Magic Toolbox Licence Key, with Data Type String and Input Type Text Field. Note its ID number.
  2. On each Mac's inventory record, enter that Mac's licence key in the attribute.
  3. In the profile, set the key to the variable, using your attribute's ID in place of 42: 
    <key>LicenseKey</key>
<string>$EXTENSIONATTRIBUTE_42</string>

Jamf Pro fills in each Mac's own value when it sends the profile. Check Jamf's payload variable documentation for your Jamf Pro version. With other MDMs, use their equivalent per-device variable, or create one profile per Mac.

For volume licensing, email info@mdmmagic.au.

Jamf Pro defaults

Key Type What it does
DefaultJamfServerURL String Fills in the Jamf Pro Instance field when a tool's Connect step is empty, and when you add a new Saved Server. Example: https://your-instance.jamfcloud.com
DefaultJamfUsername String Fills in the username for username and password sign-in, in the same places. It doesn't fill in an API client ID
LockDefaultServer Boolean true stops people editing the server address in the Connect step and in Saved Servers. Only applies when DefaultJamfServerURL is also set

These only fill in an empty form. If someone has already saved credentials for a tool, or picks a Saved Server, the form shows those instead. With LockDefaultServer, that saved address is locked too, rather than being replaced with the default.

Report branding and support

Key Type What it does
OrganisationName String The organisation name on every exported HTML report. Overrides the name in Preferences → Report Branding, where the field shows Managed and can't be edited. The logo can still be set in Preferences
SupportContact String Adds a Contact IT Support link to About (?). Use an email address, which opens a new email, or a web address starting with https://, which opens in the browser

How the rules combine

When more than one setting affects a tool, the most restrictive one wins:

  1. HiddenCategories hides every tool in those categories.
  2. If Entra sign-in is on, the person sees only the tools their groups map to. Before signing in, or if they aren't in any mapped group, they see none.
  3. If AllowedTools is also set, they see only tools that are in both their Entra tools and AllowedTools.
  4. LockedTools doesn't hide anything. It adds a PIN prompt to tools that are already visible.

If Entra sign-in is on but EntraGroupMappings is left out, everyone who signs in sees every tool (subject to the other rules).

When every tool is hidden, the Home screen says Sign In Required if the person still needs to sign in, or No tools available if the profile has hidden everything.

Tool names

Tool names in AllowedTools, LockedTools and EntraGroupMappings must match these exactly, including capitals, spaces and &. A name that doesn't match is ignored.

Category Tool names
Jamf Pro Tools Clone, Compare, Wipe, Restore, Disable, Create, Command, Device Logs, Policy Scope, Pre-stage Audit, LAPS, MDM Command Queue, Self Service Descriptions
Audit & Health Check Profile Conflicts, Smart Group Audit, Account Audit, Cert & Token Expiry, Unused, Network Check, Script Auditor, Fleet Health, Extension Attributes, Self Service Audit
Profile Builders PPPC Analyser, System Extensions, Web Content Filter, Notifications, Login Item Profiles, Profile Signer, Profile Unsigner, Profile Inspector
Content & Packages Inspector, Downloader, Icons

In a plist file, write & as &amp;, for example <string>Cert &amp; Token Expiry</string>.

Example plist

This example activates a licence, turns on Entra sign-in with four groups, requires a PIN for the tools that change Jamf Pro in bulk, follows the macOS appearance, adds two app shortcuts, fills in and locks the Jamf Pro server, and brands reports. Every key, ID, name and address is a placeholder. Replace them with your own, and remember a LicenseKey works on one Mac at a time.

<?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>LicenseKey</key>
    <string>MAGIC-00000000-00000000-00000000</string>
    <key>EntraTenantID</key>
    <string>00000000-0000-0000-0000-000000000000</string>
    <key>EntraClientID</key>
    <string>11111111-1111-1111-1111-111111111111</string>
    <key>ShowEntraSignIn</key>
    <true/>
    <key>EntraGroupMappings</key>
    <dict>
        <key>MT-FullAccess</key>
        <array>
            <string>*</string>
        </array>
        <key>MT-Helpdesk</key>
        <array>
            <string>Command</string>
            <string>Device Logs</string>
            <string>LAPS</string>
            <string>MDM Command Queue</string>
            <string>Policy Scope</string>
            <string>Fleet Health</string>
            <string>Network Check</string>
        </array>
        <key>MT-Auditors</key>
        <array>
            <string>Account Audit</string>
            <string>Cert &amp; Token Expiry</string>
            <string>Profile Conflicts</string>
            <string>Smart Group Audit</string>
            <string>Script Auditor</string>
            <string>Extension Attributes</string>
            <string>Self Service Audit</string>
            <string>Unused</string>
        </array>
        <key>MT-ProfileBuilders</key>
        <array>
            <string>PPPC Analyser</string>
            <string>System Extensions</string>
            <string>Web Content Filter</string>
            <string>Notifications</string>
            <string>Login Item Profiles</string>
            <string>Profile Inspector</string>
            <string>Profile Signer</string>
            <string>Profile Unsigner</string>
        </array>
    </dict>
    <key>LockedTools</key>
    <array>
        <string>Wipe</string>
        <string>Disable</string>
        <string>Clone</string>
        <string>Restore</string>
    </array>
    <key>LockAppearance</key>
    <string>auto</string>
    <key>HideDebugLog</key>
    <false/>
    <key>HideAdditionalTools</key>
    <false/>
    <key>CustomApplications</key>
    <array>
        <dict>
            <key>name</key>
            <string>Self Service</string>
            <key>path</key>
            <string>/Applications/Self Service.app</string>
        </dict>
        <dict>
            <key>name</key>
            <string>Terminal</string>
            <key>path</key>
            <string>/System/Applications/Utilities/Terminal.app</string>
        </dict>
    </array>
    <key>AllowUserCustomApps</key>
    <true/>
    <key>DefaultJamfServerURL</key>
    <string>https://your-instance.jamfcloud.com</string>
    <key>DefaultJamfUsername</key>
    <string>your-jamf-username</string>
    <key>LockDefaultServer</key>
    <true/>
    <key>OrganisationName</key>
    <string>Your Organisation</string>
    <key>SupportContact</key>
    <string>it-support@example.com</string>
</dict>
</plist>

With this profile:

Signed-in person is in They see
MT-FullAccess Every tool. Wipe, Disable, Clone and Restore ask for the PIN
MT-Helpdesk The seven helpdesk tools
MT-Helpdesk and MT-Auditors All fifteen tools from both groups
None of the four groups No tools

Without Entra ID

To limit the tools without asking anyone to sign in, leave out the four Entra keys and use AllowedTools instead:

<key>AllowedTools</key>
<array>
    <string>Fleet Health</string>
    <string>Device Logs</string>
    <string>Policy Scope</string>
    <string>Network Check</string>
</array>
<key>HiddenCategories</key>
<array>
    <string>Content &amp; Packages</string>
</array>

Related

Magic Toolbox © MDM Magic · mdmmagic.au · Releases · Report an issue

🏠 Home

Getting started

Deployment

Jamf Pro Tools

Audit & Health Check

Profile Builders

Content & Packages

Reference

⬇️ Download latest

Clone this wiki locally