diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index de01c370..17ea575f 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -1,31 +1,613 @@ --- -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) +- Linux (via agent software deployment) + +## 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) + - Linux (Debian/Ubuntu x64): [step-agent-plugin_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent-plugin_amd64_latest.deb) + - Linux (Debian/Ubuntu ARM64): [step-agent-plugin_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent-plugin_arm64_latest.deb) + - Linux (RHEL/Fedora x64): [step-agent-plugin_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent-plugin_x86_64_latest.rpm) + - Linux (RHEL/Fedora ARM64): [step-agent-plugin_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent-plugin_aarch64_latest.rpm) +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. + +### Linux agent configuration + +Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux registers directly using TPM attestation. After installing the agent package, you must configure it with your Smallstep team slug and CA fingerprint. + +When adding a Linux agent package in Fleet, add the following **post-install script** to configure and start the agent: + +```bash +#!/bin/bash + +# Configure the Smallstep agent +mkdir -p /etc/step-agent +cat > /etc/step-agent/agent.yaml << EOF +team: "" +fingerprint: "" +EOF + +# Enable and start the agent service +systemctl daemon-reload +systemctl enable --now step-agent +``` + +Replace `` with your Smallstep team slug (found in [**Settings → Team**](https://smallstep.com/app/?next=/settings/team)), and `` with the SHA-256 root fingerprint of your Smallstep Agents authority (found in [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities) under the Agents authority). + + +
+If your fleet includes multiple Linux distributions or architectures, create separate software entries for each package variant. Use [Fleet labels](https://fleetdm.com/guides/managing-labels-in-fleet) to target `.deb` packages to Debian/Ubuntu hosts and `.rpm` packages to RHEL/Fedora hosts. See the [GitOps section](#gitops-configure-fleet-with-fleetctl) for a complete example with label targeting. +
+ + +After deployment, Linux devices will self-register with your Smallstep team via TPM attestation. By default, new devices require admin approval in the [Smallstep console](https://smallstep.com/app/?next=/devices). To automate approval, you can [pre-register devices via API](../platform/smallstep-agent.mdx#pre-registration-via-api). + +## 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 + └── smallstep-agent-setup.sh +``` + +- `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) and Linux agent setup script + +### 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 + - url: https://packages.smallstep.com/stable/linux/step-agent-plugin_amd64_latest.deb + post_install_script: + path: ../lib/smallstep-agent-setup.sh + - url: https://packages.smallstep.com/stable/linux/step-agent-plugin_x86_64_latest.rpm + post_install_script: + path: ../lib/smallstep-agent-setup.sh +``` + +If your Linux fleet includes multiple architectures, add entries for each variant and use `labels_include_any` to target the correct package to each host: + +```yaml + - url: https://packages.smallstep.com/stable/linux/step-agent-plugin_amd64_latest.deb + post_install_script: + path: ../lib/smallstep-agent-setup.sh + labels_include_any: + - Ubuntu Linux + - url: https://packages.smallstep.com/stable/linux/step-agent-plugin_arm64_latest.deb + post_install_script: + path: ../lib/smallstep-agent-setup.sh + labels_include_any: + - Ubuntu Linux + - url: https://packages.smallstep.com/stable/linux/step-agent-plugin_x86_64_latest.rpm + post_install_script: + path: ../lib/smallstep-agent-setup.sh + labels_include_any: + - Red Hat Linux + - url: https://packages.smallstep.com/stable/linux/step-agent-plugin_aarch64_latest.rpm + post_install_script: + path: ../lib/smallstep-agent-setup.sh + labels_include_any: + - Red Hat Linux +``` + +Adapt the label names to match your Fleet label configuration. Fleet includes built-in labels for common Linux distributions. For architecture-specific targeting, you can create [custom labels](https://fleetdm.com/guides/managing-labels-in-fleet) using osquery queries (for example, `SELECT 1 FROM system_info WHERE cpu_type = 'x86_64'`). + +### 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 +- **Linux**: Run `sudo systemctl status step-agent` to verify the agent is running, and check `/var/lib/step-agent` for certificate files