Setup Assistant#

Our aim as developers of this tool is to streamline the setup and installation process to be as straightforward as possible. We understand there’s nothing more frustrating than the anticipation of using a new tool, only to be bogged down by extensive configuration or setup steps before you can even start. To address this, we introduced a setup assistant in version 1.3.2 (and up) that automates the initial configuration. This page will demonstrate how the tool operates under the hood, giving you the end-user insight into how to trigger it again if necessary.

First Run Detection#

Patcher needs to know whether it is being run for the first time. This is important so that credentials are saved and stored properly and user-interface customizations are setup for subsequent uses. Here is how the process works:

  1. First Run Check: When Patcher is executed, it looks for a property list in Patcher’s Application Support directory. Specifically, it checks for the presence of com.liquidzoo.patcher.plist in /Users/$username/Library/Application Support/Patcher, where $username denotes the currently logged in user.

  2. Key Check: If the property list is found, Patcher will parse its contents for the first_run_done key.

    • If the file does not exist, or if the key is set to False, the setup assistant is triggered.

    • The key must be set to True to prevent the setup assistant from running.

Choosing Setup type#

The setup assistant will show a greeting message and then prompt you which setup method to proceed with:

Thanks for downloading Patcher!

[...]  # Rest of greeting

Choose setup method (1: Standard setup, 2: SSO setup) [1]:

Which Method to Use#

  • Select SSO if you use Single Sign On (SSO) to sign into Jamf. This is due to the Jamf Pro API not supporting the use of SSO for authorization. Both an API role and API client will need to be created manually to pass credentials to the setup assistant. See the Jamf Deployment Guide for instructions on completing this.

  • Select Standard if you’d like Patcher to automatically create an API Role & Client on your behalf. You will be prompted for your username and password during setup, but these values are never stored permanently by Patcher. They are solely used to obtain a basic token to create the API integration as expected.

Storing Credentials#

Patcher uses the keyring library to save credentials to the login keychain in macOS. In some situations, it may be easier or necessary to save the credentials before using Patcher. If you find this may apply to you, copy the code snippet below into your code editor of choice. If you do not have the keyring library already installed, it can be installed via pip. After installing keyring, replace the placeholder values for api_url, api_client_id, and api_client_secret and run the script.

import keyring

api_url = "Your Jamf URL here"  # https://anyorg.jamfcloud.com
api_client_id = "Your client ID here"
api_client_secret = "Your client secret here"

keyring.set_password("Patcher", "URL", api_url)
keyring.set_password("Patcher", "CLIENT_ID", api_client_id)
keyring.set_password("Patcher", "CLIENT_SECRET", api_client_secret)

If the snippet runs without any errors, these credentials can be viewed in the Keychain Access application under the login keychain.

Tip

Patcher is configured to handle generating bearer tokens and ensuring they are refreshed. Therefore, it is not required to generate a bearer token as part of this process.