Configuration

Configuration

Every setting lives in the domain com.github.macadmins.SupportCompanion. For the full list of keys, see Preference reference. This page is about where you put them, which in 3.0.0 is no longer the same answer for every key.

The three tiers

Tier	Where the value has to come from
Profile	A configuration profile, forced onto the logged-in user or the device. Nothing else counts.
Helper	/Library/Managed Preferences/<user>/<domain>.plist, then /Library/Managed Preferences/<domain>.plist. Root-owned, not group- or other-writable.
Defaults	Anywhere UserDefaults looks: a profile, /Library/Preferences, or the user's own domain.

Most settings are Defaults — deploy them however you like. The Profile and Helper tiers cover only the settings that decide what runs as root or who holds administrator rights.

Breaking in 3.0.0. These settings used to be read from wherever UserDefaults found them, including the user's own domain. A standard user could set EnableElevation or an IsPrivileged action with defaults write and get root. If you deploy any of them that way today, move them to a configuration profile before upgrading.

Why not /Library/Preferences

It is root-owned, which sounds sufficient, and that is the problem. Every setting in these two tiers decides something privileged. Anything that reaches root even briefly — a privileged action, somebody inside an elevation window — could write itself a permanent grant of elevation and of the installer allowlist into that file, and nothing would ever put it back. A configuration profile is owned by the MDM, which re-applies it, so a forged value does not survive.

Which keys

Profile, read by the app to decide what to offer:

EnableElevation, MaxElevationTime, RequireResonForElevation, ReasonMinLength, ElevationWebhookUrl, ElevationSeverity, RequirePrivilegedActionAuthentication, EnableUserInstalls, ShowInstallerServiceMenuItem, SkipHelperInstall, FleetUrl, and IsPrivileged on Actions.

Helper, read by the helper to decide what actually happens:

EnforceAdminAllowlist, PermanentAdmins, ElevationAllowedAdmins (all device-scoped), EnableUserInstalls, RequireAuthenticationForInstalls, UserInstallFallback, AllowedInstallers, and Actions (for the command behind a privileged action).

Where the two overlap, the helper's answer is the one that counts. The app's copy only decides whether to show a button.

When a setting appears to do nothing

Neither reader falls back silently. Both log an error naming the key and the file it was found in:

Ignoring 'EnableElevation' from /Library/Preferences: settings that grant privileges are only
read from a configuration profile. Deliver it through your MDM.

See Troubleshooting for how to read the log.

Scope

Most keys work user-scoped or device-scoped. Three must be device-scoped, because the helper reads them when there is no logged-in user to attribute the read to:

• EnforceAdminAllowlist
• PermanentAdmins
• ElevationAllowedAdmins

SkipHelperInstall must also be device-scoped, because an installer script cannot read a user-scoped profile.

A minimal profile

<?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>BrandName</key>
    <string>Contoso IT</string>
    <key>SupportEmail</key>
    <string>servicedesk@contoso.com</string>
    <key>SupportPageUrl</key>
    <string>https://support.contoso.com</string>
    <key>KnowledgeBaseUrl</key>
    <string>https://kb.contoso.com</string>
    <key>NotificationInterval</key>
    <integer>4</integer>
</dict>
</plist>

A profile with elevation

Everything here must be in a profile to be honoured. See Admin elevation for what these do.

<key>EnableElevation</key>
<true/>
<key>MaxElevationTime</key>
<integer>10</integer>
<key>RequireResonForElevation</key>
<true/>
<key>ReasonMinLength</key>
<integer>20</integer>
<key>ElevationWebhookUrl</key>
<string>https://example.com/hooks/elevation</string>

<!-- Device-scoped profile -->
<key>EnforceAdminAllowlist</key>
<true/>
<key>PermanentAdmins</key>
<array>
    <string>ladmin</string>
    <string>breakglass</string>
</array>

Testing settings

Plain Defaults-tier keys can be set locally while you work:

defaults write com.github.macadmins.SupportCompanion BrandName "Test"

The app notices and redraws without a restart, whether the change came from a profile, from defaults write, or from the app itself.

Profile and Helper keys cannot be tested this way, by design. For development, put a plist in /Library/Managed Preferences/ — root can write there directly and both readers will read it.

SupportCompanionCLI prefs prints what the app currently sees, and SupportCompanionCLI reset returns the Defaults tier to its built-in values. See CLI.