Skip to content

Managing Privileges

Jump to bottom
Marc Thielemann edited this page Nov 5, 2025 · 145 revisions



Configuration profile keys

Here you can find information about all app settings that can be configured using a configuration profile:

AllowCLIBiometricAuthentication
AllowPrivilegeRenewal
BiometricsFallbackType
DockToggleTimeout (DEPRECATED)
DockToggleMaxTimeout (DEPRECATED)
EnableSmartCardSupport
EnableSystemExtension (BETA)
EnforcePrivileges
ExpirationInterval
ExpirationIntervalMax
ForceUpdatePrebootVolume
HelpButtonCustomURL
HideHelpButton
HideOtherWindows
HideSettingsButton
HideSettingsFromDockMenu
HideSettingsFromStatusItem
LimitToGroup
LimitToUser
MaxIntervalInitial
PassReasonToExecutable
PostChangeActionOnGrantOnly
PostChangeExecutablePath
ReasonCheckingEnabled
ReasonMaxLength
ReasonMinLength
ReasonPresetList
ReasonRequired
RemoteLogging
RenewalCustomAction
RenewalFollowsAuthSetting
RenewalNotificationInterval
RequireAuthentication
RequireBiometricAuthentication
RevokeAtLoginExcludedUsers
RevokePrivilegesAfterSystemTimeChange
RevokePrivilegesAtLogin
ShowInMenuBar
ShowRemainingTimeInMenuBar

key:	ExpirationInterval
value:	a positive integer

Privileges 2.0.0+

Set a fixed time interval after which administrator privileges expire and revert to standard user rights. A value of 0 disables the timeout and allows the user to request permanent administrator privileges.

key:	ExpirationIntervalMax
value:	a positive integer

Privileges 2.0.0+

Set a maximum time interval for a user to request administrator privileges. This generally works the same way as ExpirationInterval, but allows the user to choose any timeout value up to the specified one. So if the admin would set ExpirationIntervalMax to 20 minutes, the user can choose to set it to a value up to 20 minutes instead of being forced to use the 20 minute timeout.

Important

For usability reasons, we recommend using ExpirationIntervalMax instead of ExpirationInterval. If both ExpirationIntervalMax and ExpirationInterval are set, the value of ExpirationInterval takes precedence over ExpirationIntervalMax.

key:	MaxIntervalInitial
value:	a positive integer

Privileges 2.4.0+

Sets the initial time interval if ExpirationIntervalMax has been configured. If not set and the user never selected an expiration interval, the initial expiration interval is set to 20 minutes. If you want to define an expiration interval that is less than the maximum expiration interval, use this option to define it. As mentioned earlier, this option has no effect if a user has already selected an expiration interval.

key:	DockToggleTimeout
value:	a positive integer

Privileges 1.0.5 - 1.5.4

Set a fixed time interval after which administrator privileges expire and revert to standard user rights. A value of 0 disables the timeout and allows the user to request permanent administrator privileges.

key:	DockToggleMaxTimeout
value:	a positive integer

Privileges 1.0.5 - 1.5.4

Set a maximum time interval for a user to request administrator privileges. This generally works the same way as DockToggleTimeout, but allows the user to choose any timeout value up to the specified one. So if the admin would set DockToggleMaxTimeout to 20 minutes, the user can choose to set it to a value up to 20 minutes instead of being forced to use the 20 minute timeout.

Important

For usability reasons, we recommend using DockToggleMaxTimeout instead of DockToggleTimeout. If both DockToggleMaxTimeout and DockToggleTimeout are set, the value of DockToggleTimeout takes precedence over DockToggleMaxTimeout.

key:	AllowPrivilegeRenewal
value:	a boolean

Privileges 2.1.0+

Specifies whether expiring administrator privileges can be renewed. When set to true, the user will receive a notification one minute before administrator privileges expire. The notification includes a Renew button that can be used to renew administrator privileges.

key:	RenewalFollowsAuthSetting
value:	a boolean

Privileges 2.1.0+

When set to true, renewing privileges requires the same kind of authentication as initially requesting administrator privileges.

key:	RenewalCustomAction
value:	a dictionary

Privileges 2.3.0+

Specifies a custom action to notify the user about expiring administrator privileges. So you can inform your users using a dialog or whatever you want. You could e.g. just run the following script…

#!/bin/bash

privilegesPath="/Applications/Privileges.app"

buttonPressed=$(/usr/bin/osascript << EOF
tell application "System Events"
try
activate
display dialog "Your administrator privileges are about to expire. Do you want to renew them?" with \
icon (get first file of folder "${privilegesPath%%/}/Contents/Resources" whose name extension is "icns") \
buttons {"Cancel", "Renew"} default button 2 giving up after 60
return (button returned of the result)
end try
end tell
EOF
)

if [[ "$buttonPressed" = "Renew" ]]; then
   "${privilegesPath%%/}/Contents/MacOS/PrivilegesCLI" -a
fi

exit 0

…to get something like this:


The following keys are supported:

ActionExecutablePath
ActionNotificationInterval


The dictionary could look like this:

<key>RenewalCustomAction</key>
<dict>
   <key>ActionExecutablePath</key>
   <string>/Library/Application Support/Privileges/privileges_renewal.sh</string>
   <key>ActionNotificationInterval</key>
   <integer>5</integer>
</dict>

key:	ActionExecutablePath
value:	a string containing the absolute path to an application or script

Privileges 2.3.0+

If configured, the default renewal notifications are disabled and the specified executable is launched instead.

key:	ActionNotificationInterval
value:	an integer

Privileges 2.3.0+

This optional value can be configured to specify how many minutes before the admin privileges expire the executable should be launched. If not configured, or the configured value is smaller than 1 or bigger than the expiration interval - 1, it defaults to 1 minute. The notification interval is also passed to the executable configured using ActionExecutablePath as the $1 argument.

key:	RenewalNotificationInterval
value:	a positive integer

Privileges 2.4.1+

Specifies the number of minutes before the expiration of administrator privileges when Privileges should notify users to renew their privileges. This number must be lower than the expiration interval, otherwise it defaults to 1. If a RenewalCustomAction is specified, its ActionNotificationInterval overwrites the configured RenewalNotificationInterval.

key:	EnforcePrivileges
value:	a string containing the value "admin", "user" or "none"

Privileges 1.0.5+

Immediately enforces specific privileges. If EnforcePrivileges is set to none, it is no longer possible to change privileges with the Privileges application or any of its bundled applications.

key:	RequireAuthentication
value:	a boolean

Privileges 1.5.0+

Specifies whether authentication is required to obtain administrator privileges. When set to true, the user is prompted for the account password (or Touch ID, if available). Note that once this option is enabled, privileges cannot be changed from the Privileges Dock tile menu unless AllowCLIBiometricAuthentication is also enabled.

key:	AllowCLIBiometricAuthentication
value:	a boolean

Privileges 2.0.0+

Specifies whether to allow biometric authentication in the PrivilegesCLI to obtain administrator privileges. When set to true, the PrivilegesAgent prompts the user for the account password (or Touch ID, if available). To make this option work, you must enable the RequireAuthentication option.

key:	RequireBiometricAuthentication
value:	a boolean

Privileges 2.4.0+

Specifies whether biometric authentication is required to obtain administrator privileges. When set to true, the PrivilegesAgent prompts the user for Touch ID and does not offer an alternative option. If Touch ID is unavailable or has not been configured, the user is prompted for their account password instead. To make this option work, you must enable the RequireAuthentication option and EnableSmartCardSupport must be disabled.

key:	BiometricsFallbackType
value:	a positive integer

Privileges 2.4.2+

This specifies the fallback strategy when RequireBiometricAuthentication is enabled. By default, users are prompted to enter their username and password if biometric authentication is not configured or is unavailable. However, this may not be the desired behavior in all environments. It can be changed as follows:

0: If biometric authentication is unavailable or not configured, the user will be prompted to enter their username and password. (default)

1: If biometric authentication is unavailable, the user will be prompted to enter their username and password. If biometric authentication is available but has not been configured, authentication will fail.

2: If biometric authentication is unavailable or not configured, authentication will fail.

Important

PrivilegesCLI does not use biometric authentication by default. Therefore, the BiometricsFallbackType setting will be ignored unless the AllowCLIBiometricAuthentication setting is enabled.

key:	EnableSmartCardSupport
value:	a boolean

Privileges 2.2.0+

Specifies whether to enable smart card support for authentication. Since the modern Local Authentication framework does not yet support smart cards/PIV tokens, enabling this option will cause the application to fall back to the older Authorization Services. To make this option work, you must enable the RequireAuthentication option.

key:	PostChangeExecutablePath
value:	a string containing the absolute path to an application or script

When set, the PrivilegesAgent executes the given application or script and provides the current user's user name ($1) and its privileges (admin or user, $2) as launch arguments. If the application or script does not exist or is not executable, the launch operation fails silently.

key:	PassReasonToExecutable
value:	a boolean

Privileges 2.1.0+

Specifies whether the reason that the user entered when requesting administrator privileges should be passed to the executable configured with the PostChangeExecutablePath key. This is disabled by default. If enabled, the reason is passed to the executable as $3.

key:	PostChangeActionOnGrantOnly
value:	a boolean

Privileges 2.0.0+

When set to true, the application or script, specified in PostChangeExecutablePath, will only be executed if administrator privileges are granted to a user, but not the privileges are revoked.

key:	RevokePrivilegesAtLogin
value:	a boolean

Privileges 2.0.0+

When set to true, the user's administrator privileges are revoked at login.

Warning

For those who use fixed admin accounts on their machines: If you want to enable this feature, please make sure you exclude the admin account(s) using the RevokeAtLoginExcludedUsers key. Otherwise these accounts become standard user accounts at next log in.

key:	RevokeAtLoginExcludedUsers
value:	an array of strings containing the short names of the users

Privileges 2.1.0+

If RevokePrivilegesAtLogin is set to true, the specified users are excluded from privilege revocation at login. When used with a client management system that supports variables in configuration profiles, variables such as $USERNAME can be used here.

key:	RevokePrivilegesAfterSystemTimeChange
value:	a boolean

Privileges 2.4.1+

When set to true, the user's administrator privileges are revoked if the system time did change. Enable this feature to prevent users from extending their admin time by adjusting the time on their Mac.

Important

If you enable this feature, please be aware that admin users can extend or retain their admin rights in various other ways. Therefore, this feature offers no protection against users misusing their admin rights.

key:	HideOtherWindows
value:	a boolean

Privileges 2.0.0+

By default, Privileges hides open windows to show the desktop and ensure that only the Privileges window is visible on the screen. Set HideOtherWindows to false to disable this function.

key:	LimitToUser
value:	a string containing the user's short name or an array of strings containing the user's short names

Privileges 1.5.0+

Restricts use of the application to the specified user or list of users. When used with a client management system that supports variables in configuration profiles, variables such as $USERNAME can be used here.

Important

Please use the array of strings instead of the string value. The string value is only there for backwards compatibility to version 1.x and support for it will be removed in a future version of Privileges.

key:	LimitToGroup
value:	a string containing the name of the group or an array of strings containing the group names

Privileges 1.5.0+

Restricts use of the application to the specified group or list of groups.

Important

Please use the array of strings instead of the string value. The string value is only there for backwards compatibility to version 1.x and support for it will be removed in a future version of Privileges.

key:	ReasonRequired
value:	a boolean

Privileges 1.5.0+

When set to true, the user must provide a reason for requesting administrator privileges. The reason is logged. Note that once this option is enabled, privileges cannot be changed from the Privileges Dock tile menu or the status item menu.

key:	ReasonMinLength
value:	a positive integer below 255

Privileges 1.5.0+

If ReasonRequired is set to true, this key specifies the minimum number of characters the user has to enter as the reason for becoming an admin. If not set, the value defaults to 10. If a value < 1 is specified or if ReasonMinLength is > 250, the value is set to default.

key:	ReasonMaxLength
value:	a positive integer <= 250

Privileges 1.5.3+

If ReasonRequired is set to true, this key specifies the maximum number of characters the user can enter as the reason for becoming an admin. If not set, the value defaults to 250. If a value > 250 is specified or if ReasonMaxLength is <= ReasonMinLength, the value is set to default.

key:	ReasonPresetList
value:	an array of dictionaries

Privileges 1.5.3+

If ReasonRequired is set to true, this key allows to pre-define a list of possible reasons (for becoming an admin) the user can choose from. When set, an additional pop-up menu will appear in the dialog box. This only works for the GUI version of Privileges.

A dictionary should contain these keys and values:

  • a key containing the locale identifier for each language (for example, en or zh)
  • a value containing the localized reason string for that language
  • an optional key default with a value containing the unlocalized reason string

If no exact match is found, the default localization is used. If there is no default localization, the en localization is used. If there is no en localization, the dictionary is skipped. Here's how the general structure should look like:

<key>ReasonPresetList</key>
<array>

   <dict>
      <key>de</key>
      <string>Um Software zu installieren</string>
      <key>en</key>
      <string>For installing software</string>
      <key>es</key>
      <string>Para la instalación de software</string>
      <key>it</key>
      <string>Per l'installazione del software</string>
      <key>default</key>
      <string>For installing software</string>
   </dict>

   <dict>
      …
   </dict>

</array>

key:	ReasonCheckingEnabled
value:	a boolean

Privileges 2.0.0+

When set to true, the text the user enters for a reason is roughly parsed for valid words. If the text does not contain any valid words, the Request Privileges button remains grayed out, even if the minimum number of characters has been entered. The test passes if the text contains any valid words, even if they don't make sense.

Caution

This feature is experimental and disabled by default. If you enable it, please check carefully that it works as expected in your environment.

key:	HideSettingsButton
value:	a boolean

Privileges 2.0.0+

When set to true, the Settings button is no longer displayed in the app.

key:	HideSettingsFromDockMenu
value:	a boolean

Privileges 2.0.0+

When set to true, the Settings menu item is no longer displayed in the Dock tile's menu.

key:	HideSettingsFromStatusItem
value:	a boolean

Privileges 2.1.0+

When set to true, the Settings menu item is no longer displayed in the status item's menu.

key:	HideHelpButton
value:	a boolean

Privileges 2.1.0+

When set to true, the Help (?) button is no longer displayed in the app.

key:	HelpButtonCustomURL
value:	a string containing a http(s) url

Privileges 2.1.0+

If specified, this url is called instead of the Privileges GitHub url if the user clicks the help button. Malformed urls and non-http(s) urls are ignored.

key:	ShowInMenuBar
value:	a boolean

Privileges 2.1.0+

When set to true, a Privileges status item is displayed in the Menu Bar.

key:	ShowRemainingTimeInMenuBar
value:	a boolean

Privileges 2.4.1+

When set to true, a timer displaying the remaining admin time is shown in the Privileges status item.

key:	ForceUpdatePrebootVolume
value:	a boolean

Privileges 2.4.1+

When set to true, the PrivilegesDaemon runs the command /usr/sbin/diskutil apfs updatePreboot / whenever a user's privileges change. You should normally never have to enable this function because the preboot volume is updated automatically after a while. However, we implemented this feature because it seems to be needed in some environments.

Important

Please only enable this function if you know precisely why you are doing so.

key:	EnableSystemExtension
value:	a boolean

Privileges 2.5.0+

When set to true, the Privileges system extension is enabled. The system extension protects the Privileges application and its components against unauthorized modifications, deactivation, or uninstallation. Once this key has been set, it is no longer possible to enable or disable the extension using PrivilegesCLI.

Important

The Privileges system extension requires macOS 13 or newer. Please make sure you grant it full disk access, otherwise it will not work.

key:	RemoteLogging
value:	a dictionary containing the server information

Privileges 1.5.0+

The following keys are supported:

QueuedEventsMax
QueueUnsentEvents
ServerAddress
ServerType
SyslogOptions
WebhookCustomData

key:	QueueUnsentEvents
value:	a boolean

Privileges 2.4.0+

When set to true, syslog and webhook events that could not be sent are queued. When a user changes privileges, PrivilegesAgent attempts to resend these events. The maximum number of queued events can be set using the QueuedEventsMax key. If not set, a maximum of 20 events will be queued. Event queueing works as follows:

  • If an event (syslog or webhook) cannot be sent, it will be stored locally in /Library/Application Support/Privileges/QueuedEvents.plist.
  • The next time any user changes their admin rights via Privileges, an attempt will be made to resend the queued events.
  • If, due to configuration changes, webhook and syslog events are mixed in the event queue, only the events that match the currently configured logging type are resent. Events of a different logging type are discarded.
  • We make sure that the events are sent in the correct order. So the current event will be sent after the queued events.
  • The delayed key of a webhook event is set to true for queued events. This makes it relatively easy for the receiver to identify these events.
  • Events that still could not be sent are returned to the event queue. If the number of unsent events is greater than QueuedEventsMax, the oldest events are discarded. Setting QueuedEventsMax to 0 means that an unlimited number of events will be queued (not recommended).
key:	QueuedEventsMax
value:	a positive integer

Privileges 2.4.0+

Specifies the maximum number of queued events. If not set, a maximum of 20 events will be queued. When set to 0, an unlimited number of events will be queued.

key:	ServerType
value:	a string specifying the type of the logging server

Privileges 1.5.0+

At the moment syslog and webhook are the only supported values.

key:	ServerAddress
value:	a string containing the address of the logging server

Privileges 1.5.0+

The server address can be an ip address or a fully-qualified domain name (FQDN) if a syslog server is configured. For webhooks please provide a http(s) url.

key:    WebhookCustomData
value:  a dictionary

Privileges 2.1.0+

You may use this dictionary to pass custom data (like the machine name, serial number, Jamf Pro ID, etc.) to the webhook. This data is added to the webhook's JSON as custom_data. So for an MDM server that supports variables, the dictionary could look like this:

<dict>
   <key>name</key>
   <string>$COMPUTERNAME</string>
   <key>serial</key>
   <string>$SERIALNUMBER</string>
</dict>

The JSON then would look like this:

{
   "admin":true,
   "custom_data": {
      "name":"Testuser's Mac",
      "serial":"XYZ1234567"
   },
   "delayed":false,
   "event":"corp.sap.privileges.granted",
   "expires":"2024-11-28T07:40:59Z",
   "machine":"E60E8CCB-32F1-4495-A436-BD1939C2BC32",
   "reason":"",
   "timestamp":"2024-11-28T07:20:59Z",
   "user":"testuser"
}

key:	SyslogOptions
value:	a dictionary containing syslog-specific options

Privileges 1.5.0+

The following keys can be used:

EnableTCP (DEPRECATED)
LogFacility
LogSeverity
MaximumMessageSize
MessageFormat
ServerPort
StructuredData
UseTLS

key:	ServerPort
value:	an integer specifying the port of the logging server

Privileges 1.5.0+

If not specified, the port defaults to 514 or to 6514 if TLS is enabled.

key:	EnableTCP
value:	a boolean

Privileges 1.5.0 - 1.5.4

When set to true, the log messages are sent via TCP instead of UDP.

Important

Starting with version 2, Privileges no longer supports syslog over UDP and this configuration key is no longer supported and has no effect. So please make sure your syslog server accepts TCP connections when upgrading to Privileges 2.

key:	UseTLS
value:	a boolean

Privileges 2.0.0+

When set to true, TLS is enabled for the connection. Please make sure your clients have a certificate installed that matches Apple's requirements. Please see https://support.apple.com/en-us/103769 for further information.

key:	LogFacility
value:	an integer specifying the syslog facility

Privileges 1.5.0+

If not specified, facility defaults to 4 (security). Please see https://tools.ietf.org/html/rfc5424#section-6.2.1 for further information.

key:	LogSeverity
value:	an integer specifying the syslog severity

Privileges 1.5.0+

If not specified, severity defaults to 6 (informational). Please see https://tools.ietf.org/html/rfc5424#section-6.2.1 for further information.

key:	MaximumMessageSize
value:	an integer specifying the maximum size of the syslog message (header + event message)

Privileges 1.5.0+

If not specified, the value defaults to 480 which is the minimum maximum message size a syslog server must support. If the syslog message is larger than the specified maximum, the message will be truncated at the end. Please see https://tools.ietf.org/html/rfc5424#section-6.1 for further information.

key:	MessageFormat
value:	an integer specifying the format of the syslog message

Privileges 2.3.0+

If not specified, the value defaults to 1, which describes an RFC 5424 compliant syslog message that uses non-transparent framing. Set this value to 2 if you want to create RFC 5424 compliant syslog messages that use octet counting. Please see https://tools.ietf.org/html/rfc6587#section-3.4.1 and https://tools.ietf.org/html/rfc5424#section-6 for further information.

key:	StructuredData
value:	a dictionary containing structured data elements

Privileges 2.3.0+

Each SD element contains an SD id (which is the name of the element in the form of a string) and SD parameters. SD parameters are defined in a dictionary. The values of this dictionary must be of type string. Keys must be US-ASCII. Spaces and some special characters are not allowed. Please see https://datatracker.ietf.org/doc/html/rfc5424#section-6.3 for further information.

The following example shows a dictionary with two structured data elements:

<key>StructuredData</key>
<dict>

   <key>exampleSDID@32473</key>
   <dict>
      <key>iut</key>
      <string>3</string>
      <key>eventSource</key>
      <string>Application</string>
      <key>eventID</key>
      <string>1011</string>
   </dict>

   <key>examplePriority@32473</key>
   <dict>
      <key>class</key>
      <string>high</string>
   </dict>

</dict>

JSON Schema manifest for Jamf Pro

A JSON Schema manifest allows you to easily create a Privileges configuration for your environment. You can download the Privileges 2 manifest here.

Note

Starting with version 2.3 of Privileges, we provide a more dynamic manifest to help you create better configurations for Privileges. Configurations created with this manifest include a _manifestSelectedType key that is required for the manifest to work and can be ignored. The key has no effect on the Privileges configuration.

Caution

Unfortunately, it turned out that the JSON Schema implementation in Jamf Pro is buggy in some places, so some things don't work as they should. For example, property validation does not work properly in complex manifests, custom error messages are not displayed, and the unique keyword cannot be used because it throws an error. We have some open feature requests and bugs with Jamf and hope that they will eventually work on them so that we can create a more convenient and intelligent manifest for you.


Sample configuration profiles

Some sample configuration profiles are available via the links below:

Dock icon

The Privileges app icon changes its appearance in the dock (screenshot below) if the app is managed by a macOS configuration profile that uses one or more of the following management keys:

  • EnforcePrivileges
  • LimitToGroup
  • LimitToUser

Note

Other management keys do not trigger the icon change.



Privileges settings

Some settings must be pushed to your clients via a configuration profile to enable notifications or allow the PrivilegesAgent and PrivilegesDaemon to run without user permission. You can download a sample profile here.

Clone this wiki locally