Merge pull request #430 from smallstep/carl/agent-manual-install-macos

CON-248: Agent manual install steps for macos

Author: tashian

tutorials/connect-jamf-pro-to-smallstep.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: July 07, 2025
+updated_at: August 21, 2025
 title: Connect Jamf Pro to Smallstep
 html_title: Connect Jamf Pro to Smallstep
 description: Configure Jamf Pro to deploy the Smallstep Agent and distribute certificates and configuration to Mac clients.
@@ -9,7 +9,7 @@ Smallstep can integrate with Jamf Pro to synchronize your device inventory, and
 
 This document also contains [uninstall instructions](#uninstall-smallstep-agent-with-jamf-pro).
 
-# Requirements & Limitations
+## Requirements & Limitations
 
 You will need:
 
@@ -35,9 +35,9 @@ Limitations:
 - For VPN configurations, only IPSec VPNs are currently supported.
 - “Always-on VPN” or device-wide VPNs are not yet supported in Smallstep-managed configurations.
 
-# Step-by-step instructions
+## Step-by-step instructions
 
-### Create an API Client in Jamf Pro
+## Create an API Client in Jamf Pro
 
 This API client will allow Smallstep to read your Jamf device inventory and manage the webhooks necessary for ongoing inventory syncing.
 
@@ -59,19 +59,19 @@ This API client will allow Smallstep to read your Jamf device inventory and mana
 5. Choose **Generate client secret**
 6. Temporarily save the **Client ID** and **Client Secret**. You’ll use them in the next step.
 
-### Connect Jamf to Smallstep
+## Connect Jamf Pro to Smallstep
 
-Let’s add the Jamf API credentials you just created to Smallstep.
+Let’s add the Jamf Pro API credentials you just created to Smallstep.
 
 1. In the Smallstep UI, go to the [**Device Management**](https://smallstep.com/app/?next=/settings/devices) tab in ⛭ **Settings**
 2. Under Jamf, choose ➕ **Connect**
 3. Enter the API credentials from Jamf
 4. Choose **Add Platform**. Your device inventory will start syncing from Jamf to Smallstep.
 5. Temporarily save the **Webhook URL**, **Username**, and **Password** presented.
 
-### Configure a SCEP Enrollment webhook in Jamf Pro
+## Configure a SCEP Enrollment webhook in Jamf Pro
 
-For compatibility reasons, Smallstep may use ACME or SCEP for certificate enrollment. The SCEP Enrollment webhook allows Jamf to request a dynamic, short-lived challenge string from Smallstep during a SCEP request. The challenge string is injected into a [SCEP payload](https://developer.apple.com/documentation/devicemanagement/scep) for your clients to authenticate to Smallstep.
+For compatibility reasons, Smallstep may use ACME or SCEP for certificate enrollment. The SCEP Enrollment webhook allows Jamf to request a dynamic, short-lived challenge string from Smallstep during the SCEP request. The challenge string is injected into the [SCEP payload](https://developer.apple.com/documentation/devicemanagement/scep) for your clients to authenticate to Smallstep.
 
 1. In Jamf Pro, choose ⚙️ **Settings**
 2. Under the **Global** tab, Choose **Webhooks**
@@ -86,9 +86,18 @@ For compatibility reasons, Smallstep may use ACME or SCEP for certificate enroll
     5. Webhook Event: SCEPChallenge
 4. Choose **Save**
 
-### Create an Agent Package for Distribution
+Your Smallstep team is now linked to Jamf Pro. Smallstep will do a partial sync of your device inventory from Jamf every hour, and a full sync every 8 hours.
 
-In this step, you’ll upload the Smallstep agent package to Jamf’s distribution network.
+## Install the Smallstep agent
+
+There's two ways to install the agent: Using Jamf Pro, or using a separate software management tool.
+For example, [Munki](https://www.munki.org/munki/) is a popular option for managing macOS apps in a large IT organization.
+
+### Option 1: Install the agent via Jamf
+
+#### Create an Agent Package for Distribution
+
+In this step, you’ll upload the Smallstep agent package to Jamf Pro’s software distribution network.
 
 1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg)
 2. In Jamf Pro, choose ⚙️ **Settings**
@@ -98,7 +107,7 @@ In this step, you’ll upload the Smallstep agent package to Jamf’s distributi
     2. Filename: (upload from step #1)
 5. Choose **Save**
 
-### Create an Agent Bootstrap Script
+#### Create an Agent Bootstrap Script
 
 This step will install a script on your client devices that bootstraps the connection between your devices and Smallstep.
 
@@ -117,7 +126,7 @@ This step will install a script on your client devices that bootstraps the conne
 
 4. Choose **Save**
 
-### Create an Agent Installation Policy
+#### Create an Agent Installation Policy
 
 Next, we’ll configure the Script we just created to run on your client devices.
 
@@ -140,7 +149,7 @@ Next, we’ll configure the Script we just created to run on your client devices
     4. Under Scope, select your desired policy scope. The agent will be installed on all devices in this scope.
 4. Choose **Save**
 
-### Configure an Agent Enrollment Profile
+#### Configure an Agent Enrollment Profile
 
 In this step, we’ll tie everything together by creating a managed policy to enroll devices using the Smallstep Agent.
 
@@ -210,18 +219,57 @@ In this step, we’ll tie everything together by creating a managed policy to en
             2. Set the desired scope. This should mirror the scope you chose when creating the Policy in step 5.
             3. Choose Save
 
-Your Smallstep team is now linked to Jamf. Smallstep will do a partial sync of your device inventory from Jamf every hour, and a full sync every 8 hours.
-
 The devices that you scoped will receive a certificate and have the agent installed and running.
 
-### Confirmation
+### Option 2: Install via a software management tool
+
+If you're using a software management tool:
+
+1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg)
+2. Distribute and install the package on your desired endpoints
+3. Create a user launch agent file on the endpoint, in `/Users/<USER>/Library/LaunchAgents/com.smallstep.launchd.Agent.plist` for the primary user of the device.
+
+   The Smallstep agent does not yet support multi-user deployments on macOS&mdash;it must be installed for a single user:
+ 
+   ```
+   <?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>Label</key>
+       <string>com.smallstep.launchd.Agent</string>
+       <key>ProgramArguments</key>
+       <array>
+           <string>/Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent</string>
+           <string>start</string>
+           <string>managed</string>
+       </array>
+       <key>KeepAlive</key>
+       <true/>
+       <key>RunAtLoad</key>
+       <true/>
+       <key>AssociatedBundleIdentifiers</key>
+       <string>com.smallstep.Agent</string>
+   </dict>
+   </plist>
+   ```
+
+4. On the endpoint, register the launch agent by running the following:
+
+   ```
+   launchctl load /Users/<USER>/Library/LaunchAgents/com.smallstep.launchd.Agent.plist`
+   ```
+
+
+## Confirmation
 
 There's two ways to confirm installation on an endpoint:
+
 - In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp.
 - Alternatively, on the device itself, run `/Applications/SmallstepAgent/Contents/MacOS/SmallstepAgent version` to see that the agent is installed. And, in **System Settings**, check **Login Items** to confirm that there is a **Smallstep Agent** entry.
 
 
-# Uninstall Smallstep Agent with Jamf Pro
+## Uninstall Smallstep Agent with Jamf Pro
 
 You can easily remove a Smallstep Agent that was installed on macOS endpoints via Jamf Pro.