From 4aa586f852671609cdfa5c2698a583bf000f50c1 Mon Sep 17 00:00:00 2001 From: Josh Drake Date: Mon, 26 Jan 2026 09:58:42 -0600 Subject: [PATCH 1/5] 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/5] 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/5] 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/5] 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 - - From 9dba1168b03c141f6e996931a6b5630eff7a8da3 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 24 Feb 2026 09:39:28 -0800 Subject: [PATCH 5/5] Add Linux agent package distribution to Fleet DM integration docs Linux hosts don't support MDM profiles, so instead of SCEP enrollment the agent registers directly via TPM attestation. Adds .deb and .rpm package links, a post-install script for agent configuration, GitOps YAML examples with label-based targeting, and Linux confirmation steps. Co-Authored-By: Claude Opus 4.6 --- tutorials/connect-fleet-dm-to-smallstep.mdx | 75 ++++++++++++++++++++- 1 file changed, 73 insertions(+), 2 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 171a3df3..56c343c2 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -34,6 +34,7 @@ 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 @@ -432,10 +433,45 @@ You can deploy the agent using Fleet's [software deployment](https://fleetdm.com - 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/docs/using-fleet/hosts#labels) 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. @@ -452,12 +488,13 @@ fleet-gitops/ └── lib/ ├── smallstep-agent.mobileconfig ├── smallstep-scep.xml - └── smallstep-root-ca.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) +- `lib/` — Configuration profile files created in [Step 4](#step-4-create-scep-configuration-profiles) and Linux agent setup script ### Add the Smallstep CA @@ -505,8 +542,41 @@ 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/docs/using-fleet/hosts#custom-labels) 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: @@ -540,3 +610,4 @@ 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