Skip to content

Commit 4aa586f

Browse files
JoshDrake-mintedjoshdrake
JoshDrake-minted
authored and
joshdrake
committed
Add documentation for Fleet integration.
1 parent 16fb36f commit 4aa586f

1 file changed

Lines changed: 256 additions & 12 deletions

File tree

‎tutorials/connect-fleet-dm-to-smallstep.mdx‎

Lines changed: 256 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,275 @@
11
---
2-
updated_at: November 11, 2025
2+
updated_at: January 26, 2026
33
title: Connect Fleet DM to Smallstep
4-
description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates to your managed fleet using Fleet's device management platform.
4+
html_title: Integrate Fleet DM with Smallstep Tutorial
5+
description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates and syncing device inventory using Fleet's device management platform.
56
---
67

7-
Smallstep can integrate with Fleet DM to deploy certificates to your Fleet-managed devices.
8+
Smallstep can integrate with [Fleet DM](https://fleetdm.com/) to deploy certificates to your Fleet-managed devices. Fleet has a native Smallstep integration that makes it easy to configure Dynamic SCEP for certificate enrollment.
9+
10+
In this document, we will configure your Fleet instance for use with your Smallstep team.
811

912
## Requirements
1013

1114
You will need:
1215

13-
- A [Smallstep team](https://smallstep.com/signup)
14-
- A [Fleet DM](https://fleetdm.com/) instance
16+
- A [Smallstep team](https://smallstep.com/signup) with Pro features enabled
17+
- A [Fleet DM](https://fleetdm.com/) instance with MDM enabled for your target platforms
18+
19+
Client requirements:
20+
21+
- For SCEP certificate enrollment, devices must be MDM-enrolled in Fleet
22+
- The Smallstep agent will need to reach the following domains:
23+
```
24+
smallstep.com
25+
api.smallstep.com
26+
gateway.smallstep.com
27+
control.infra.smallstep.com
28+
*.[team-name].ca.smallstep.com
29+
auth.smallstep.com
30+
att.smallstep.com
31+
```
32+
33+
Supported platforms:
34+
35+
- macOS, iOS, iPadOS (via .mobileconfig profiles)
36+
- Windows (via .xml profiles)
37+
38+
## Step-by-step instructions
39+
40+
### 1. Get SCEP credentials from Smallstep
41+
42+
First, you'll configure Smallstep and gather the SCEP credentials needed for Fleet.
43+
44+
1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices)
45+
2. Under Available Providers, find **Jamf** and click **Connect**
46+
47+
<Alert severity="info">
48+
<div>
49+
Fleet uses the same SCEP integration as Jamf. Select Jamf as the provider type in Smallstep.
50+
</div>
51+
</Alert>
52+
53+
3. Enter your Jamf Pro Server URL (you can use a placeholder value like `https://fleet.example.com` since Fleet doesn't require this connection)
54+
4. After connecting, temporarily save the following values:
55+
- **SCEP URL** (e.g., `https://wifi.example.ca.smallstep.com/scep/integration-jamf-abc123`)
56+
- **SCEP Challenge URL** (e.g., `https://wifi.example.ca.smallstep.com/jamf/abc123-def456/challenge`)
57+
- **Challenge Basic Authentication Username**
58+
- **Challenge Basic Authentication Password**
59+
60+
### 2. Add the Smallstep Certificate Authority in Fleet
61+
62+
Now we'll add the Smallstep SCEP credentials to Fleet.
63+
64+
1. In Fleet, go to **Settings** (click your profile icon in the top right)
65+
2. Navigate to **Integrations → Certificate authorities**
66+
3. Click **Add CA**
67+
4. From the dropdown, select **Smallstep**
68+
5. Fill in the fields:
69+
- **Name**: A unique identifier using letters, numbers, and underscores only (e.g., `WIFI_CERTIFICATE`). Fleet will create configuration profile variables with this name as a suffix.
70+
- **SCEP URL**: Paste the SCEP URL from Smallstep
71+
- **Challenge URL**: Paste the SCEP Challenge URL from Smallstep
72+
- **Username**: Paste the Challenge Basic Authentication Username
73+
- **Password**: Paste the Challenge Basic Authentication Password
74+
6. Click **Add CA**
75+
76+
### 3. Create a SCEP configuration profile
77+
78+
Fleet deploys certificates to devices using configuration profiles. You'll need to create a profile that includes the SCEP payload with Fleet's dynamic variables.
79+
80+
Fleet provides these variables for Smallstep certificate enrollment:
81+
82+
| Variable | Description |
83+
|----------|-------------|
84+
| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_{CA_NAME}` | The dynamic SCEP challenge string |
85+
| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_{CA_NAME}` | The SCEP proxy URL for certificate requests |
86+
| `$FLEET_VAR_SCEP_RENEWAL_ID` | A unique renewal identifier for the device |
87+
| `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` | The end user's email from the identity provider |
88+
89+
Replace `{CA_NAME}` with the name you configured in Step 2 (e.g., `WIFI_CERTIFICATE`).
90+
91+
#### Example macOS/iOS SCEP profile
92+
93+
Create a `.mobileconfig` file with the following structure. This example is for Wi-Fi authentication:
94+
95+
```xml
96+
<?xml version="1.0" encoding="UTF-8"?>
97+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
98+
<plist version="1.0">
99+
<dict>
100+
<key>PayloadContent</key>
101+
<array>
102+
<dict>
103+
<key>PayloadDisplayName</key>
104+
<string>Smallstep SCEP</string>
105+
<key>PayloadIdentifier</key>
106+
<string>com.smallstep.scep</string>
107+
<key>PayloadType</key>
108+
<string>com.apple.security.scep</string>
109+
<key>PayloadUUID</key>
110+
<string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
111+
<key>PayloadVersion</key>
112+
<integer>1</integer>
113+
<key>PayloadContent</key>
114+
<dict>
115+
<key>Challenge</key>
116+
<string>$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_WIFI_CERTIFICATE</string>
117+
<key>Key Type</key>
118+
<string>RSA</string>
119+
<key>Key Usage</key>
120+
<integer>5</integer>
121+
<key>Keysize</key>
122+
<integer>2048</integer>
123+
<key>Subject</key>
124+
<array>
125+
<array>
126+
<array>
127+
<string>CN</string>
128+
<string>$FLEET_VAR_HOST_END_USER_EMAIL_IDP</string>
129+
</array>
130+
</array>
131+
<array>
132+
<array>
133+
<string>OU</string>
134+
<string>$FLEET_VAR_SCEP_RENEWAL_ID</string>
135+
</array>
136+
</array>
137+
</array>
138+
<key>URL</key>
139+
<string>$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_WIFI_CERTIFICATE</string>
140+
</dict>
141+
</dict>
142+
</array>
143+
<key>PayloadDisplayName</key>
144+
<string>Smallstep Certificate</string>
145+
<key>PayloadIdentifier</key>
146+
<string>com.smallstep.certificate-profile</string>
147+
<key>PayloadType</key>
148+
<string>Configuration</string>
149+
<key>PayloadUUID</key>
150+
<string>12345678-90AB-CDEF-1234-567890ABCDEF</string>
151+
<key>PayloadVersion</key>
152+
<integer>1</integer>
153+
</dict>
154+
</plist>
155+
```
156+
157+
<Alert severity="info">
158+
<div>
159+
Replace `WIFI_CERTIFICATE` in the variable names with the CA name you configured in Fleet.
160+
</div>
161+
</Alert>
162+
163+
### 4. Deploy the configuration profile
164+
165+
1. In Fleet, go to **Controls → OS settings → Custom settings**
166+
2. Click **Add profile**
167+
3. Upload your `.mobileconfig` file
168+
4. Assign the profile to your desired scope (teams or all devices)
169+
170+
The profile will be deployed to devices at their next check-in. Fleet will automatically substitute the variables with the appropriate values for each device.
171+
172+
## Deploy the Smallstep agent (optional)
173+
174+
Though not required for SCEP certificate enrollment, we recommend deploying the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent makes it easier to configure endpoints and manage certificates for additional use cases like VPN authentication.
175+
176+
You can deploy the agent using Fleet's software management features:
177+
178+
1. Download the agent package:
179+
- macOS: [step-agent-plugin_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg)
180+
- Windows (x64): [step-agent-plugin_latest_amd64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi)
181+
- Windows (ARM64): [step-agent-plugin_latest_arm64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_arm64.msi)
182+
183+
2. In Fleet, go to **Software** and add the package for distribution
184+
3. Use Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) to install the agent on your devices
185+
4. Configure the agent using Fleet's [scripting features](https://fleetdm.com/guides/scripts) or a separate configuration profile
186+
187+
Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See [install via a software management tool](https://smallstep.com/docs/tutorials/connect-jamf-pro-to-smallstep/#option-2-install-via-a-software-management-tool) for details.
188+
189+
## Confirmation
190+
191+
To confirm certificate deployment:
192+
193+
1. In Fleet, go to **Hosts** and select a device that received the profile
194+
2. Check the **OS settings** status to verify the profile was applied successfully
195+
3. In the Smallstep console, go to **Devices** to verify the device has enrolled and received a certificate
196+
197+
On the device itself:
198+
199+
- **macOS**: Open **Keychain Access** and look for a certificate issued by your Smallstep authority
200+
- **iOS/iPadOS**: Go to **Settings → General → VPN & Device Management** to view installed profiles
201+
- **Windows**: Open **certmgr.msc** and check the Personal certificates store
202+
203+
## Device sync
204+
205+
To sync your device inventory from Fleet to Smallstep, you'll create an API user in Fleet and configure the connection in Smallstep.
206+
207+
### 1. Create an API-only user in Fleet
208+
209+
An API-only user is a Fleet user that cannot log into the Fleet UI and is intended for automated integrations. The default **Observer** role provides read-only access to host information, which is all Smallstep needs for device sync.
210+
211+
You'll need the [fleetctl CLI](https://fleetdm.com/guides/fleetctl#installing-fleetctl) tool installed and authenticated with admin privileges to create an API-only user.
212+
213+
1. Configure fleetctl with your Fleet server address:
214+
215+
```bash
216+
fleetctl config set --address 'https://fleet.example.com'
217+
```
218+
219+
2. Log in with your admin credentials:
220+
221+
```bash
222+
fleetctl login
223+
```
224+
225+
3. Create the API-only user:
226+
227+
```bash
228+
fleetctl user create --name 'Smallstep' \
229+
--email 'smallstep-api@example.com' \
230+
--password 'your-secure-password' \
231+
--api-only
232+
```
233+
234+
4. The command will output an API token:
235+
236+
```
237+
Success! The API token for your new user is: <TOKEN>
238+
```
239+
240+
Copy this token—you'll need it for the next step.
15241

242+
<Alert severity="info">
243+
<div>
244+
The default role for API-only users is **Observer**, which grants read-only access to hosts and device information. This is the appropriate permission level for Smallstep device sync.
245+
</div>
246+
</Alert>
16247

17-
## Configure device sync (coming soon)
248+
### 2. Connect Fleet to Smallstep
18249

19-
To sync your devices from Fleet DM, create an [API-only user](https://fleetdm.com/guides/fleetctl#using-fleetctl-with-an-api-only-user) in Fleet DM, and then put the token into the Fleet settings in Smallstep.
250+
Now you'll add your Fleet API credentials to Smallstep.
20251

21-
## Configure Dynamic SCEP
252+
1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices)
253+
2. Under Available Providers, find **Fleet** and click **Connect**
254+
3. Fill in the fields:
255+
- **API Base URL**: Your Fleet server URL (e.g., `https://fleet.example.com`)
256+
- **API Token**: Paste the API token from the previous step
257+
- **Name/Alias**: An optional identifier for this connection (e.g., `Production Fleet`)
258+
4. Click **Connect MDM**
22259

23-
To configure Fleet to use Dynamic SCEP for certificate issuance to your endpoints, follow the instructions in **[Connect end user to WiFi with certificate (Smallstep)](https://fleetdm.com/guides/connect-end-user-to-wifi-with-certificate#smallstep)**
260+
Within a few minutes, you will see your Fleet devices in the [Devices](https://smallstep.com/app/?next=/devices/all) tab. Your Smallstep device inventory syncs from Fleet approximately every four hours.
24261

25-
## Deploy the Smallstep agent
262+
### Alternative: Get an API token from the Fleet UI
26263

27-
Though not required, we suggest deploying the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent makes it easier to configure endpoints and manage certificates. You can deploy the agent [using Fleet's software management](https://fleetdm.com/guides/deploy-software-packages) and [scripting features](https://fleetdm.com/guides/scripts).
264+
If you prefer not to create a dedicated API-only user, you can generate an API token for an existing user:
28265

29-
Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See [install via a software management tool](http://smallstep.com/docs/tutorials/connect-jamf-pro-to-smallstep/#option-2-install-via-a-software-management-tool) for details.
266+
1. In Fleet, click your profile icon in the top right and select **My account**
267+
2. Click **Get API token**
268+
3. Copy the token and use it in Smallstep's Fleet connection settings
30269

270+
<Alert severity="warning">
271+
<div>
272+
For production use, we recommend creating a dedicated API-only user rather than using a personal account token. This provides better security isolation and ensures the integration continues to work if individual users leave the organization.
273+
</div>
274+
</Alert>
31275

0 commit comments

Comments
 (0)