Jamf Configuration¶

Integrating Patcher with your Jamf instance.

In order for Patcher to operate as expected a few things need to be setup on the Jamf side beforehand. This page walks through each. If your Jamf instance uses SSO, see SSO considerations below for extra steps you’ll need to follow.

Software titles

Configured for the apps you want to track.

API role

Created with the correct privileges.

API client

A client ID and client secret that Patcher uses to authenticate.

Patch Management Software Titles¶

Patcher only pulls data from configured patch management titles. A title can be available in the catalog and still be invisible to Patcher. It won’t show up in reports until you’ve configured it for your instance.

See also

Configuring a Patch Management Software Title (Jamf Pro Documentation).

Create an API Role¶

In Jamf Pro, go to Settings.

Under System, select API Roles and Clients.

Switch to the API Roles tab and click New.

Give the role a meaningful display name (e.g. Patcher-Roles).

Under Jamf Pro API Role privileges, add the following:

  • Read Patch Management Software Titles

  • Read Patch Policies

  • Read Mobile Devices

  • Read Mobile Device Inventory Collection

  • Read Mobile Device Applications

  • Read API Integrations

  • Read API Roles

  • Read Patch Management Settings

  • Update API Integrations

Click Save.

Create an API Client¶

Once your API role is ready, proceed to create an API client:

Follow steps 1-2 from above to navigate back to the API Roles and Clients section if not already there.

Click on the API Clients tab.

Select New to initiate a new API client creation.

Assign a clear and descriptive display name for the API client (e.g., “Patcher-Client”).

In the API Roles field, assign the previously created API role to this client.

Define the Access Token Lifetime.

This defines how long each token remains valid. See Token lifetime below for more information.

Enable the API client by clicking Enable API Client.

Click Save.

Click Record the Client ID value for safe-keeping.

Generate a Client Secret¶

Important

Record the generated client secret immediately and securely as it is shown only once.

Open the API client’s details page.

Click Generate Client Secret.

Confirm by selecting Create Secret.

Copy the secret. You’ll pass this to Patcher alongside the client ID.

You now have everything Patcher needs: a Jamf URL, a Client ID, and a Client Secret. Patcher stores them in your login Keychain on first run and refreshes the Bearer token automatically as needed.

Token Lifetime¶

Note

You don’t need to generate access tokens yourself. Patcher’s TokenManager handles obtaining and refreshing tokens automatically.

When configuring the API client’s access token lifetime, at least 5 minutes is recommended. Longer durations reduce regeneration frequency and administrative overhead, but should align with your organization’s security policies.

Generate a Token Manually (Optional)¶

In situations where AccessTokens need to be generated manually, copy the bash script below into the code editor of your choice. Substitute your Jamf Pro URL in the url variable, and modify the client_id and client_secret values with the Client ID and secret generated from the steps above.

#!/bin/bash

url="https://yourserver.jamfcloud.com"
client_id="your-jamf-api-client-id"
client_secret="your-jamf-api-client-secret"

response=$(curl --silent --location --request POST "${url}/api/oauth/token" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data-urlencode "client_id=${client_id}" \
 --data-urlencode "grant_type=client_credentials" \
 --data-urlencode "client_secret=${client_secret}")

token=$(echo "$response" | plutil -extract access_token raw -)
expires_in=$(echo "$response" | plutil -extract expires_in raw -)

security add-generic-password -a "TOKEN" -s "Patcher" -w "$token" -U
security add-generic-password -a "TOKEN_EXPIRATION" -s "Patcher" -w "$expires_in" -U
Requires httpx and keyring. Both are already installed with patcherctl.¶
import httpx
import keyring

url = "https://yourserver.jamfcloud.com/api/oauth/token"
client_id = "your-jamf-api-client-id"
client_secret = "your-jamf-api-client-secret"

response = httpx.post(
    url,
    data={
        "client_id": client_id,
        "grant_type": "client_credentials",
        "client_secret": client_secret,
    },
)
response.raise_for_status()

data = response.json()
keyring.set_password("Patcher", "TOKEN", data["access_token"])
keyring.set_password("Patcher", "TOKEN_EXPIRATION", str(data["expires_in"]))

SSO Considerations¶

Patcher’s setup wizard can create the API role and client for you automatically, but only if your Jamf Pro account doesn’t use SSO. If SSO is in play, you have two options:

Option 1: Create the Role and Client Manually¶

Follow the steps above to create the API role, client, and secret yourself. Then provide the Client ID and Client Secret to Patcher’s setup wizard when prompted. This is the recommended path for SSO environments.

Option 2: Temporary Standard Account¶

Temporarily create a standard Jamf Pro user account with administrator privileges.

Pass that account’s credentials to Patcher’s setup wizard. Patcher will create the API role and client on your behalf.

After setup completes, delete the temporary account.

Multi-Instance Support¶

Patcher can be reset and pointed at a different Jamf URL via patcherctl reset creds (or by constructing PatcherClient with different credentials), but it has only been exercised against a single Jamf instance configured with two sites. Multi-tenant patterns (one workstation hopping between two distinct Jamf Pro instances) should have no problem, but has not been explicitly tested. If you run into any issues, be sure to submit an issue and let us know about it.