From a55390eaf7fa148d3cc381e0e471b28db3568495 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 8 Sep 2026 09:04:41 -0700 Subject: [PATCH 1/3] docs: don't register Fleet-synced hosts; clarify when to use the API path Hosts that Fleet syncs to Smallstep with the osquery extension already exist in inventory. Running `step-agent register` on them creates a conflicting device entry and fails with `unprocessable entity`. Say so in the Fleet tutorial (Linux and Windows), add the symptom to the troubleshooting guide, and reframe self-registration and API pre-registration in the agent guide and enrollment guide as the paths for devices Smallstep can't sync from an MDM. Also replace the Linux approval pointer in the Fleet tutorial: devices synced from Fleet need admin approval by default, and auto-approval is set through the Device Enrollment Policy API, not by adding the device via API. Fixes EFF-334. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK --- .../config/vocabularies/Smallstep/accept.txt | 2 ++ platform/enrollment-guide.mdx | 9 ++++++++- platform/smallstep-agent.mdx | 8 +++++--- platform/troubleshooting-agent.mdx | 11 ++++++++++- tutorials/connect-fleet-dm-to-smallstep.mdx | 18 +++++++++++++++--- 5 files changed, 40 insertions(+), 8 deletions(-) diff --git a/.vale/styles/config/vocabularies/Smallstep/accept.txt b/.vale/styles/config/vocabularies/Smallstep/accept.txt index 77f561c7..60db4531 100644 --- a/.vale/styles/config/vocabularies/Smallstep/accept.txt +++ b/.vale/styles/config/vocabularies/Smallstep/accept.txt @@ -952,3 +952,5 @@ publicKey serialNumber testuser disallow +osquery +fleetctl diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index a671f932..2ba959f4 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -1,5 +1,5 @@ --- -updated_at: February 03, 2026 +updated_at: September 8, 2026 title: Device Enrollment Guide html_title: Device Enrollment Implementation Guide description: Step-by-step guide for device enrollment and inventory management. Set up secure certificate enrollment for all enterprise devices. @@ -72,6 +72,13 @@ see [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.m ### Add devices via API You can import devices from any source into Smallstep using our API. +Use this when your devices are inventoried in a system that Smallstep can't sync from. +If Smallstep already syncs your inventory from an MDM, +don't add the same devices via the API as well: +the result is a duplicate entry that blocks agent enrollment. +For Fleet-managed Linux and Windows hosts, +deploy the [Smallstep osquery extension](../tutorials/connect-fleet-dm-to-smallstep.mdx#linux) +so that Fleet reports each device's TPM Endorsement Key to Smallstep. Devices added via API are automatically approved. but they will not be marked as high-assurance diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 65a90bd0..eb2cf46a 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: July 27, 2026 +updated_at: September 8, 2026 title: Install the Smallstep Agent html_title: Install the Smallstep Agent on macOS, Windows, and Linux description: Install, configure, and deploy the Smallstep Agent on macOS, Windows, and Linux endpoints. Includes manual install, MDM integration, system requirements, and network endpoints. @@ -22,6 +22,7 @@ Using an MDM? See: - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS) - [Connect Intune to Smallstep](../tutorials/connect-intune-to-smallstep.mdx) (Windows) - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows) +- [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx) (macOS, Linux, Windows) Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx). @@ -359,7 +360,7 @@ so a host with no /dev/tpmrm0 cannot enroll yet. ### Self-registration -Users can configure the agent and register their Linux device with your Smallstep team by running: +For a device that is not yet in your Smallstep inventory, users can configure the agent and register their Linux device with your Smallstep team by running: ```bash sudo step-agent register [team name] @@ -370,7 +371,7 @@ Devices must be approved by an admin before they can be used. ### Pre-registration via API -Alternatively, you can pre-register all of your team's devices: +If your devices are inventoried in a system that Smallstep can't sync from, you can pre-register them via the API instead of having each device self-register: 1. [Register and approve your devices via API](./enrollment-guide.mdx#add-devices-via-api). The devices you add via API will be pre-approved. @@ -387,6 +388,7 @@ Alternatively, you can pre-register all of your team's devices: - Select the Smallstep Agents authority - Use the sha256 Root fingerprint displayed on this page +If Smallstep already syncs your inventory from an MDM that reports each device's TPM Endorsement Key, such as Fleet with the Smallstep osquery extension, skip step 1. The devices are already in your inventory, and adding them again via the API or with `step-agent register` creates a conflicting entry. Write `agent.yaml` as in step 2 and start the agent. It attests with its TPM and is matched to the synced entry. See [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx#linux) for the full Fleet flow. ## Start the agent diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index da9f6202..89512859 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: July 27, 2026 +updated_at: September 8, 2026 title: Troubleshooting Guide html_title: Smallstep Troubleshooting Guide description: Troubleshoot Smallstep Device Identity issues. Diagnose platform, MDM, and endpoint problems with step-by-step guidance. @@ -97,6 +97,15 @@ The agent may not be installed or may not be running on the device. - Try rebooting the device. 4. If the agent still hasn't logged in, contact Smallstep support. +**Symptom:** "`step-agent register` fails with `unprocessable entity`, or the browser prompts me to register a device that is already in my inventory" + +The device already exists in your Smallstep inventory. This happens when the device was synced from an MDM that reports its TPM Endorsement Key (for example, Fleet with the Smallstep osquery extension) or was added via the API. `step-agent register` tries to create a second device entry, which conflicts with the existing one. + +**Troubleshooting steps:** +1. Don't run `step-agent register` on the device. Write the agent configuration file directly and start the agent service. It attests with its TPM and is matched to the existing entry. See [Linux agent configuration](../tutorials/connect-fleet-dm-to-smallstep.mdx#step-5-linux-agent-configuration) in the Fleet tutorial, or [Pre-registration via API](./smallstep-agent.mdx#pre-registration-via-api) in the agent guide. +2. If a duplicate device was created, delete it in the [Smallstep console](https://smallstep.com/app/?next=/devices) and keep the entry that came from the MDM sync or the API. +3. If the device shows as pending after the agent starts, approve it in the console. + **Symptom:** "The device is approved, but it's not converting to a Smallstep-managed device (no green dot)" **Troubleshooting steps:** diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 7a080d0f..28b79f10 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: May 21, 2026 +updated_at: September 8, 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. @@ -427,7 +427,13 @@ systemctl enable --now step-agent ``` -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). +When the agent starts, it attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. No registration step runs on the host. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2025-01-01/operations/put-device-enrollment-policy). + + +
+Do not run `step-agent register` or `step-agent start --login` on a host that Fleet has already synced to Smallstep, and do not add the host through the Smallstep API. The host is already in your inventory, and registering it again fails with `unprocessable entity` or prompts you to register a duplicate device. The agent configuration above is all the host needs. +
+ ## Step 6. Confirmation (Linux) @@ -559,7 +565,13 @@ Add the Smallstep agent MSI as Fleet software so it installs on enrollment: 2. In the Fleet console, go to **Software**, choose **Add software → Custom package**, and upload the MSI 3. Scope the install to your Windows hosts -The agent reads the registry values written in Step 3 on startup, and completes TPM-attested registration with your Smallstep team. +The agent reads the registry values written in Step 3 on startup, attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2025-01-01/operations/put-device-enrollment-policy). + + +
+Do not run `step-agent register` or `step-agent start --login` on a host that Fleet has already synced to Smallstep, and do not add the host through the Smallstep API. The host is already in your inventory, and registering it again fails with `unprocessable entity` or prompts you to register a duplicate device. The agent configuration above is all the host needs. +
+ ## Step 6. Confirmation (Windows) From c2f0c9558e37da4e89dc28d65807d3d49afe078f Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 8 Sep 2026 09:39:46 -0700 Subject: [PATCH 2/3] docs: point Fleet auto-approval links at the live API docs slug The API docs site keys operations by PascalCase operationId (PutDeviceEnrollmentPolicy) and the 2026-05-01 version is current. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK --- tutorials/connect-fleet-dm-to-smallstep.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 28b79f10..a7402873 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -427,7 +427,7 @@ systemctl enable --now step-agent ``` -When the agent starts, it attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. No registration step runs on the host. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2025-01-01/operations/put-device-enrollment-policy). +When the agent starts, it attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. No registration step runs on the host. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy).
@@ -565,7 +565,7 @@ Add the Smallstep agent MSI as Fleet software so it installs on enrollment: 2. In the Fleet console, go to **Software**, choose **Add software → Custom package**, and upload the MSI 3. Scope the install to your Windows hosts -The agent reads the registry values written in Step 3 on startup, attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2025-01-01/operations/put-device-enrollment-policy). +The agent reads the registry values written in Step 3 on startup, attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy).
From 24fda4abe59c0f2a1919d9147685bf17d3eb138c Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 8 Sep 2026 10:11:03 -0700 Subject: [PATCH 3/3] docs: osquery-based enrollment for Fleet, 2026-05-01 API, auto-approval curl - Enrollment guide: add an osquery-based enrollment section for Fleet, and move the device API examples to the 2026-05-01 API version. - Fleet tutorial: describe Linux enrollment as ACME Device Attestation with the TPM, and show the curl flow for adding Fleet to autoApproveSources via the Device Enrollment Policy API, since the console doesn't expose it. - Agent guide and troubleshooting: tighten the wording around pre-registration and the duplicate-registration symptom. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK --- platform/enrollment-guide.mdx | 21 ++++--- platform/smallstep-agent.mdx | 6 +- platform/troubleshooting-agent.mdx | 4 +- tutorials/connect-fleet-dm-to-smallstep.mdx | 70 +++++++++++++++++---- 4 files changed, 72 insertions(+), 29 deletions(-) diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 2ba959f4..9b4e27d0 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -31,7 +31,7 @@ into your Smallstep inventory: You can [manually invite users to join your Smallstep team](https://smallstep.com/app/?next=/users/invite), and they will be able to self-enroll devices -using the [Smallstep Agent](./smallstep-agent.mdx). +using the [Smallstep Agent](./smallstep-agent.mdx)'s `step-agent register` subcommand. By default, administrators must approve a new device @@ -69,16 +69,17 @@ until Smallstep receives an attestation from the device. For a concrete example, see [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) +### Use osquery-based enrollment + +For [Fleet-managed](../tutorials/connect-fleet-dm-to-smallstep.mdx) Linux and Windows hosts, deploy the Smallstep osquery extension. +The osquery extension will report each device's TPM Endorsement Key to Fleet. +Smallstep then syncs the data into your inventory. + ### Add devices via API You can import devices from any source into Smallstep using our API. + Use this when your devices are inventoried in a system that Smallstep can't sync from. -If Smallstep already syncs your inventory from an MDM, -don't add the same devices via the API as well: -the result is a duplicate entry that blocks agent enrollment. -For Fleet-managed Linux and Windows hosts, -deploy the [Smallstep osquery extension](../tutorials/connect-fleet-dm-to-smallstep.mdx#linux) -so that Fleet reports each device's TPM Endorsement Key to Smallstep. Devices added via API are automatically approved. but they will not be marked as high-assurance @@ -86,7 +87,7 @@ until Smallstep receives an attestation from the device. You'll need [an API token](https://smallstep.com/app/?next=/settings/api/tokens/add) with all “device” scopes (put-device, patch-device, etc.). -Use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device. +Use the [Add Device](https://gateway.smallstep.com/v2026-05-01/operations/PostDevices) endpoint to create a device. - For Apple devices, the `permanentIdentifier` must be the device's 9-character serial number. - For TPM 2.0 devices, the `permanentIdentifier` must be the TPM Endorsement Key URI, in the format `urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=`. (You can retrieve the EK URI by running `step agent tpm --fingerprint` on the device.) - To create and assign a user to a device, fill in the `user` fields. @@ -94,7 +95,7 @@ Use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDe Once added, the devices will be automatically approved. -You can see the device using the [List Devices](https://gateway.smallstep.com/v2025-01-01/operations/ListDevices) endpoint: +You can see the device using the [List Devices](https://gateway.smallstep.com/v2026-05-01/operations/ListDevices) endpoint: ```bash set +o history @@ -103,7 +104,7 @@ set -o history curl -sH @api_headers --request GET \ --url https://gateway.smallstep.com/api/devices \ --header 'Accept: application/json' \ - --header 'x-smallstep-api-version: 2025-01-01' | jq + --header 'x-smallstep-api-version: 2026-05-01' | jq ``` You'll also see new devices in the Smallstep console, diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index eb2cf46a..4ff112fc 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -22,7 +22,7 @@ Using an MDM? See: - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS) - [Connect Intune to Smallstep](../tutorials/connect-intune-to-smallstep.mdx) (Windows) - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows) -- [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx) (macOS, Linux, Windows) +- [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx) Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx). @@ -356,7 +356,7 @@ so a host with no /dev/tpmrm0 cannot enroll yet. ``` -## Registering and approving endpoints +## Registering and approving NixOS endpoints ### Self-registration @@ -388,8 +388,6 @@ If your devices are inventoried in a system that Smallstep can't sync from, you - Select the Smallstep Agents authority - Use the sha256 Root fingerprint displayed on this page -If Smallstep already syncs your inventory from an MDM that reports each device's TPM Endorsement Key, such as Fleet with the Smallstep osquery extension, skip step 1. The devices are already in your inventory, and adding them again via the API or with `step-agent register` creates a conflicting entry. Write `agent.yaml` as in step 2 and start the agent. It attests with its TPM and is matched to the synced entry. See [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx#linux) for the full Fleet flow. - ## Start the agent Finally, enable and start the agent: diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index 89512859..c65084d9 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -99,10 +99,10 @@ The agent may not be installed or may not be running on the device. **Symptom:** "`step-agent register` fails with `unprocessable entity`, or the browser prompts me to register a device that is already in my inventory" -The device already exists in your Smallstep inventory. This happens when the device was synced from an MDM that reports its TPM Endorsement Key (for example, Fleet with the Smallstep osquery extension) or was added via the API. `step-agent register` tries to create a second device entry, which conflicts with the existing one. +This happens when the device was synced from an MDM that reports its TPM Endorsement Key or was added via the API. `step-agent register` tries to create a second device entry, which conflicts with the existing one. **Troubleshooting steps:** -1. Don't run `step-agent register` on the device. Write the agent configuration file directly and start the agent service. It attests with its TPM and is matched to the existing entry. See [Linux agent configuration](../tutorials/connect-fleet-dm-to-smallstep.mdx#step-5-linux-agent-configuration) in the Fleet tutorial, or [Pre-registration via API](./smallstep-agent.mdx#pre-registration-via-api) in the agent guide. +1. Don't run `step-agent register` on the device. Write the agent configuration file directly and start the agent service. See [Pre-registration via API](./smallstep-agent.mdx#pre-registration-via-api). 2. If a duplicate device was created, delete it in the [Smallstep console](https://smallstep.com/app/?next=/devices) and keep the entry that came from the MDM sync or the API. 3. If the device shows as pending after the agent starts, approve it in the console. diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index a7402873..be782d64 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -404,10 +404,13 @@ Once the enrollment report is configured in Fleet, the Smallstep platform needs 2. In the Smallstep console, edit your Fleet configuration 3. Set the **Enrollment Query ID** to the numeric ID +Your fleet's TPM information will begin syncing to Smallstep. ## Step 5. 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 and the osquery extension, you must configure the agent with your Smallstep team slug and CA fingerprint. +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 uses ACME Device Attestation with the system's TPM. + +After installing the agent package and the osquery extension, you must configure the agent 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: @@ -426,14 +429,34 @@ systemctl daemon-reload systemctl enable --now step-agent ``` +When the agent starts, it attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data you just synced. By default, devices synced from Fleet need admin approval: if the host shows as `pending` in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. -When the agent starts, it attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. No registration step runs on the host. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy). +To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`: - -
-Do not run `step-agent register` or `step-agent start --login` on a host that Fleet has already synced to Smallstep, and do not add the host through the Smallstep API. The host is already in your inventory, and registering it again fails with `unprocessable entity` or prompts you to register a duplicate device. The agent configuration above is all the host needs. -
- +```bash +set +o history +echo "Authorization: Bearer [your API token]" > api_headers +set -o history + +# Fetch the current policy +curl -sH @api_headers --request GET \ + --url https://gateway.smallstep.com/api/device-enrollment-policy \ + --header 'Accept: application/json' \ + --header 'x-smallstep-api-version: 2026-05-01' | jq + +# Resubmit it with Fleet in autoApproveSources. +# Adjust both lists to match the policy you fetched. +curl -sH @api_headers --request PUT \ + --url https://gateway.smallstep.com/api/device-enrollment-policy \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'x-smallstep-api-version: 2026-05-01' \ + --data '{ + "allowedSources": ["Smallstep API", "Smallstep Agent", "Fleet"], + "autoApproveSources": ["Fleet"], + "requireUserBinding": true + }' | jq +``` ## Step 6. Confirmation (Linux) @@ -565,13 +588,34 @@ Add the Smallstep agent MSI as Fleet software so it installs on enrollment: 2. In the Fleet console, go to **Software**, choose **Add software → Custom package**, and upload the MSI 3. Scope the install to your Windows hosts -The agent reads the registry values written in Step 3 on startup, attests with the host's TPM, and Smallstep matches the attestation to the inventory entry that Fleet synced along with the TPM Endorsement Key. By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` using the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy). +On startup, the agent reads the registry values to find the team information, then attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data synced from Fleet. - -
-Do not run `step-agent register` or `step-agent start --login` on a host that Fleet has already synced to Smallstep, and do not add the host through the Smallstep API. The host is already in your inventory, and registering it again fails with `unprocessable entity` or prompts you to register a duplicate device. The agent configuration above is all the host needs. -
- +By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`: + +```bash +set +o history +echo "Authorization: Bearer [your API token]" > api_headers +set -o history + +# Fetch the current policy +curl -sH @api_headers --request GET \ + --url https://gateway.smallstep.com/api/device-enrollment-policy \ + --header 'Accept: application/json' \ + --header 'x-smallstep-api-version: 2026-05-01' | jq + +# Resubmit it with Fleet in autoApproveSources. +# Adjust both lists to match the policy you fetched. +curl -sH @api_headers --request PUT \ + --url https://gateway.smallstep.com/api/device-enrollment-policy \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --header 'x-smallstep-api-version: 2026-05-01' \ + --data '{ + "allowedSources": ["Smallstep API", "Smallstep Agent", "Fleet"], + "autoApproveSources": ["Fleet"], + "requireUserBinding": true + }' | jq +``` ## Step 6. Confirmation (Windows)