Skip to content

Mosyle setup guide #481

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

Open
tashian wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Mosyle setup guide #481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c93d292
Draft of Mosyle setup guide
tashian Jan 21, 2026
31c656a
Updates to Mosyle docs
tashian Jan 21, 2026
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
4 changes: 4 additions & 0 deletions manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
283 changes: 283 additions & 0 deletions tutorials/connect-mosyle-to-smallstep.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,283 @@
---
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)
- A [Mosyle](https://mosyle.com/) Business 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:

- 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

<Aside type="tip">
We recommend creating a dedicated Mosyle administrator account for the Smallstep integration. This allows you to manage API access separately from personal administrator accounts and makes it easier to rotate credentials if needed. Use an account that has access to the device groups you will want to sync with Smallstep.
</Aside>

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 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 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

### Get Smallstep CA Details

After connecting Mosyle to Smallstep, you'll find all the certificate details you need on the Platform Settings page:

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

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

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
<?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>PayloadContent</key>
<array>
<dict>
<key>PayloadType</key>
<string>com.smallstep.Agent</string>
<key>PayloadIdentifier</key>
<string>com.smallstep.Agent.config</string>
<key>PayloadUUID</key>
<string>YOUR-UNIQUE-UUID-HERE</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>TeamSlug</key>
<string>YOUR-TEAM-SLUG</string>
<key>Certificate</key>
<string>mackms:label=$PROFILE_IDENTIFIER;se=false;tag=</string>
</dict>
</array>
<key>PayloadDisplayName</key>
<string>Smallstep Agent Configuration</string>
<key>PayloadIdentifier</key>
<string>com.smallstep.Agent.profile</string>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>YOUR-PROFILE-UUID-HERE</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>
```

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.