-
Notifications
You must be signed in to change notification settings - Fork 0
Apple Silicon Jamf Pro API Credentials
Even with root privileges 'super' can not enforce software updates on Mac computers with Apple silicon without additional update credentials. Mac computers with Intel do not require additional software update credentials.
For Mac computers with Apple silicon on macOS 11.5 or later, super supports a MDM push software update enforcement workflow via Jamf Pro API credentials. On older systems the Jamf Pro API credentials are still validated and saved but the MDM push software update workflow is not attempted until the system is at least macOS 11.5.
Alternately, for Mac computers with Apple silicon, super also supports more reliable and performant workflows that update via local update credentials.
Only one Apple silicon authentication method is allowed at a time. If you specify multiple authentication methods then only one will be saved via the priority order as follows; local end user's password, then an existing local account, then the local super service account, Jamf Pro API client/secret credentials, and finally Jamf Pro API username/password credentials.
If you are aware of another MDM service that can push macOS software update commands via a public API, then please submit an Issue for consideration in a future version of super.
Jamf Pro 10.49 introduced support for authentication via API roles and clients credentials. However, at this point all versions of Jamf Pro still support API authentication via user account and password credentials. Although super still supports both methods, the newer API roles and clients method is more secure, and as such is considered the best practice.
These credentials can not be set via a MDM configuration profile as doing so would make them visible to any macOS user in System Settings (or System Preferences). These credentials are encoded in base64 format and then stored in the the System keychain. Although these credentials are not stored in "clear text", any local administrator can access the base64 encoded strings in the System keychain.
A Jamf Pro API client ID and client secret with appropriate privileges to request macOS managed software update MDM commands.
Command option example:
--auth-jamf-client=688326af-6be1-4fd4-868a-e33a167b01e6
--auth-jamf-secret=f56df3be3f73e3694b6a19ffd0e59cbf28e20b4acb1a6868e6d73170120d955e
Jamf Pro API client ID and client secret values do not contain any special characters, thus do not require any special handling in the command line.
A Jamf Pro user account name and password with appropriate privileges to request macOS managed software update MDM commands.
Command option example:
--auth-jamf-account='superapi'
--auth-jamf-password='ThisIs@Test'
When deploying super using the command line, if either the account name or password contains any special characters or spaces then you should surround the text with single ' quotes. However, when deploying super using a Jamf Pro Policy with Script Parameters do not use single quotes.
Jamf Pro Policy Script Parameters example:
--auth-jamf-account=superapi
--auth-jamf-password=ThisIs@Test
In addition to specifying a Jamf Pro API authentication option, you must also set appropriate Jamf Pro privileges to allow the saved credentials to start the MDM managed update workflow.
Starting with Jamf Pro 10.48, you have the option to enable the new "beta" managed macOS update feature. In addition to providing a new Jamf Pro interface for managed macOS updates, this feature also introduced a new Jamf Pro API endpoint. Although super can automatically detect if you have this new feature enabled in Jamf Pro, it requires dramatically different API permissions than the legacy API endpoint.
As covered previously on this page, Jamf Pro supports two different API authentication mechanisms, as such the names of the required privileges are slightly different between the two mechanisms.
New "beta" managed update privileges when authenticating via API roles and clients:
- Read Computers
- Create Managed Software Updates
- Read Managed Software Updates
- Read Mobile Devices
- Send Computer Remote Command to Download and Install OS X Update
- Send Mobile Device Remote Command to Download and Install iOS Update
New "beta" managed update privileges when authenticating via account and password:
- Jamf Pro Server Objects > Computers > Read
- Jamf Pro Server Objects > Managed Software Updates > Create & Read
- Jamf Pro Server Objects > Mobile Devices > Read
- Jamf Pro Server Actions > Send Computer Remote Command to Download and Install macOS Update
- Jamf Pro Server Actions > Send Mobile Device Remote Command to Download and Install iOS Update
As covered previously on this page, Jamf Pro supports two different API authentication mechanisms, as such the names of the required privileges are slightly different between the two mechanisms.
Legacy managed update privileges when authenticating via API roles and clients:
- Create Computers
- Create Managed Software Updates
- Read Managed Software Updates
- Update Managed Software Updates
- Send Computer Remote Command to Download and Install OS X Update
Legacy managed update privileges when authenticating via account and password:
- Jamf Pro Server Objects > Computers > Create
- Jamf Pro 10.47+: Jamf Pro Server Objects > Managed Software Updates > Create, Read, Update
- Jamf Pro Server Actions > Send Computer Remote Command to Download and Install macOS Update
In order to send a managed software update request, super must know the Jamf Pro ID of the computer's inventory record. During super startup, if the computer's Jamf Pro ID is unknown, then super runs an additional jamf recon to resolve the computer's Jamf Pro ID. This additional Jamf inventory can take several minutes for some configurations, but it can also be avoided with the proper configuration of a super MDM configuration profile.
In other words, super does not have to run additional jamf recon inventories if you also deploy a super MDM configuration profile that contains the following XML keys:
Configuration profile example:
<key>AuthJamfComputerID</key>
<string>$JSSID</string>
Detailed documentation regarding the deployment of super settings via Jamf Pro can be found here.
Set a specific custom Jamf Pro URL for API calls.
Command option example:
--auth-jamf-custom-url=https://jamf-api.domain.com
Command option disable example:
--auth-jamf-custom-url=X
Configuration profile example:
<key>AuthJamfCustomURL</key>
<string>https://jamf-api.domain.com</string>
The default behavior for super is to automatically discover the Jamf Pro management URL via the local Jamf Pro property list. However, setting this option overrides automatic URL discovery in favor of the specified URL.
The unfortunate truth is that the MDM update workflow is too complicated to be reliable. If the MDM workflow fails, the default behavior of super is to automatically try again later based on the error deferral timer.
Alternately, the user authentication MDM failover option allows the currently logged in user to provide local authentication so the update workflow can continue even if the MDM workflow fails. This option accepts one or more MDM failover types that are comma separated with no spaces.
Command option example:
--auth-mdm-failover-to-user=NOSERVICE,INSTALLNOW,BOOTSTRAP
Command option disable example:
--auth-mdm-failover-to-user=X
Configuration profile example:
<key>AuthMDMFailoverToUser</key>
<string>NOSERVICE,INSTALLNOW,BOOTSTRAP</string>
You can use any combination of the following user authentication MDM failover types:
-
Fail over any time the MDM workflow fails (this encompasses all of the other failover types):
--auth-mdm-failover-to-user=ALWAYS -
Fail over if the MDM service is unavailable or the API account fails to authenticate:
--auth-mdm-failover-to-user=NOSERVICE -
Fail over if the MDM workflow fails and a hard deadline has passed:
--auth-mdm-failover-to-user=HARD -
Fail over if the MDM workflow fails and a soft deadline has passed:
--auth-mdm-failover-to-user=SOFT -
Fail over if the MDM workflow fails during the install now workflow:
--auth-mdm-failover-to-user=INSTALLNOW -
Fail over if
superhas detected a problem with the computer's bootstrap token escrow:
--auth-mdm-failover-to-user=BOOTSTRAP
In order to enforce macOS updates via MDM the computer's bootstrap token must be escrowed with your MDM service. Even if you don't enable the user authentication MDM failover option, super always checks if the computer's bootstrap token was previously escrowed with the MDM service. However, just because the computer's bootstrap token was previously escrowed does not guarantee it's still valid. As such, on systems with macOS 13.3 or newer, super can also check the validity of the previously escrowed bootstrap token with the MDM service (assuming it can be reached).
If super detects an issue with the computer's booststrap token escrow, and you have specified either the ALWAYS or BOOTSTRAP user authentication MDM failover types, then super attempts to re-escrow the computer's bootstrap token with the MDM service. However, the re-escrow attempt is only possible if the following criteria is met; the user successfully authenticates, the user account is a local admin, the user account has a secure token, and the MDM service is available.
If any managed automatic authentication method fails validation, then failover to local end user authentication.
Command option example:
--auth-credential-failover-to-user
Command option disable example:
--auth-credential-failover-to-user-off
Configuration profile example:
<key>AuthCredentialFailoverToUser</key>
<true/>
As a default behavior, managed authentication option errors do not allow the super workflow to continue. Enabling this option allows for end user authentication if any of the following authentication options fail; --auth-local-account, --auth-service-add-via-admin-account, --auth-jamf-client, or --auth-jamf-account. As such, the --auth-credential-failover-to-user option covers both local and MDM authentication failures, as opposed to the MDM-specific --auth-mdm-failover-to-user option.
Delete all previously saved Apple silicon update credentials.
Command option example:
--auth-delete-all
This includes deleting any saved account credentials and any automatically generated local super service account. This option can not be set via a MDM configuration profile.