From c93d292566836e45c2153e8773dc70ddf2689512 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 21 Jan 2026 17:04:08 +0000 Subject: [PATCH 1/2] Draft of Mosyle setup guide --- tutorials/connect-mosyle-to-smallstep.mdx | 281 ++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 tutorials/connect-mosyle-to-smallstep.mdx diff --git a/tutorials/connect-mosyle-to-smallstep.mdx b/tutorials/connect-mosyle-to-smallstep.mdx new file mode 100644 index 00000000..35787ec5 --- /dev/null +++ b/tutorials/connect-mosyle-to-smallstep.mdx @@ -0,0 +1,281 @@ +--- +updated_at: January 21, 2026 +title: Connect Mosyle to Smallstep +html_title: Integrate Mosyle with Smallstep Tutorial +description: Integrate Mosyle with Smallstep for Apple device security. Complete guide for enforcing device trust in macOS and iOS environments. +--- + +Smallstep can integrate with Mosyle to synchronize your device inventory, and enroll your fleet with Smallstep using the Smallstep Agent. In this document, we will configure your Mosyle instance for use with your Smallstep team. + +This document also contains [uninstall instructions](#uninstall-smallstep-agent-with-mosyle). + +## Requirements & Limitations + +You will need: + +- A [Smallstep team](https://smallstep.com/signup) with Pro features enabled +- A [Mosyle](https://mosyle.com/) Business or Fuse tenant + +Client requirements: + +- The agent will need to reach the following domains: + ``` + smallstep.com + api.smallstep.com + gateway.smallstep.com + control.infra.smallstep.com + *.[team-name].ca.smallstep.com + auth.smallstep.com + att.smallstep.com + ``` + +Limitations: + +- Mosyle supports static SCEP only; dynamic SCEP challenges are not available. +- 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 + +## Create an API Token in Mosyle + +This API token will allow Smallstep to read your Mosyle device inventory for ongoing inventory syncing. + +1. In Mosyle, choose **Organization** from the top navigation +2. In the left sidebar, expand **Integrations** +3. Choose **Mosyle API Integration** +4. Choose **Add new token** +5. Configure the token: + - Profile name: `Smallstep` + - Access Method: `Public` + - Ensure **Allow all current and future endpoints** is checked +6. Choose **Save** +7. Temporarily save the **Access Token** that is displayed. You'll use it in the next step. + +## Connect Mosyle to Smallstep + +Let's add the Mosyle 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 Mosyle, choose ➕ **Connect** +3. Enter the API token from Mosyle +4. Choose **Add Platform**. Your device inventory will start syncing from Mosyle to Smallstep. + +Your Smallstep team is now linked to Mosyle. Smallstep will do a partial sync of your device inventory from Mosyle every hour, and a full sync every 8 hours. + +## Configure Certificates in Mosyle + +### Download Smallstep Authority Certificates + +1. In the Smallstep console, choose **Certificate Manager** +2. Select [Authorities](https://smallstep.com/app/?next=/cm/authorities) +3. Select the **Smallstep Agents** authority +4. Download the **Root Certificate** +5. Temporarily save the root certificate file + +### Get the SCEP Provisioner URL and Challenge + +1. In the Smallstep console, choose **Certificate Manager** +2. Select [Authorities](https://smallstep.com/app/?next=/cm/authorities) +3. Select the **Smallstep Agents** authority +4. Under the Provisioners section, choose the provisioner beginning with **`integration-mosyle`** +5. Temporarily save: + - The **SCEP URL**, e.g., `https://agents.example.ca.smallstep.com/scep/integration-mosyle-abc123` + - The **Static Challenge** value shown on the page + +### Upload the Root Certificate to Mosyle + +1. In Mosyle, choose **Management** from the top navigation +2. Use the platform dropdown in the left sidebar to select **macOS** +3. In the left sidebar, under **Management Profiles**, choose **Certificates / Custom Profiles** + - If this profile type is not visible, choose **Activate New Profile Type**, search for "Certificates", and activate **Certificates / Custom Profiles** +4. Choose **Add new profile** +5. Configure the certificate profile: + - Profile Name: `Smallstep Agents Root CA` + - Upload the root certificate file you downloaded earlier +6. Under **Profile Assignment**, choose **+ Add Assignment** and select your desired device groups +7. Choose **Save** + +### Create a SCEP Profile in Mosyle + +1. In Mosyle, choose **Management** from the top navigation +2. Use the platform dropdown in the left sidebar to select **macOS** +3. In the left sidebar, under **Management Profiles**, choose **SCEP** + - If this profile type is not visible, choose **Activate New Profile Type**, search for "SCEP", and activate **SCEP** +4. Choose **Add new profile** +5. Configure the SCEP profile: + - Profile Name: `Smallstep` + - URL: (paste the SCEP provisioner URL you saved earlier) + - Subject: `CN=%DeviceName%` (or customize as needed using Mosyle variables) + - Challenge: (paste the static challenge you saved earlier) + - Key Size (in bits): `2048` + - Check ☑️ **Allow all apps to access the certificate in the keychain** +6. Under **Profile Assignment**, choose **+ Add Assignment** and select your desired device groups +7. Choose **Save** + +## Install the Smallstep agent + +There are two ways to install the agent: + +- **via Mosyle** (below): Use Mosyle's package distribution and policy management +- **separately**: Use a separate software management tool like [Munki](https://www.munki.org/munki/), or install the agent manually via scripts. See the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#macos-installation) guide for detailed macOS installation instructions. + +### Install the agent via Mosyle + +#### Upload the Agent Package + +1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) +2. In Mosyle, choose **Management** from the top navigation +3. Use the platform dropdown in the left sidebar to select **macOS** +4. In the left sidebar, under **Management Profiles**, choose **Install PKG** + - If this profile type is not visible, choose **Activate New Profile Type**, search for "Install PKG", and activate it +5. Choose the **PKGs** tab, then choose **Add new package** +6. Upload the package you downloaded +7. Once uploaded, choose the **Profiles** tab, then choose **Add new profile** +8. Configure the profile: + - Profile Name: `Smallstep Agent` + - Select the SmallstepAgent package you uploaded +9. Under **Profile Assignment**, choose **+ Add Assignment** and select your desired device groups +10. Choose **Save** + +#### Configure the Agent Settings + +The Smallstep Agent requires configuration settings to connect to your Smallstep team. Create a custom configuration profile: + +1. In the Smallstep console, choose ⚙️ **Settings** +2. Temporarily save the **Team Slug** value +3. In Mosyle, choose **Management** from the top navigation +4. Ensure **macOS** is selected in the platform dropdown +5. In the left sidebar, under **Management Profiles**, choose **Certificates / Custom Profiles** +6. Choose **Add new profile** +7. Create a `.mobileconfig` file with the following content and upload it: + + ```xml + + + + + PayloadContent + + + PayloadType + com.smallstep.Agent + PayloadIdentifier + com.smallstep.Agent.config + PayloadUUID + YOUR-UNIQUE-UUID-HERE + PayloadVersion + 1 + TeamSlug + YOUR-TEAM-SLUG + Certificate + mackms:label=$PROFILE_IDENTIFIER;se=false;tag= + + + PayloadDisplayName + Smallstep Agent Configuration + PayloadIdentifier + com.smallstep.Agent.profile + PayloadType + Configuration + PayloadUUID + YOUR-PROFILE-UUID-HERE + PayloadVersion + 1 + + + ``` + + Replace `YOUR-TEAM-SLUG` with your actual team slug from Smallstep, and generate unique UUIDs for the `PayloadUUID` fields (you can use `uuidgen` on macOS). + +8. Configure the profile: + - Profile Name: `Smallstep Agent Configuration` +9. Under **Profile Assignment**, choose **+ Add Assignment** and select your desired device groups (should match the agent installation scope) +10. Choose **Save** + +#### Configure Login Items (macOS) + +To ensure the Smallstep Agent starts automatically on macOS devices: + +1. In Mosyle, choose **Management** from the top navigation +2. Ensure **macOS** is selected in the platform dropdown +3. In the left sidebar, under **Management Profiles**, choose **Login Items** + - If this profile type is not visible, choose **Activate New Profile Type**, search for "Login Items", and activate it +4. Choose **Add new profile** +5. Configure the profile: + - Profile Name: `Smallstep Login Item` + - Add a managed login item with: + - Rule Type: **Bundle Identifier** + - Rule Value: `com.smallstep.Agent` +6. Under **Profile Assignment**, choose **+ Add Assignment** and select your desired device groups +7. Choose **Save** + +## Confirmation + +There are 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.app/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 Mosyle + +You can remove the Smallstep Agent from macOS endpoints managed by Mosyle. + +### Remove the Agent Installation Profile + +1. In Mosyle, choose **Management** from the top navigation +2. Use the platform dropdown in the left sidebar to select **macOS** +3. In the left sidebar, under **Management Profiles**, choose **Install PKG** +4. In the **Profiles** tab, find and delete the **Smallstep Agent** profile + +### Remove the Configuration Profiles + +1. In Mosyle, choose **Management** from the top navigation +2. Use the platform dropdown in the left sidebar to select **macOS** +3. In the left sidebar, under **Management Profiles**, choose **Certificates / Custom Profiles** +4. Find and delete the **Smallstep Agent Configuration** profile +5. Find and delete the **Smallstep Agents Root CA** certificate profile + +### Remove the SCEP Profile + +1. In Mosyle, choose **Management** from the top navigation +2. Ensure **macOS** is selected in the platform dropdown +3. In the left sidebar, under **Management Profiles**, choose **SCEP** +4. Find and delete the **Smallstep** SCEP profile + +### Remove the Login Items Profile + +1. In Mosyle, choose **Management** from the top navigation +2. Ensure **macOS** is selected in the platform dropdown +3. In the left sidebar, under **Management Profiles**, choose **Login Items** +4. Find and delete the **Smallstep Login Item** profile + +### Create an Uninstall Script (Optional) + +For a complete cleanup, you can deploy an uninstall script: + +1. In Mosyle, choose **Management** from the top navigation +2. Ensure **macOS** is selected in the platform dropdown +3. In the left sidebar, under **Management Profiles**, choose **Custom Commands** +4. Create a new command with the following script: + + ```bash + #!/bin/bash + + launchctl stop com.smallstep.launchd.Agent + launchctl remove com.smallstep.launchd.Agent + + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent svc uninstall + rm -rf /Applications/SmallstepAgent.app + if pkgutil --packages | grep -q com.smallstep.Agent; then + pkgutil --forget com.smallstep.Agent + fi + ``` + +5. Assign this command to the devices you want to uninstall from +6. Once the uninstall is complete, remove the command profile + +### Confirm Uninstallation + +Verify that `/Applications/SmallstepAgent.app` no longer exists on target devices. From 31c656a8645e83c8383415a1a696d21530d15c9a Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 21 Jan 2026 20:23:50 +0000 Subject: [PATCH 2/2] Updates to Mosyle docs --- manifest.json | 4 ++ tutorials/connect-mosyle-to-smallstep.mdx | 46 ++++++++++++----------- 2 files changed, 28 insertions(+), 22 deletions(-) diff --git a/manifest.json b/manifest.json index 85f1af9c..172b1643 100644 --- a/manifest.json +++ b/manifest.json @@ -52,6 +52,10 @@ "title": "Connect Intune (macOS)", "path": "/tutorials/connect-intune-to-smallstep-macos.mdx" }, + { + "title": "Connect Mosyle", + "path": "/tutorials/connect-mosyle-to-smallstep.mdx" + }, { "title": "Connect Jamf Pro", "path": "/tutorials/connect-jamf-pro-to-smallstep.mdx" diff --git a/tutorials/connect-mosyle-to-smallstep.mdx b/tutorials/connect-mosyle-to-smallstep.mdx index 35787ec5..f99b9938 100644 --- a/tutorials/connect-mosyle-to-smallstep.mdx +++ b/tutorials/connect-mosyle-to-smallstep.mdx @@ -13,8 +13,8 @@ This document also contains [uninstall instructions](#uninstall-smallstep-agent- You will need: -- A [Smallstep team](https://smallstep.com/signup) with Pro features enabled -- A [Mosyle](https://mosyle.com/) Business or Fuse tenant +- A [Smallstep team](https://smallstep.com/signup) +- A [Mosyle](https://mosyle.com/) Business tenant Client requirements: @@ -31,14 +31,17 @@ Client requirements: Limitations: -- Mosyle supports static SCEP only; dynamic SCEP challenges are not available. -- For VPN configurations, only IPSec VPNs are currently supported. -- "Always-on VPN" or device-wide VPNs are not yet supported in Smallstep-managed configurations. +- Devices must be assigned to a device group in Mosyle to be synced with Smallstep. Devices not in any device group will not appear in your Smallstep inventory. +- Mosyle supports static SCEP ## Step-by-step instructions ## Create an API Token in Mosyle + + This API token will allow Smallstep to read your Mosyle device inventory for ongoing inventory syncing. 1. In Mosyle, choose **Organization** from the top navigation @@ -54,34 +57,33 @@ This API token will allow Smallstep to read your Mosyle device inventory for ong ## Connect Mosyle to Smallstep -Let's add the Mosyle API credentials you just created to Smallstep. +Let's add the Mosyle credentials to Smallstep. You'll need the API token you created, plus the email and password of a Mosyle administrator account. 1. In the Smallstep UI, go to the [**Device Management**](https://smallstep.com/app/?next=/settings/devices) tab in ⛭ **Settings** 2. Under Mosyle, choose ➕ **Connect** -3. Enter the API token from Mosyle -4. Choose **Add Platform**. Your device inventory will start syncing from Mosyle to Smallstep. +3. Enter the following credentials: + - **Account Email**: The email address of a Mosyle administrator account + - **Account Password**: The password for that Mosyle administrator account + - **API Access Token**: The API token you created in the previous step + - **Name/Alias** (optional): A friendly name for this connection +4. Choose **Connect MDM**. Your device inventory will start syncing from Mosyle to Smallstep. Your Smallstep team is now linked to Mosyle. Smallstep will do a partial sync of your device inventory from Mosyle every hour, and a full sync every 8 hours. ## Configure Certificates in Mosyle -### Download Smallstep Authority Certificates +### Get Smallstep CA Details -1. In the Smallstep console, choose **Certificate Manager** -2. Select [Authorities](https://smallstep.com/app/?next=/cm/authorities) -3. Select the **Smallstep Agents** authority -4. Download the **Root Certificate** -5. Temporarily save the root certificate file +After connecting Mosyle to Smallstep, you'll find all the certificate details you need on the Platform Settings page: -### Get the SCEP Provisioner URL and Challenge +1. In the Smallstep console, go to [**Device Management**](https://smallstep.com/app/?next=/settings/devices) in **Settings** +2. Click on your Mosyle connection +3. From this page, you can: + - Download the **Root Certificate** file + - Copy the **SCEP URL** (e.g., `https://agents.example.ca.smallstep.com/scep/integration-mosyle-abc123`) + - Copy the **SCEP Challenge** value -1. In the Smallstep console, choose **Certificate Manager** -2. Select [Authorities](https://smallstep.com/app/?next=/cm/authorities) -3. Select the **Smallstep Agents** authority -4. Under the Provisioners section, choose the provisioner beginning with **`integration-mosyle`** -5. Temporarily save: - - The **SCEP URL**, e.g., `https://agents.example.ca.smallstep.com/scep/integration-mosyle-abc123` - - The **Static Challenge** value shown on the page +Keep this page open or save these values temporarily—you'll need them for the Mosyle configuration steps below. ### Upload the Root Certificate to Mosyle