From 4aa586f852671609cdfa5c2698a583bf000f50c1 Mon Sep 17 00:00:00 2001 From: Josh Drake Date: Mon, 26 Jan 2026 09:58:42 -0600 Subject: [PATCH 1/4] Add documentation for Fleet integration. --- tutorials/connect-fleet-dm-to-smallstep.mdx | 268 +++++++++++++++++++- 1 file changed, 256 insertions(+), 12 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index df6c0c4b..33d33801 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -1,31 +1,275 @@ --- -updated_at: November 11, 2025 +updated_at: January 26, 2026 title: Connect Fleet DM to Smallstep -description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates to your managed fleet using Fleet's device management platform. +html_title: Integrate Fleet DM with Smallstep Tutorial +description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates and syncing device inventory using Fleet's device management platform. --- -Smallstep can integrate with Fleet DM to deploy certificates to your Fleet-managed devices. +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. + +In this document, we will configure your Fleet instance for use with your Smallstep team. ## Requirements You will need: -- A [Smallstep team](https://smallstep.com/signup) -- A [Fleet DM](https://fleetdm.com/) instance +- A [Smallstep team](https://smallstep.com/signup) with Pro features enabled +- A [Fleet DM](https://fleetdm.com/) instance with MDM enabled for your target platforms + +Client requirements: + +- For SCEP certificate enrollment, devices must be MDM-enrolled in Fleet +- The Smallstep 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 + ``` + +Supported platforms: + +- macOS, iOS, iPadOS (via .mobileconfig profiles) +- Windows (via .xml profiles) + +## Step-by-step instructions + +### 1. Get SCEP credentials from Smallstep + +First, you'll configure Smallstep and gather the SCEP credentials needed for Fleet. + +1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) +2. Under Available Providers, find **Jamf** and click **Connect** + + +
+ Fleet uses the same SCEP integration as Jamf. Select Jamf as the provider type in Smallstep. +
+ + +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) +4. After connecting, temporarily save the following values: + - **SCEP URL** (e.g., `https://wifi.example.ca.smallstep.com/scep/integration-jamf-abc123`) + - **SCEP Challenge URL** (e.g., `https://wifi.example.ca.smallstep.com/jamf/abc123-def456/challenge`) + - **Challenge Basic Authentication Username** + - **Challenge Basic Authentication Password** + +### 2. Add the Smallstep Certificate Authority in Fleet + +Now we'll add the Smallstep SCEP credentials to Fleet. + +1. In Fleet, go to **Settings** (click your profile icon in the top right) +2. Navigate to **Integrations → Certificate authorities** +3. Click **Add CA** +4. From the dropdown, select **Smallstep** +5. Fill in the fields: + - **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. + - **SCEP URL**: Paste the SCEP URL from Smallstep + - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep + - **Username**: Paste the Challenge Basic Authentication Username + - **Password**: Paste the Challenge Basic Authentication Password +6. Click **Add CA** + +### 3. Create a SCEP configuration profile + +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. + +Fleet provides these variables for Smallstep certificate enrollment: + +| Variable | Description | +|----------|-------------| +| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_{CA_NAME}` | The dynamic SCEP challenge string | +| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_{CA_NAME}` | The SCEP proxy URL for certificate requests | +| `$FLEET_VAR_SCEP_RENEWAL_ID` | A unique renewal identifier for the device | +| `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` | The end user's email from the identity provider | + +Replace `{CA_NAME}` with the name you configured in Step 2 (e.g., `WIFI_CERTIFICATE`). + +#### Example macOS/iOS SCEP profile + +Create a `.mobileconfig` file with the following structure. This example is for Wi-Fi authentication: + +```xml + + + + + PayloadContent + + + PayloadDisplayName + Smallstep SCEP + PayloadIdentifier + com.smallstep.scep + PayloadType + com.apple.security.scep + PayloadUUID + A1B2C3D4-E5F6-7890-ABCD-EF1234567890 + PayloadVersion + 1 + PayloadContent + + Challenge + $FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_WIFI_CERTIFICATE + Key Type + RSA + Key Usage + 5 + Keysize + 2048 + Subject + + + + CN + $FLEET_VAR_HOST_END_USER_EMAIL_IDP + + + + + OU + $FLEET_VAR_SCEP_RENEWAL_ID + + + + URL + $FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_WIFI_CERTIFICATE + + + + PayloadDisplayName + Smallstep Certificate + PayloadIdentifier + com.smallstep.certificate-profile + PayloadType + Configuration + PayloadUUID + 12345678-90AB-CDEF-1234-567890ABCDEF + PayloadVersion + 1 + + +``` + + +
+Replace `WIFI_CERTIFICATE` in the variable names with the CA name you configured in Fleet. +
+ + +### 4. Deploy the configuration profile + +1. In Fleet, go to **Controls → OS settings → Custom settings** +2. Click **Add profile** +3. Upload your `.mobileconfig` file +4. Assign the profile to your desired scope (teams or all devices) + +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. + +## Deploy the Smallstep agent (optional) + +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. + +You can deploy the agent using Fleet's software management features: + +1. Download the agent package: + - macOS: [step-agent-plugin_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) + - Windows (x64): [step-agent-plugin_latest_amd64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi) + - Windows (ARM64): [step-agent-plugin_latest_arm64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_arm64.msi) + +2. In Fleet, go to **Software** and add the package for distribution +3. Use Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) to install the agent on your devices +4. Configure the agent using Fleet's [scripting features](https://fleetdm.com/guides/scripts) or a separate configuration profile + +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. + +## Confirmation + +To confirm certificate deployment: + +1. In Fleet, go to **Hosts** and select a device that received the profile +2. Check the **OS settings** status to verify the profile was applied successfully +3. In the Smallstep console, go to **Devices** to verify the device has enrolled and received a certificate + +On the device itself: + +- **macOS**: Open **Keychain Access** and look for a certificate issued by your Smallstep authority +- **iOS/iPadOS**: Go to **Settings → General → VPN & Device Management** to view installed profiles +- **Windows**: Open **certmgr.msc** and check the Personal certificates store + +## Device sync + +To sync your device inventory from Fleet to Smallstep, you'll create an API user in Fleet and configure the connection in Smallstep. + +### 1. Create an API-only user in Fleet + +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. + +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. + +1. Configure fleetctl with your Fleet server address: + + ```bash + fleetctl config set --address 'https://fleet.example.com' + ``` + +2. Log in with your admin credentials: + + ```bash + fleetctl login + ``` + +3. Create the API-only user: + + ```bash + fleetctl user create --name 'Smallstep' \ + --email 'smallstep-api@example.com' \ + --password 'your-secure-password' \ + --api-only + ``` + +4. The command will output an API token: + + ``` + Success! The API token for your new user is: + ``` + + Copy this token—you'll need it for the next step. + +
+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. +
+ -## Configure device sync (coming soon) +### 2. Connect Fleet to Smallstep -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. +Now you'll add your Fleet API credentials to Smallstep. -## Configure Dynamic SCEP +1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) +2. Under Available Providers, find **Fleet** and click **Connect** +3. Fill in the fields: + - **API Base URL**: Your Fleet server URL (e.g., `https://fleet.example.com`) + - **API Token**: Paste the API token from the previous step + - **Name/Alias**: An optional identifier for this connection (e.g., `Production Fleet`) +4. Click **Connect MDM** -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)** +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. -## Deploy the Smallstep agent +### Alternative: Get an API token from the Fleet UI -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). +If you prefer not to create a dedicated API-only user, you can generate an API token for an existing user: -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. +1. In Fleet, click your profile icon in the top right and select **My account** +2. Click **Get API token** +3. Copy the token and use it in Smallstep's Fleet connection settings + +
+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. +
+ From fd7e83bcf0b1cce74b13663ccdba8cc3f5f23d6f Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 5 Feb 2026 14:05:32 -0800 Subject: [PATCH 2/4] Many updates from QA session --- tutorials/connect-fleet-dm-to-smallstep.mdx | 412 ++++++++++++++------ 1 file changed, 295 insertions(+), 117 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 94000c2b..c93b07f7 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: February 03, 2026 +updated_at: February 05, 2026 title: Connect Fleet DM to Smallstep html_title: Integrate Fleet DM with Smallstep Tutorial description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates and syncing device inventory using Fleet's device management platform. @@ -32,34 +32,89 @@ Client requirements: Supported platforms: -- macOS, iOS, iPadOS (via .mobileconfig profiles) -- Windows (via .xml profiles) +- macOS, iOS, iPadOS (via `.mobileconfig` profiles) +- Windows (via `.xml` SyncML profiles) -## Configure dynamic SCEP +## Device sync -## Step-by-step instructions +To sync your device inventory from Fleet to Smallstep, you'll create an API user in Fleet and configure the connection in Smallstep. -### 1. Get SCEP credentials from Smallstep +### 1. Create an API-only user in Fleet -First, you'll configure Smallstep and gather the SCEP credentials needed for Fleet. +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. -1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) -2. Under Available Providers, find **Jamf** and click **Connect** +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. + +1. Configure fleetctl with your Fleet server address: + + ```bash + fleetctl config set --address 'https://fleet.example.com' + ``` + +2. Log in with your admin credentials: + + ```bash + fleetctl login + ``` + +3. Create the API-only user: + + ```bash + fleetctl user create --name 'Smallstep' \ + --email 'smallstep-api@example.com' \ + --password 'your-secure-password' \ + --api-only + ``` + +4. The command will output an API token: + + ``` + Success! The API token for your new user is: + ``` + + Copy this token—you'll need it for the next step. + + +
+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. +
+ + +### Alternative: Get an API token from the Fleet UI - -
- Fleet uses the same SCEP integration as Jamf. Select Jamf as the provider type in Smallstep. -
- +If you prefer not to create a dedicated API-only user, you can generate an API token for an existing user: + +1. In Fleet, click your profile icon in the top right and select **My account** +2. Click **Get API token** +3. Copy the token and use it in Smallstep's Fleet connection settings + + +
+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. +
+ -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) -4. After connecting, temporarily save the following values: - - **SCEP URL** (e.g., `https://wifi.example.ca.smallstep.com/scep/integration-jamf-abc123`) - - **SCEP Challenge URL** (e.g., `https://wifi.example.ca.smallstep.com/jamf/abc123-def456/challenge`) - - **Challenge Basic Authentication Username** - - **Challenge Basic Authentication Password** +### 2. Connect Fleet to Smallstep + +Now you'll add your Fleet API credentials to Smallstep. + +1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) +2. Under Available Providers, find **Fleet** and click **Connect** +3. Fill in the fields: + - **API Base URL**: Your Fleet server URL (for example, `https://fleet.example.com`) + - **API Token**: Paste the API token from the previous step + - **Name/Alias**: An optional identifier for this connection (for example, `Production Fleet`) +4. Click **Connect MDM** +5. After connecting, temporarily save the following values: + - **SCEP URL** (for example, `https://your-team.scep.smallstep.com/p/agents/integration-fleet-abc123`) + - **SCEP Challenge URL** (for example, `https://your-team.scep.smallstep.com/webhook/abc123-def4-5678-9abc-def012345678/challenge`) + - **Challenge Username** + - **Challenge Password** + - Under **Authority Certificates**, download the Root CA certificate. + +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. -### 2. Add the Smallstep Certificate Authority in Fleet +### 3. Add the Smallstep Certificate Authority in Fleet Now we'll add the Smallstep SCEP credentials to Fleet. @@ -68,14 +123,16 @@ Now we'll add the Smallstep SCEP credentials to Fleet. 3. Click **Add CA** 4. From the dropdown, select **Smallstep** 5. Fill in the fields: - - **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. + - **Name**: A unique identifier using letters, numbers, and underscores only (for example, `SMALLSTEP_AGENT`). Fleet will create configuration profile variables with this name as a suffix. - **SCEP URL**: Paste the SCEP URL from Smallstep - - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep - - **Username**: Paste the Challenge Basic Authentication Username - - **Password**: Paste the Challenge Basic Authentication Password + - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep (Fleet calls this "Challenge URL") + - **Username**: Paste the Challenge Username from Smallstep + - **Password**: Paste the Challenge Password from Smallstep 6. Click **Add CA** -### 3. Create a SCEP configuration profile +Fleet will test the CA connection after you create it. + +### 4. Create a SCEP configuration profile 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. @@ -83,16 +140,24 @@ Fleet provides these variables for Smallstep certificate enrollment: | Variable | Description | |----------|-------------| -| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_{CA_NAME}` | The dynamic SCEP challenge string | -| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_{CA_NAME}` | The SCEP proxy URL for certificate requests | +| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_SMALLSTEP_AGENT` | The dynamic SCEP challenge string | +| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_SMALLSTEP_AGENT` | The SCEP proxy URL for certificate requests | | `$FLEET_VAR_SCEP_RENEWAL_ID` | A unique renewal identifier for the device | | `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` | The end user's email from the identity provider | -Replace `{CA_NAME}` with the name you configured in Step 2 (e.g., `WIFI_CERTIFICATE`). +If you used a different name when adding the CA in Fleet, replace `SMALLSTEP_AGENT` accordingly. + #### Example macOS/iOS SCEP profile -Create a `.mobileconfig` file with the following structure. This example is for Wi-Fi authentication: +Create a `.mobileconfig` file with the following structure. + +This profile contains two payloads: + +1. **SCEP payload**: Issues a provisional SCEP certificate that the Smallstep agent uses for bootstrapping into a Device Attested environment +2. **Root CA trust payload**: Installs the Smallstep Agent Root CA so the agent can validate its certificate chain. + To create this payload, open the downloaded `.pem` file in a text editor and copy the Base64-encoded certificate contents (everything between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, not including those lines) + You will paste this value into the `` field of the Root CA trust payload below. ```xml @@ -101,6 +166,7 @@ Create a `.mobileconfig` file with the following structure. This example is for PayloadContent + PayloadDisplayName Smallstep SCEP @@ -115,7 +181,7 @@ Create a `.mobileconfig` file with the following structure. This example is for PayloadContent Challenge - $FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_WIFI_CERTIFICATE + $FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_SMALLSTEP_AGENT Key Type RSA Key Usage @@ -127,7 +193,7 @@ Create a `.mobileconfig` file with the following structure. This example is for CN - $FLEET_VAR_HOST_END_USER_EMAIL_IDP + step-agent-bootstrap @@ -138,9 +204,58 @@ Create a `.mobileconfig` file with the following structure. This example is for URL - $FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_WIFI_CERTIFICATE + $FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_SMALLSTEP_AGENT + + + PayloadDisplayName + Smallstep Agent Root CA + PayloadIdentifier + com.smallstep.root-ca + PayloadType + com.apple.security.pem + PayloadUUID + B2C3D4E5-F6A7-8901-BCDE-F12345678901 + PayloadVersion + 1 + PayloadContent + + + + + + + PayloadContent + + + PayloadType + com.smallstep.Agent + PayloadVersion + 1 + PayloadIdentifier + com.smallstep.Agent.settings + PayloadUUID + A1B2C3D4-E5F6-7890-ABCD-EF1234567890 + PayloadDisplayName + Smallstep Agent Settings + TeamSlug + + Certificate + mackms:label=step-agent-bootstrap;se=false;tag= + + + PayloadDisplayName + Smallstep Agent + PayloadIdentifier + com.smallstep.Agent + PayloadType + Configuration + PayloadUUID + 12345678-1234-1234-1234-123456789ABC + PayloadVersion + 1 + PayloadDisplayName Smallstep Certificate @@ -149,31 +264,166 @@ Create a `.mobileconfig` file with the following structure. This example is for PayloadType Configuration PayloadUUID - 12345678-90AB-CDEF-1234-567890ABCDEF + 1234EXAMPLE-CDEF-1234-567890ABCDEF PayloadVersion 1 ``` - -
-Replace `WIFI_CERTIFICATE` in the variable names with the CA name you configured in Fleet. -
- +- If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. +- Replace the `PayloadUUID` values with unique identifiers. You can generate them with `uuidgen`. +- Replace the `` value with your Smallstep team slug + +#### Example Windows SCEP profile + +For Windows devices, create an XML profile using the SyncML format. +This profile mirrors the macOS profile above, enrolling a SCEP certificate +and trusting the Smallstep Agent Root CA. + +To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities), click **View details** on the **Agents** authority, and copy the **Root Fingerprint** (SHA-256). + +```xml + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID + + + node + + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/KeyUsage + + + int + + 160 + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/KeyLength + + + int + + 2048 + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/HashAlgorithm + + + chr + + SHA-1 + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/SubjectName + + + chr + + CN=step-agent-bootstrap,OU=$FLEET_VAR_SCEP_RENEWAL_ID + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/EKUMapping + + + chr + + 1.3.6.1.5.5.7.3.2 + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/ServerURL + + + chr + + $FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_SMALLSTEP_AGENT + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/Challenge + + + chr + + $FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_SMALLSTEP_AGENT + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/CAThumbprint + + + chr + + YOUR_ROOT_CA_SHA256_FINGERPRINT + + + + + + ./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/Enroll + + + +``` -### 4. Deploy the configuration profile +- Replace `YOUR_ROOT_CA_SHA256_FINGERPRINT` with the Root Fingerprint from the Smallstep Agents authority. +- If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. + +To also install the Smallstep Agent Root CA on Windows, create a second profile using the `RootCATrustedCertificates` CSP: + +```xml + + + + ./Device/Vendor/MSFT/RootCATrustedCertificates/Root/YOUR_ROOT_CA_SHA256_FINGERPRINT/EncodedCertificate + + + b64 + + + + + + +``` + +### 5. Deploy the configuration profiles 1. In Fleet, go to **Controls → OS settings → Custom settings** 2. Click **Add profile** -3. Upload your `.mobileconfig` file +3. Upload your `.mobileconfig` file (for macOS/iOS) or `.xml` file (for Windows) 4. Assign the profile to your desired scope (teams or all devices) -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. +The profiles will be deployed to devices at their next check-in. Fleet will automatically substitute the variables with the appropriate values for each device. -## Deploy the Smallstep agent (optional) +## 6. Deploy the Smallstep agent -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. +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. You can deploy the agent using Fleet's software management features: @@ -186,7 +436,7 @@ You can deploy the agent using Fleet's software management features: 3. Use Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) to install the agent on your devices 4. Configure the agent using Fleet's [scripting features](https://fleetdm.com/guides/scripts) or a separate configuration profile -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. +Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See the [Smallstep Agent manual installation guide](../platform/smallstep-agent.mdx#macos-installation) for detailed instructions. ## Confirmation @@ -202,76 +452,4 @@ On the device itself: - **iOS/iPadOS**: Go to **Settings → General → VPN & Device Management** to view installed profiles - **Windows**: Open **certmgr.msc** and check the Personal certificates store -## Device sync - -To sync your device inventory from Fleet to Smallstep, you'll create an API user in Fleet and configure the connection in Smallstep. - -### 1. Create an API-only user in Fleet - -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. - -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. - -1. Configure fleetctl with your Fleet server address: - - ```bash - fleetctl config set --address 'https://fleet.example.com' - ``` - -2. Log in with your admin credentials: - - ```bash - fleetctl login - ``` - -3. Create the API-only user: - - ```bash - fleetctl user create --name 'Smallstep' \ - --email 'smallstep-api@example.com' \ - --password 'your-secure-password' \ - --api-only - ``` - -4. The command will output an API token: - - ``` - Success! The API token for your new user is: - ``` - - Copy this token—you'll need it for the next step. - - -
-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. -
- - -### 2. Connect Fleet to Smallstep - -Now you'll add your Fleet API credentials to Smallstep. - -1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) -2. Under Available Providers, find **Fleet** and click **Connect** -3. Fill in the fields: - - **API Base URL**: Your Fleet server URL (e.g., `https://fleet.example.com`) - - **API Token**: Paste the API token from the previous step - - **Name/Alias**: An optional identifier for this connection (e.g., `Production Fleet`) -4. Click **Connect MDM** - -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. - -### Alternative: Get an API token from the Fleet UI - -If you prefer not to create a dedicated API-only user, you can generate an API token for an existing user: - -1. In Fleet, click your profile icon in the top right and select **My account** -2. Click **Get API token** -3. Copy the token and use it in Smallstep's Fleet connection settings - - -
-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. -
- From dcd0af05cb0b4730ed34400c2e1864820bad13c7 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 5 Feb 2026 15:14:29 -0800 Subject: [PATCH 3/4] Small fleet updates --- tutorials/connect-fleet-dm-to-smallstep.mdx | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index c93b07f7..6cfb050c 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -125,7 +125,7 @@ Now we'll add the Smallstep SCEP credentials to Fleet. 5. Fill in the fields: - **Name**: A unique identifier using letters, numbers, and underscores only (for example, `SMALLSTEP_AGENT`). Fleet will create configuration profile variables with this name as a suffix. - **SCEP URL**: Paste the SCEP URL from Smallstep - - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep (Fleet calls this "Challenge URL") + - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep - **Username**: Paste the Challenge Username from Smallstep - **Password**: Paste the Challenge Password from Smallstep 6. Click **Add CA** @@ -147,17 +147,17 @@ Fleet provides these variables for Smallstep certificate enrollment: If you used a different name when adding the CA in Fleet, replace `SMALLSTEP_AGENT` accordingly. - #### Example macOS/iOS SCEP profile Create a `.mobileconfig` file with the following structure. -This profile contains two payloads: +This profile contains three payloads: 1. **SCEP payload**: Issues a provisional SCEP certificate that the Smallstep agent uses for bootstrapping into a Device Attested environment 2. **Root CA trust payload**: Installs the Smallstep Agent Root CA so the agent can validate its certificate chain. To create this payload, open the downloaded `.pem` file in a text editor and copy the Base64-encoded certificate contents (everything between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, not including those lines) - You will paste this value into the `` field of the Root CA trust payload below. + You will paste this value inside the `` field of the Root CA trust payload below. +3. **Agent Configuration**: A configuration payload for the Smallstep Agent that includes your Smallstep team slug. ```xml @@ -423,18 +423,14 @@ The profiles will be deployed to devices at their next check-in. Fleet will auto ## 6. Deploy the Smallstep agent -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. - -You can deploy the agent using Fleet's software management features: +The last step is to deploy 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 deployment](hrtps://fleetdm.com/guides/deploy-software-packages) feature: 1. Download the agent package: - macOS: [step-agent-plugin_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) - Windows (x64): [step-agent-plugin_latest_amd64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi) - Windows (ARM64): [step-agent-plugin_latest_arm64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_arm64.msi) - -2. In Fleet, go to **Software** and add the package for distribution -3. Use Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) to install the agent on your devices -4. Configure the agent using Fleet's [scripting features](https://fleetdm.com/guides/scripts) or a separate configuration profile +2. In Fleet, go to **Software**, choose **Custom Package**, and add the package for distribution Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See the [Smallstep Agent manual installation guide](../platform/smallstep-agent.mdx#macos-installation) for detailed instructions. From e73a946aa30e22cf4ff003a60c60a3e79ecf2cf5 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 5 Feb 2026 15:37:08 -0800 Subject: [PATCH 4/4] Draft of gitops instructions --- tutorials/connect-fleet-dm-to-smallstep.mdx | 163 +++++++++++++++----- 1 file changed, 127 insertions(+), 36 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 6cfb050c..171a3df3 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -35,15 +35,21 @@ Supported platforms: - macOS, iOS, iPadOS (via `.mobileconfig` profiles) - Windows (via `.xml` SyncML profiles) -## Device sync +## Step 1. Get a Fleet API token -To sync your device inventory from Fleet to Smallstep, you'll create an API user in Fleet and configure the connection in Smallstep. +Smallstep needs a Fleet API token to sync your device inventory. You can use a personal API token for testing, or create a dedicated API-only user for production use. -### 1. Create an API-only user in Fleet +### Option A: Use a personal API token -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. +1. In Fleet, click your profile icon in the top right and select **My account** +2. Click **Get API token** +3. Copy the token — you'll need it for the next step + +### Option B: Create an API-only user (recommended for production) + +For production use, we recommend creating a dedicated API-only user for the Smallstep integration rather than using a personal account token. An API-only user cannot log into the Fleet UI and is intended for automated integrations. -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. +You'll need the [fleetctl CLI](https://fleetdm.com/guides/fleetctl#installing-fleetctl) tool installed and authenticated with admin privileges. 1. Configure fleetctl with your Fleet server address: @@ -72,7 +78,7 @@ You'll need the [fleetctl CLI](https://fleetdm.com/guides/fleetctl#installing-fl Success! The API token for your new user is: ``` - Copy this token—you'll need it for the next step. + Copy this token — you'll need it for the next step.
@@ -80,21 +86,7 @@ The default role for API-only users is **Observer**, which grants read-only acce
-### Alternative: Get an API token from the Fleet UI - -If you prefer not to create a dedicated API-only user, you can generate an API token for an existing user: - -1. In Fleet, click your profile icon in the top right and select **My account** -2. Click **Get API token** -3. Copy the token and use it in Smallstep's Fleet connection settings - - -
-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. -
- - -### 2. Connect Fleet to Smallstep +## Step 2. Connect Fleet to Smallstep Now you'll add your Fleet API credentials to Smallstep. @@ -114,7 +106,7 @@ Now you'll add your Fleet API credentials to Smallstep. 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. -### 3. Add the Smallstep Certificate Authority in Fleet +## Step 3. Add the Smallstep Certificate Authority in Fleet Now we'll add the Smallstep SCEP credentials to Fleet. @@ -132,9 +124,15 @@ Now we'll add the Smallstep SCEP credentials to Fleet. Fleet will test the CA connection after you create it. -### 4. Create a SCEP configuration profile + +
+If you plan to use GitOps instead of the Fleet UI, skip this step and see the [GitOps section below](#gitops-configure-fleet-with-fleetctl) for the YAML-based alternative. +
+ -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. +## Step 4. Create SCEP configuration profiles + +Fleet deploys certificates to devices using configuration profiles. You'll need to create profiles that include the SCEP payload with Fleet's dynamic variables. Fleet provides these variables for Smallstep certificate enrollment: @@ -147,9 +145,9 @@ Fleet provides these variables for Smallstep certificate enrollment: If you used a different name when adding the CA in Fleet, replace `SMALLSTEP_AGENT` accordingly. -#### Example macOS/iOS SCEP profile +### macOS/iOS SCEP profile (`smallstep-agent.mobileconfig`) -Create a `.mobileconfig` file with the following structure. +Create a file called `smallstep-agent.mobileconfig` with the following structure. This profile contains three payloads: @@ -275,9 +273,9 @@ This profile contains three payloads: - Replace the `PayloadUUID` values with unique identifiers. You can generate them with `uuidgen`. - Replace the `` value with your Smallstep team slug -#### Example Windows SCEP profile +### Windows SCEP profile (`smallstep-scep.xml`) -For Windows devices, create an XML profile using the SyncML format. +For Windows devices, create a file called `smallstep-scep.xml` using the SyncML format. This profile mirrors the macOS profile above, enrolling a SCEP certificate and trusting the Smallstep Agent Root CA. @@ -394,7 +392,9 @@ To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](ht - Replace `YOUR_ROOT_CA_SHA256_FINGERPRINT` with the Root Fingerprint from the Smallstep Agents authority. - If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. -To also install the Smallstep Agent Root CA on Windows, create a second profile using the `RootCATrustedCertificates` CSP: +### Windows Root CA profile (`smallstep-root-ca.xml`) + +To install the Smallstep Agent Root CA on Windows, create a second file called `smallstep-root-ca.xml` using the `RootCATrustedCertificates` CSP: ```xml @@ -412,20 +412,22 @@ To also install the Smallstep Agent Root CA on Windows, create a second profile ``` -### 5. Deploy the configuration profiles +## Step 5. Deploy the configuration profiles and Smallstep agent + +### Upload profiles 1. In Fleet, go to **Controls → OS settings → Custom settings** 2. Click **Add profile** -3. Upload your `.mobileconfig` file (for macOS/iOS) or `.xml` file (for Windows) +3. Upload your `smallstep-agent.mobileconfig` file (for macOS/iOS) or your `.xml` files (for Windows) 4. Assign the profile to your desired scope (teams or all devices) The profiles will be deployed to devices at their next check-in. Fleet will automatically substitute the variables with the appropriate values for each device. -## 6. Deploy the Smallstep agent +### Deploy the agent -The last step is to deploy the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent makes it easier to configure endpoints and manage certificates. +The last step is to deploy the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent manages certificates and makes it easy to configure endpoints. -You can deploy the agent using Fleet's [software deployment](hrtps://fleetdm.com/guides/deploy-software-packages) feature: +You can deploy the agent using Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) feature: 1. Download the agent package: - macOS: [step-agent-plugin_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) - Windows (x64): [step-agent-plugin_latest_amd64.msi](https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi) @@ -434,6 +436,97 @@ You can deploy the agent using Fleet's [software deployment](hrtps://fleetdm.com Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See the [Smallstep Agent manual installation guide](../platform/smallstep-agent.mdx#macos-installation) for detailed instructions. +## GitOps: Configure Fleet with `fleetctl` + +As an alternative to Steps 3 through 5, you can manage your entire Fleet configuration with YAML files and the `fleetctl gitops` command. This approach is ideal for version-controlled, repeatable deployments. + +### Directory layout + +A typical GitOps repository for Fleet looks like this: + +``` +fleet-gitops/ +├── default.yml +├── teams/ +│ └── team.yml +└── lib/ + ├── smallstep-agent.mobileconfig + ├── smallstep-scep.xml + └── smallstep-root-ca.xml +``` + +- `default.yml` — Organization-wide settings, including certificate authorities +- `teams/team.yml` — Per-team configuration for profiles and software +- `lib/` — Configuration profile files created in [Step 4](#step-4-create-scep-configuration-profiles) + +### Add the Smallstep CA + +In `default.yml`, add the Smallstep certificate authority under `org_settings`: + +```yaml +org_settings: + certificate_authorities: + smallstep: + - name: SMALLSTEP_AGENT + url: + challenge_url: + username: $SMALLSTEP_CHALLENGE_USERNAME + password: $SMALLSTEP_CHALLENGE_PASSWORD +``` + +The `$SMALLSTEP_CHALLENGE_USERNAME` and `$SMALLSTEP_CHALLENGE_PASSWORD` values are environment variables. Set them before running `fleetctl gitops`: + +```bash +export SMALLSTEP_CHALLENGE_USERNAME='your-challenge-username' +export SMALLSTEP_CHALLENGE_PASSWORD='your-challenge-password' +``` + +### Add configuration profiles + +In your team YAML file, reference the profile files from [Step 4](#step-4-create-scep-configuration-profiles): + +```yaml +controls: + macos_settings: + custom_settings: + - path: ../lib/smallstep-agent.mobileconfig + windows_settings: + custom_settings: + - path: ../lib/smallstep-scep.xml + - path: ../lib/smallstep-root-ca.xml +``` + +### Add the Smallstep agent software + +In the same team YAML file, add the Smallstep agent packages: + +```yaml +software: + packages: + - url: https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg + - url: https://packages.smallstep.com/stable/windows/step-agent-plugin_latest_amd64.msi +``` + +### Apply the configuration + +Run `fleetctl gitops` to apply the configuration: + +```bash +fleetctl gitops -f default.yml -f teams/team.yml +``` + +Use `--dry-run` to validate your configuration before applying: + +```bash +fleetctl gitops -f default.yml -f teams/team.yml --dry-run +``` + + +
+The `--dry-run` flag is useful for CI pipelines. You can run it on pull requests to validate configuration changes before merging. +
+ + ## Confirmation To confirm certificate deployment: @@ -447,5 +540,3 @@ On the device itself: - **macOS**: Open **Keychain Access** and look for a certificate issued by your Smallstep authority - **iOS/iPadOS**: Go to **Settings → General → VPN & Device Management** to view installed profiles - **Windows**: Open **certmgr.msc** and check the Personal certificates store - -