Skip to content

CON-248: Agent manual install steps for macos #430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tashian merged 3 commits into from
Aug 22, 2025
Merged

CON-248: Agent manual install steps for macos #430

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ce61bab
Add manual install instructions for agent
tashian Aug 21, 2025
b37eff7
Cleanups
tashian Aug 21, 2025
ee232ec
Add manual install optoin
tashian Aug 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 65 additions & 17 deletions tutorials/connect-jamf-pro-to-smallstep.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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**
Expand All @@ -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**
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down