From ce61babe00dc86df9b8794bda6c3f10a4a7ac236 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 Aug 2025 13:38:51 -0500 Subject: [PATCH 1/3] Add manual install instructions for agent --- tutorials/connect-jamf-pro-to-smallstep.mdx | 66 +++++++++++++++++---- 1 file changed, 53 insertions(+), 13 deletions(-) diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index 70079eb6..489c2d7d 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/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. @@ -37,7 +37,7 @@ Limitations: # 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,7 +59,7 @@ 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 to Smallstep Let’s add the Jamf API credentials you just created to Smallstep. @@ -69,7 +69,7 @@ Let’s add the Jamf API credentials you just created to Smallstep. 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. @@ -86,7 +86,49 @@ 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. Smallstep will do a partial sync of your device inventory from Jamf every hour, and a full sync every 8 hours. + +## Install the Smallstep agent + +There's two ways to install the agent: Using Jamf, 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 organizatoin. + +### Option: Install using 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 endpoints +3. Add the following user launch agent file in `/Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist`: + + ``` + + + + + Label + com.smallstep.launchd.Agent + ProgramArguments + + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent + start + managed + + KeepAlive + + RunAtLoad + + AssociatedBundleIdentifiers + com.smallstep.Agent + + + ``` + +4. Register the launch agent with `launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` + +### Option: Install the agent via Jamf + +#### Create an Agent Package for Distribution In this step, you’ll upload the Smallstep agent package to Jamf’s distribution network. @@ -210,11 +252,9 @@ 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 +## 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. @@ -225,7 +265,7 @@ There's two ways to confirm installation on an endpoint: You can easily remove a Smallstep Agent that was installed on macOS endpoints via Jamf Pro. -### Remove the Agent Install Policy and Script +## Remove the Agent Install Policy and Script If you still have the Policy and Script that install the Smallstep Agent, remove those first. @@ -236,7 +276,7 @@ If you still have the Policy and Script that install the Smallstep Agent, remove 5. Under the **Computer Management** tab, choose **Policies** 6. Delete the **Smallstep Agent** policy -### Create an Agent Uninstall Script +## Create an Agent Uninstall Script This step will install a script on your client devices that uninstalls the Smallstep Agent. @@ -261,7 +301,7 @@ This step will install a script on your client devices that uninstalls the Small 4. Choose **Save** -### Create a New Policy for Uninstallation +## Create a New Policy for Uninstallation Next, we’ll configure the Script we just created to run on your client devices. @@ -280,10 +320,10 @@ Next, we’ll configure the Script we just created to run on your client devices 3. Under Scope, select your desired policy scope. The agent will be uninstalled from all devices in this scope. 4. Choose **Save** -### Confirm Uninstallation +## Confirm Uninstallation Use **Logs** in Jamf Pro to confirm the uninstallation process completed successfully. -### Cleanup +## Cleanup Once the agent is uninstalled from all endpoints, remove the Policy and Script you created for uninstallation. From b37eff7b232fbbdaceaaebcaa3764b3bacbc0e29 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 Aug 2025 13:49:45 -0500 Subject: [PATCH 2/3] Cleanups --- tutorials/connect-jamf-pro-to-smallstep.mdx | 87 +++++++++++---------- 1 file changed, 47 insertions(+), 40 deletions(-) diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index 489c2d7d..72089f1f 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/tutorials/connect-jamf-pro-to-smallstep.mdx @@ -59,9 +59,9 @@ 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** @@ -86,46 +86,13 @@ For compatibility reasons, Smallstep may use ACME or SCEP for certificate enroll 5. Webhook Event: SCEPChallenge 4. 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. +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. ## Install the Smallstep agent -There's two ways to install the agent: Using Jamf, or using a separate software management tool. +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 organizatoin. -### Option: Install using 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 endpoints -3. Add the following user launch agent file in `/Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist`: - - ``` - - - - - Label - com.smallstep.launchd.Agent - ProgramArguments - - /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent - start - managed - - KeepAlive - - RunAtLoad - - AssociatedBundleIdentifiers - com.smallstep.Agent - - - ``` - -4. Register the launch agent with `launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` - ### Option: Install the agent via Jamf #### Create an Agent Package for Distribution @@ -140,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. @@ -159,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. @@ -182,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. @@ -254,6 +221,46 @@ In this step, we’ll tie everything together by creating a managed policy to en The devices that you scoped will receive a certificate and have the agent installed and running. +### Option: Install using 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//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—it must be installed for a single user: + + ``` + + + + + Label + com.smallstep.launchd.Agent + ProgramArguments + + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent + start + managed + + KeepAlive + + RunAtLoad + + AssociatedBundleIdentifiers + com.smallstep.Agent + + + ``` + +4. On the endpoint, register the launch agent by running the following: + + ``` + launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` + ``` + + ## Confirmation There's two ways to confirm installation on an endpoint: From ee232ec0f5d992f52cba2134e6fa3c9fafa8b9c6 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 21 Aug 2025 13:54:18 -0500 Subject: [PATCH 3/3] Add manual install optoin --- tutorials/connect-jamf-pro-to-smallstep.mdx | 27 +++++++++++---------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index 72089f1f..37190f87 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/tutorials/connect-jamf-pro-to-smallstep.mdx @@ -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,7 +35,7 @@ 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 @@ -71,7 +71,7 @@ Let’s add the Jamf Pro API credentials you just created to Smallstep. ## 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** @@ -91,13 +91,13 @@ Your Smallstep team is now linked to Jamf Pro. Smallstep will do a partial sync ## 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 organizatoin. +For example, [Munki](https://www.munki.org/munki/) is a popular option for managing macOS apps in a large IT organization. -### Option: Install the agent via Jamf +### 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’s distribution network. +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** @@ -221,7 +221,7 @@ In this step, we’ll tie everything together by creating a managed policy to en The devices that you scoped will receive a certificate and have the agent installed and running. -### Option: Install using a software management tool +### Option 2: Install via a software management tool If you're using a software management tool: @@ -264,15 +264,16 @@ If you're using a software management tool: ## 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. -## Remove the Agent Install Policy and Script +### Remove the Agent Install Policy and Script If you still have the Policy and Script that install the Smallstep Agent, remove those first. @@ -283,7 +284,7 @@ If you still have the Policy and Script that install the Smallstep Agent, remove 5. Under the **Computer Management** tab, choose **Policies** 6. Delete the **Smallstep Agent** policy -## Create an Agent Uninstall Script +### Create an Agent Uninstall Script This step will install a script on your client devices that uninstalls the Smallstep Agent. @@ -308,7 +309,7 @@ This step will install a script on your client devices that uninstalls the Small 4. Choose **Save** -## Create a New Policy for Uninstallation +### Create a New Policy for Uninstallation Next, we’ll configure the Script we just created to run on your client devices. @@ -327,10 +328,10 @@ Next, we’ll configure the Script we just created to run on your client devices 3. Under Scope, select your desired policy scope. The agent will be uninstalled from all devices in this scope. 4. Choose **Save** -## Confirm Uninstallation +### Confirm Uninstallation Use **Logs** in Jamf Pro to confirm the uninstallation process completed successfully. -## Cleanup +### Cleanup Once the agent is uninstalled from all endpoints, remove the Policy and Script you created for uninstallation.