diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index de01c370..171a3df3 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -1,31 +1,542 @@ --- -updated_at: February 03, 2026 +updated_at: February 05, 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` SyncML profiles) + +## Step 1. Get a Fleet API token + +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. + +### Option A: Use a personal API token + +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. + +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. +
+ + +## Step 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. + +## Step 3. 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 (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 Username from Smallstep + - **Password**: Paste the Challenge Password from Smallstep +6. Click **Add CA** + +Fleet will test the CA connection after you create it. + + +
+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. +
+ + +## 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: + +| Variable | Description | +|----------|-------------| +| `$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 | + +If you used a different name when adding the CA in Fleet, replace `SMALLSTEP_AGENT` accordingly. + +### macOS/iOS SCEP profile (`smallstep-agent.mobileconfig`) + +Create a file called `smallstep-agent.mobileconfig` with the following structure. + +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 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 + + + + + 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_SMALLSTEP_AGENT + Key Type + RSA + Key Usage + 5 + Keysize + 2048 + Subject + + + + CN + step-agent-bootstrap + + + + + OU + $FLEET_VAR_SCEP_RENEWAL_ID + + + + URL + $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 + PayloadIdentifier + com.smallstep.certificate-profile + PayloadType + Configuration + PayloadUUID + 1234EXAMPLE-CDEF-1234-567890ABCDEF + PayloadVersion + 1 + + +``` + +- 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 + +### Windows SCEP profile (`smallstep-scep.xml`) + +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. + +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 + + + +``` + +- 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. + +### 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 + + + + ./Device/Vendor/MSFT/RootCATrustedCertificates/Root/YOUR_ROOT_CA_SHA256_FINGERPRINT/EncodedCertificate + + + b64 + + + + + + +``` + +## 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 `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. + +### Deploy the agent + +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](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) + - 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**, 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. + +## 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: -## Configure device sync (coming soon) +```bash +fleetctl gitops -f default.yml -f teams/team.yml +``` -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. +Use `--dry-run` to validate your configuration before applying: -## Configure dynamic SCEP +```bash +fleetctl gitops -f default.yml -f teams/team.yml --dry-run +``` -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)** + +
+The `--dry-run` flag is useful for CI pipelines. You can run it on pull requests to validate configuration changes before merging. +
+ -## Deploy the Smallstep agent +## Confirmation -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). +To confirm certificate deployment: -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, 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