From 0c73f66d9a5074e40901f3fae2a42d6797fccf95 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 12 Nov 2025 20:37:06 +0100 Subject: [PATCH 01/10] Initial commit --- manifest.json | 2 +- platform/smallstep-agent.mdx | 246 ++++++++++++++++-- tutorials/connect-intune-to-smallstep.mdx | 6 +- tutorials/connect-jamf-pro-to-smallstep.mdx | 50 +--- .../connect-workspace-one-to-smallstep.mdx | 6 +- 5 files changed, 239 insertions(+), 71 deletions(-) diff --git a/manifest.json b/manifest.json index 3f6a7126..3e3f24ca 100644 --- a/manifest.json +++ b/manifest.json @@ -70,7 +70,7 @@ "path": "/platform/smallstep-app.mdx" }, { - "title": "Deploy to Linux", + "title": "Deploy the Agent", "path": "/platform/smallstep-agent.mdx" }, { diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index c89047b8..b1141cab 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,20 +1,32 @@ --- -updated_at: November 06, 2025 -title: Smallstep Agent for Linux -html_title: Smallstep Agent for Device Management Guide -description: Deploy and configure Smallstep Agent on Linux. Automated device identity management and certificate renewal for enterprise Linux fleets. +updated_at: November 12, 2025 +title: Deploy the Agent +html_title: Deploy the Smallstep Agent +description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment. --- -The Smallstep Agent for Linux is a background component of the [Smallstep Desktop App](./smallstep-app.mdx). -Choose one or the other depending on your deployment needs. + +The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints. +It is a background component of the [Smallstep Desktop App](./smallstep-app.mdx). +Most organizations choose only to deploy the agent. # Introduction -While macOS, Windows, and ChromeOS can manage certificates and authentication settings via Mobile Device Management (MDM), Linux does not include automated remote management facilities. The Smallstep Agent brings vital certificate management features to your Linux users and endpoints. It can be installed independently on any Linux device running systemd. +This guide covers manual installation of the Smallstep Agent on Linux, macOS, and Windows. +Use this guide if you +want to install the agent +via a software management tool separate from your MDM (eg Ansible, Munki), +or if your MDM only supports script-based software management. + +For MDM-based deployments, 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) -In this document, we will install, configure, and start the Smallstep Agent on a Linux device running systemd. We also show how to use the agent’s built-in PKCS#11 (smart card) service. With the PKCS#11 service, you can access Smallstep certificates and keys from applications that support PKCS#11. # System Requirements +## Linux + - Supported operating systems: - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc) - Ubuntu (Current Stable and LTS) @@ -22,26 +34,43 @@ In this document, we will install, configure, and start the Smallstep Agent on a - Fedora (Current Releases) - A TPM 2.0 module is required. Smallstep depends on TPMs to create a high-assurance device inventory. - We support `amd64` and `arm64` architectures - The following directories are used by default: +- The following directories are used by default: - runtime state in `/run/step-agent` - configuration in `/etc/step-agent` - - certificates in`/var/lib/step-agent` and in your configured locations -- The agent will connect to the following Smallstep hosts: - - Your CA: `.ca.smallstep.com` and subdomains - - Agent API: `control.infra.smallstep.com` - - Smallstep API: `gateway.smallstep.com` - - TPM Attestation CA: `att.smallstep.com` + - certificates in `/var/lib/step-agent` and in your configured locations + +## macOS + +- macOS 10.15 (Catalina) or later +- The agent must be installed for a single user (multi-user deployments are not yet supported) +- Installation location: `/Applications/SmallstepAgent.app` + +## Windows + +- Windows 10 (Anniversary Edition) or later +- Windows Home is not supported +- A TPM 2.0 module is required +- We support `amd64` and `arm64` architectures + +## Network Requirements (All Platforms) + +The agent will connect to the following Smallstep hosts: +- Your CA: `.ca.smallstep.com` and subdomains +- Agent API: `control.infra.smallstep.com` +- Smallstep API: `gateway.smallstep.com` +- TPM Attestation CA: `att.smallstep.com` -# Quick Install +# Linux Installation -On a system with `bash` and `curl`, run the following: +## Quick Install + +On a Linux system with `bash` and `curl`, run the following: ```bash curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | sudo env STEP_AGENT_TEAM=[your-team] bash ``` - -# Manual Install +## Manual Install ### Fedora @@ -194,7 +223,7 @@ curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | s Users can configure the agent and register their Linux device with your Smallstep team by running: -```jsx +```bash sudo step-agent-plugin register [team name] ``` @@ -209,7 +238,7 @@ Alternatively, you can pre-register all of your team's devices: The devices you add via API will be pre-approved. 2. Then, on your endpoints, update the `/etc/step-agent/agent.yaml` config file with your Smallstep team name and Smallstep Agent CA fingerprint. - ```jsx + ```bash team: "myteamname" fingerprint: "40523785c1d1d11EXAMPLE017b660d52a5fa5f2cb94cf0e1a9e9209dbea0826" ``` @@ -225,14 +254,14 @@ Alternatively, you can pre-register all of your team's devices: Finally, enable and start the agent: -```jsx +```bash sudo systemctl daemon-reload sudo systemctl enable --now step-agent ``` If you get any errors, check the agent’s status: -```jsx +```bash sudo systemctl status step-agent.service ``` @@ -277,3 +306,174 @@ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \ See the [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/) documentation for more details. +## Uninstall + +To uninstall the Smallstep Agent from a Linux system: + +1. Stop and disable the agent service: + + ```bash + sudo systemctl stop step-agent + sudo systemctl disable step-agent + ``` + +2. Remove the agent package: + + **For Fedora/RHEL/Enterprise Linux:** + ```bash + sudo dnf remove step-agent-plugin + ``` + + **For Debian/Ubuntu:** + ```bash + sudo apt-get remove step-agent-plugin + ``` + +3. Optionally, remove configuration and certificate files: + + ```bash + sudo rm -rf /etc/step-agent /var/lib/step-agent /run/step-agent + ``` + +# macOS Installation + +## Manual Install + +1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) + +2. Install the package on your endpoint (double-click the `.pkg` file, or use the `installer` command) + +3. Create a user launch agent file on the endpoint, in `/Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` for the primary user of the device. + + The Smallstep agent does not yet support multi-user deployments on macOS—it must be installed for a single user: + + ```xml + + + + + Label + com.smallstep.launchd.Agent + ProgramArguments + + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent + start + managed + + KeepAlive + + RunAtLoad + + AssociatedBundleIdentifiers + com.smallstep.Agent + + + ``` + +4. On the endpoint, register the launch agent by running: + + ```bash + launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist + ``` + +## Registering the Agent + + +## Confirmation + +There's two ways to confirm installation on a macOS endpoint: + +- In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp. +- On the device itself, run `/Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent version` to see that the agent is installed. And, in **System Settings**, check **Login Items** to confirm that there is a **Smallstep Agent** entry. + +## Uninstall + +To uninstall the Smallstep Agent from a macOS system: + +1. Stop and remove the launch agent: + + ```bash + launchctl stop com.smallstep.launchd.Agent + launchctl remove com.smallstep.launchd.Agent + ``` + +2. Run the agent's uninstall command: + + ```bash + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent svc uninstall + ``` + +3. Remove the application directory: + + ```bash + rm -rf /Applications/SmallstepAgent.app + ``` + +4. Remove the package receipt: + + ```bash + if pkgutil --packages | grep -q com.smallstep.Agent; then + pkgutil --forget com.smallstep.Agent + fi + ``` + +# Windows Installation + +## Manual Install + +1. Download the agent installer from the [Smallstep releases page](https://github.com/smallstep/step-agent-plugin/releases): + - For most systems: `step-agent-plugin_amd64_.msi` + - For ARM64 systems: `step-agent-plugin_arm64_.msi` + - EXE installer also available: `step-agent-plugin-Setup_amd64_.exe` + +2. Install the agent silently: + + **For MSI installer:** + ```powershell + msiexec.exe /i "path\to\step-agent-plugin_amd64.msi" /quiet + ``` + + **For EXE installer:** + ```powershell + step-agent-plugin-Setup_amd64_.exe /silent + ``` + +3. Configure the agent using PowerShell (run as Administrator): + + ```powershell + New-Item -Path "HKLM:\Software\Policies\Smallstep" + Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "TeamSlug" -Value "" + Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "Certificate" -Value "capi:store-location=machine;store=My;issuer=Smallstep () Agents Intermediate CA;cn=step-agent-bootstrap" + ``` + + Replace `` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)). + + If your team was created before October 2024, your issuer CA may have a common name without the team slug ("Smallstep Agents Intermediate CA"). Check your [Authority list](https://smallstep.com/app/?next=/cm/authorities) to confirm. + +## Registering the Agent + +After installation and configuration, the agent should automatically register with your Smallstep team. You can verify registration in the Smallstep UI by checking the device's profile page for an **Enrolled At** timestamp in the **Device Registration** section. + +## Confirmation + +To confirm the agent is installed and running on Windows: + +- In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp. +- On Windows, check that the agent service is running in the Services control panel, or run: `sc query "Smallstep Agent"` + +## Uninstall + +To uninstall the Smallstep Agent from a Windows system: + +```powershell +msiexec /x "{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}" /quiet +``` + +**Note:** The GUID shown above (`{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}`) is the product code for the Smallstep Agent MSI. To find the correct GUID for your installed version, you can run: + +```powershell +Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -like "*Smallstep*" } | Select-Object Name, IdentifyingNumber +``` + +Alternatively, uninstall via the Windows "Add or Remove Programs" settings. + diff --git a/tutorials/connect-intune-to-smallstep.mdx b/tutorials/connect-intune-to-smallstep.mdx index 3e9626ec..508ce20b 100644 --- a/tutorials/connect-intune-to-smallstep.mdx +++ b/tutorials/connect-intune-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: November 12, 2025 title: Connect Intune to Smallstep html_title: Connect Microsoft Intune to Smallstep Tutorial description: Connect Microsoft Intune to Smallstep for Windows device identity. Step-by-step guide for enterprise device trust with MDM integration. @@ -9,7 +9,9 @@ Smallstep can integrate with Microsoft Intune to synchronize your device invento In this document, we will configure your Microsoft Intune instance for use with your Smallstep team and any Windows endpoints. -To configure the connection, let’s first set up an Application in Entra ID. Then, we’ll add the client credentials to Smallstep. +**Note:** If you're not using Intune or need to install the agent manually or via scripts, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#windows-installation) guide. + +To configure the connection, let's first set up an Application in Entra ID. Then, we'll add the client credentials to Smallstep. # Prerequisites diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index c19e36b4..5b51fece 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/tutorials/connect-jamf-pro-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: November 12, 2025 title: Connect Jamf Pro to Smallstep html_title: Integrate Jamf Pro with Smallstep Tutorial description: Integrate Jamf Pro with Smallstep for Apple device security. Complete guide for enforcing device trust in macOS and iOS environments. @@ -87,8 +87,12 @@ Your Smallstep team is now linked to Jamf Pro. Smallstep will do a partial sync ## Install the Smallstep agent -There's two ways to install the agent: Using Jamf Pro, or using a separate software management tool. -For example, [Munki](https://www.munki.org/munki/) is a popular option for managing macOS apps in a large IT organization. +There's two ways to install the agent: + +- **Option 1** (below): Use Jamf Pro's package distribution and policy management +- **Option 2**: Use a separate software management tool like [Munki](https://www.munki.org/munki/), or install manually via scripts + +For Option 2, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#macos-installation) guide for detailed macOS installation instructions. ### Option 1: Install the agent via Jamf @@ -281,46 +285,6 @@ By default, Jamf will attempt to re-deploy the configured package profile to eve 3. Set the value to the new version that you uploaded in the previous step. 4. Save -### Option 2: Install via a software management tool - -If you're using a software management tool: - -1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) -2. Distribute and install the package on your desired endpoints -3. Create a user launch agent file on the endpoint, in `/Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` for the primary user of the device. - - The Smallstep agent does not yet support multi-user deployments on macOS—it must be installed for a single user: - - ``` - - - - - Label - com.smallstep.launchd.Agent - ProgramArguments - - /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent - start - managed - - KeepAlive - - RunAtLoad - - AssociatedBundleIdentifiers - com.smallstep.Agent - - - ``` - -4. On the endpoint, register the launch agent by running the following: - - ``` - launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` - ``` - - ## Confirmation There's two ways to confirm installation on an endpoint: diff --git a/tutorials/connect-workspace-one-to-smallstep.mdx b/tutorials/connect-workspace-one-to-smallstep.mdx index 1e34db97..b33532e5 100644 --- a/tutorials/connect-workspace-one-to-smallstep.mdx +++ b/tutorials/connect-workspace-one-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: October 28, 2025 +updated_at: November 12, 2025 title: Connect Workspace One UEM to Smallstep html_title: VMware Workspace ONE Integration Guide description: Connect Workspace ONE UEM to Smallstep for unified device identity. Enterprise guide for cross-platform device security management. @@ -7,7 +7,9 @@ description: Connect Workspace ONE UEM to Smallstep for unified device identity. Smallstep can integrate with [Omnissa Workspace ONE UEM](https://www.omnissa.com/products/workspace-one-unified-endpoint-management/) to keep your device inventory in sync and to exchange SCEP tokens. A SCEP token is a single-use password that's used by devices to get a certificate from Smallstep. -To configure the connection, let’s first set up an Application in Entra ID. Then, we’ll add the client credentials to Smallstep. +**Note:** If you're not using Workspace ONE UEM or need to install the agent manually or via scripts, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#windows-installation) guide. + +To configure the connection, let's first set up an Application in Entra ID. Then, we'll add the client credentials to Smallstep. # Prerequisites From 4ba3df700b3a17b6bed33ae8f8db9b2d8fe0bb83 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 17 Nov 2025 15:28:52 +0000 Subject: [PATCH 02/10] Updates to agent install doc --- platform/smallstep-agent.mdx | 84 +++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 34 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index b1141cab..5f0cf05a 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 12, 2025 +updated_at: November 17, 2025 title: Deploy the Agent html_title: Deploy the Smallstep Agent description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment. @@ -11,21 +11,34 @@ Most organizations choose only to deploy the agent. # Introduction -This guide covers manual installation of the Smallstep Agent on Linux, macOS, and Windows. +This guide covers manual installation of the Smallstep Agent on: + +* [Linux](#linux-installation) +* [macOS](#macos-installation) +* [Windows](#windows-installation) + Use this guide if you want to install the agent via a software management tool separate from your MDM (eg Ansible, Munki), -or if your MDM only supports script-based software management. +or if your MDM only supports limited software management workflows. -For MDM-based deployments, see: +If you manage package deployments via 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) -# System Requirements +# Network Access -## Linux +The agent will connect to the following Smallstep hosts: +- Your CA: `.ca.smallstep.com` and subdomains +- Agent API: `control.infra.smallstep.com` +- Smallstep API: `gateway.smallstep.com` +- TPM Attestation CA: `att.smallstep.com` + +# Linux Installation + +## System Requirements - Supported operating systems: - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc) @@ -39,29 +52,6 @@ For MDM-based deployments, see: - configuration in `/etc/step-agent` - certificates in `/var/lib/step-agent` and in your configured locations -## macOS - -- macOS 10.15 (Catalina) or later -- The agent must be installed for a single user (multi-user deployments are not yet supported) -- Installation location: `/Applications/SmallstepAgent.app` - -## Windows - -- Windows 10 (Anniversary Edition) or later -- Windows Home is not supported -- A TPM 2.0 module is required -- We support `amd64` and `arm64` architectures - -## Network Requirements (All Platforms) - -The agent will connect to the following Smallstep hosts: -- Your CA: `.ca.smallstep.com` and subdomains -- Agent API: `control.infra.smallstep.com` -- Smallstep API: `gateway.smallstep.com` -- TPM Attestation CA: `att.smallstep.com` - -# Linux Installation - ## Quick Install On a Linux system with `bash` and `curl`, run the following: @@ -337,11 +327,17 @@ To uninstall the Smallstep Agent from a Linux system: # macOS Installation +## System Requirements + +- macOS 10.15 (Catalina) or later +- The agent must be installed for a single user (multi-user deployments are not yet supported) +- Installation location: `/Applications/SmallstepAgent.app` + ## Manual Install 1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg) -2. Install the package on your endpoint (double-click the `.pkg` file, or use the `installer` command) +2. Install the package on your endpoint (double-click the `.pkg` file, or use the built-in `installer` command) 3. Create a user launch agent file on the endpoint, in `/Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` for the primary user of the device. @@ -370,7 +366,7 @@ To uninstall the Smallstep Agent from a Linux system: ``` -4. On the endpoint, register the launch agent by running: +4. On the endpoint, register the `launchd` agent by running: ```bash launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist @@ -378,6 +374,19 @@ To uninstall the Smallstep Agent from a Linux system: ## Registering the Agent +Your agent needs to enroll with your team. There's a few ways to do this: + +1. **User self-enrollment** To self-enroll a device, run: + + ``` + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent register + ``` + + Replace `` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)). + +2. **Enroll via API** + + If you have a list of Apple serial numbers for your devices, you can [enroll all of them via our API](https://smallstep.com/docs/platform/smallstep-api/#example-add-devices-via-the-api). Once added, they will be automatically approved. ## Confirmation @@ -419,12 +428,19 @@ To uninstall the Smallstep Agent from a macOS system: # Windows Installation +## System Requirements + +- Windows 10 (Anniversary Edition) or later +- Windows Home is not supported +- A TPM 2.0 module is required +- We support `amd64` and `arm64` architectures + ## Manual Install 1. Download the agent installer from the [Smallstep releases page](https://github.com/smallstep/step-agent-plugin/releases): - For most systems: `step-agent-plugin_amd64_.msi` - For ARM64 systems: `step-agent-plugin_arm64_.msi` - - EXE installer also available: `step-agent-plugin-Setup_amd64_.exe` + - Setup (exe) installer also available: `step-agent-plugin-Setup_amd64_.exe` 2. Install the agent silently: @@ -433,7 +449,7 @@ To uninstall the Smallstep Agent from a macOS system: msiexec.exe /i "path\to\step-agent-plugin_amd64.msi" /quiet ``` - **For EXE installer:** + **For Setup (exe) installer:** ```powershell step-agent-plugin-Setup_amd64_.exe /silent ``` @@ -452,7 +468,7 @@ To uninstall the Smallstep Agent from a macOS system: ## Registering the Agent -After installation and configuration, the agent should automatically register with your Smallstep team. You can verify registration in the Smallstep UI by checking the device's profile page for an **Enrolled At** timestamp in the **Device Registration** section. +After installation and configuration, the agent will automatically register with your Smallstep team. You can verify registration in the Smallstep UI by checking the device's profile page for an **Enrolled At** timestamp in the **Device Registration** section. ## Confirmation From 75a9bf4b7e04d97a3ad8976137d6058751a3803f Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 17 Nov 2025 15:34:48 +0000 Subject: [PATCH 03/10] Add links to agent manual installation doc --- tutorials/connect-intune-to-smallstep.mdx | 6 +++--- tutorials/connect-jamf-pro-to-smallstep.mdx | 10 ++++------ tutorials/connect-workspace-one-to-smallstep.mdx | 6 +++--- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/tutorials/connect-intune-to-smallstep.mdx b/tutorials/connect-intune-to-smallstep.mdx index 508ce20b..f675646a 100644 --- a/tutorials/connect-intune-to-smallstep.mdx +++ b/tutorials/connect-intune-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 12, 2025 +updated_at: November 17, 2025 title: Connect Intune to Smallstep html_title: Connect Microsoft Intune to Smallstep Tutorial description: Connect Microsoft Intune to Smallstep for Windows device identity. Step-by-step guide for enterprise device trust with MDM integration. @@ -9,8 +9,6 @@ Smallstep can integrate with Microsoft Intune to synchronize your device invento In this document, we will configure your Microsoft Intune instance for use with your Smallstep team and any Windows endpoints. -**Note:** If you're not using Intune or need to install the agent manually or via scripts, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#windows-installation) guide. - To configure the connection, let's first set up an Application in Entra ID. Then, we'll add the client credentials to Smallstep. # Prerequisites @@ -95,6 +93,8 @@ Within a few minutes, you will see all of your Intune devices in the [Devices](h ### 4. Add the Smallstep Agent for app distribution +**Note:** If you do not want to install the agent via Intune, see our [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#windows-installation) guide. + In this step, we’ll add the Smallstep Agent to Intune for distribution to devices. 1. In Intune, diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index 5b51fece..cbc1ab87 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/tutorials/connect-jamf-pro-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 12, 2025 +updated_at: November 17, 2025 title: Connect Jamf Pro to Smallstep html_title: Integrate Jamf Pro with Smallstep Tutorial description: Integrate Jamf Pro with Smallstep for Apple device security. Complete guide for enforcing device trust in macOS and iOS environments. @@ -89,12 +89,10 @@ Your Smallstep team is now linked to Jamf Pro. Smallstep will do a partial sync There's two ways to install the agent: -- **Option 1** (below): Use Jamf Pro's package distribution and policy management -- **Option 2**: Use a separate software management tool like [Munki](https://www.munki.org/munki/), or install manually via scripts +- **via Jamf** (below): Use Jamf Pro's package distribution and policy management +- **separately**: Use a separate software management tool like [Munki](https://www.munki.org/munki/), or install the agent manually via scripts. See the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#macos-installation) guide for detailed macOS installation instructions. -For Option 2, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#macos-installation) guide for detailed macOS installation instructions. - -### Option 1: Install the agent via Jamf +### Install the agent via Jamf #### Create an Agent Package for Distribution diff --git a/tutorials/connect-workspace-one-to-smallstep.mdx b/tutorials/connect-workspace-one-to-smallstep.mdx index b33532e5..c7a3a891 100644 --- a/tutorials/connect-workspace-one-to-smallstep.mdx +++ b/tutorials/connect-workspace-one-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 12, 2025 +updated_at: November 17, 2025 title: Connect Workspace One UEM to Smallstep html_title: VMware Workspace ONE Integration Guide description: Connect Workspace ONE UEM to Smallstep for unified device identity. Enterprise guide for cross-platform device security management. @@ -7,8 +7,6 @@ description: Connect Workspace ONE UEM to Smallstep for unified device identity. Smallstep can integrate with [Omnissa Workspace ONE UEM](https://www.omnissa.com/products/workspace-one-unified-endpoint-management/) to keep your device inventory in sync and to exchange SCEP tokens. A SCEP token is a single-use password that's used by devices to get a certificate from Smallstep. -**Note:** If you're not using Workspace ONE UEM or need to install the agent manually or via scripts, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#windows-installation) guide. - To configure the connection, let's first set up an Application in Entra ID. Then, we'll add the client credentials to Smallstep. # Prerequisites @@ -67,6 +65,8 @@ Within a few minutes after adding the connection, you should see all of your Wor ### 3. Create a script for Smallstep Agent configuration +**Note:** If don't want to use Workspace ONE UEM to install the agent, see the [Smallstep Agent Manual Installation](../platform/smallstep-agent.mdx#windows-installation) guide. + 1. In Workspace One UEM, visit **Resources → Scripts** 2. Choose **Add** and then **Windows** 1. In the General tab, provide a name for the script, such as “Smallstep Agent Enrollment” From 3eb16b1fc0511d3e5aabf50531cb3f63f293b5b7 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 18 Nov 2025 17:50:41 +0000 Subject: [PATCH 04/10] More updates --- platform/smallstep-agent.mdx | 58 ++---------------------------------- 1 file changed, 3 insertions(+), 55 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 5f0cf05a..abd1d887 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,13 +1,11 @@ --- -updated_at: November 17, 2025 +updated_at: November 18, 2025 title: Deploy the Agent html_title: Deploy the Smallstep Agent description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment. --- The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints. -It is a background component of the [Smallstep Desktop App](./smallstep-app.mdx). -Most organizations choose only to deploy the agent. # Introduction @@ -339,44 +337,10 @@ To uninstall the Smallstep Agent from a Linux system: 2. Install the package on your endpoint (double-click the `.pkg` file, or use the built-in `installer` command) -3. Create a user launch agent file on the endpoint, in `/Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist` for the primary user of the device. - - The Smallstep agent does not yet support multi-user deployments on macOS—it must be installed for a single user: - - ```xml - - - - - Label - com.smallstep.launchd.Agent - ProgramArguments - - /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent - start - managed - - KeepAlive - - RunAtLoad - - AssociatedBundleIdentifiers - com.smallstep.Agent - - - ``` - -4. On the endpoint, register the `launchd` agent by running: - - ```bash - launchctl load /Users//Library/LaunchAgents/com.smallstep.launchd.Agent.plist - ``` - ## Registering the Agent -Your agent needs to enroll with your team. There's a few ways to do this: - -1. **User self-enrollment** To self-enroll a device, run: +Your agent needs to enroll with your team. +To self-enroll a device, run: ``` /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent register @@ -384,10 +348,6 @@ Your agent needs to enroll with your team. There's a few ways to do this: Replace `` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)). -2. **Enroll via API** - - If you have a list of Apple serial numbers for your devices, you can [enroll all of them via our API](https://smallstep.com/docs/platform/smallstep-api/#example-add-devices-via-the-api). Once added, they will be automatically approved. - ## Confirmation There's two ways to confirm installation on a macOS endpoint: @@ -454,18 +414,6 @@ To uninstall the Smallstep Agent from a macOS system: step-agent-plugin-Setup_amd64_.exe /silent ``` -3. Configure the agent using PowerShell (run as Administrator): - - ```powershell - New-Item -Path "HKLM:\Software\Policies\Smallstep" - Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "TeamSlug" -Value "" - Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "Certificate" -Value "capi:store-location=machine;store=My;issuer=Smallstep () Agents Intermediate CA;cn=step-agent-bootstrap" - ``` - - Replace `` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)). - - If your team was created before October 2024, your issuer CA may have a common name without the team slug ("Smallstep Agents Intermediate CA"). Check your [Authority list](https://smallstep.com/app/?next=/cm/authorities) to confirm. - ## Registering the Agent After installation and configuration, the agent will automatically register with your Smallstep team. You can verify registration in the Smallstep UI by checking the device's profile page for an **Enrolled At** timestamp in the **Device Registration** section. From 0cd99a6d6760796d41709f452fda05dfea65ede7 Mon Sep 17 00:00:00 2001 From: Josh Drake Date: Fri, 5 Dec 2025 12:24:53 -0600 Subject: [PATCH 05/10] Improve agent documentation and add troubleshooting page. --- manifest.json | 4 + platform/smallstep-agent.mdx | 5 - platform/smallstep-app.mdx | 41 ++-- platform/troubleshooting-agent.mdx | 366 +++++++++++++++++++++++++++++ 4 files changed, 396 insertions(+), 20 deletions(-) create mode 100644 platform/troubleshooting-agent.mdx diff --git a/manifest.json b/manifest.json index 463512de..fb6fd63b 100644 --- a/manifest.json +++ b/manifest.json @@ -73,6 +73,10 @@ "title": "Deploy to Linux", "path": "/platform/smallstep-agent.mdx" }, + { + "title": "Troubleshooting the Agent", + "path": "/platform/troubleshooting-agent.mdx" + }, { "title": "Configure Browser Certificates", "path": "/tutorials/browser-certificate-setup-guide.mdx" diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index c89047b8..80fa7618 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -26,11 +26,6 @@ In this document, we will install, configure, and start the Smallstep Agent on a - runtime state in `/run/step-agent` - configuration in `/etc/step-agent` - certificates in`/var/lib/step-agent` and in your configured locations -- The agent will connect to the following Smallstep hosts: - - Your CA: `.ca.smallstep.com` and subdomains - - Agent API: `control.infra.smallstep.com` - - Smallstep API: `gateway.smallstep.com` - - TPM Attestation CA: `att.smallstep.com` # Quick Install diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx index cb785bab..a6e8ff0c 100644 --- a/platform/smallstep-app.mdx +++ b/platform/smallstep-app.mdx @@ -1,20 +1,22 @@ --- updated_at: September 17, 2025 -title: The Smallstep App -html_title: Smallstep App User Documentation Guide -description: Complete guide to the Smallstep App for enterprise security workflows. Manage certificates, devices, and identity from a unified interface. +title: The Smallstep Agent +html_title: Smallstep Agent User Documentation Guide +description: Complete guide to the Smallstep Agent for enterprise security workflows. Manage certificates, devices, and identity from a unified interface. --- -Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted devices. +Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted devices. -The Smallstep desktop app offers a uniform experience for device identity across macOS, Windows, and Linux, and is foundational to Smallstep's high-assurance device attestation workflow, automating the enrollment and delivery of client certificates, and configuring the components that depend on them. +The Smallstep Agent offers a uniform experience for device identity across macOS, Windows, and Linux, and is foundational to Smallstep's high-assurance device attestation workflow, automating the enrollment and delivery of client certificates, and configuring the components that depend on them. -The Smallstep app operates differently for Linux. For Linux specific instructions, see [Smallstep Agent for Linux](./smallstep-agent.mdx). +The agent runs as a background service on all platforms. On macOS and Windows, the agent includes an optional desktop app that provides visibility into the agent's status and aids in troubleshooting. + +The Smallstep Agent operates differently for Linux. For Linux specific instructions, see [Smallstep Agent for Linux](./smallstep-agent.mdx). ## Download -The Smallstep App includes the Smallstep Agent, -which runs in the background. +On macOS and Windows, the Smallstep Agent includes an optional desktop app UI for transparency and troubleshooting. +The agent runs as a background service on all platforms. Installers for macOS, Windows and Linux can be also be downloaded from [GitHub releases](https://github.com/smallstep/smallstep-desktop/releases). Releases are signed with, and can be verified, by cosign. @@ -53,20 +55,29 @@ All platforms require an internet connection for normal operation. ### Windows -- *Administrator privileges* - the Smallstep app requires privilege escalation to be able to communicate to the TPM +- *Administrator privileges* - the Smallstep Agent requires privilege escalation to be able to communicate to the TPM ### macOS -- *Location permission* - to enable management of Wifi networks, the Smallstep app needs location permission -- *Keychain access* - the Smallstep app uses the macOS keychain to store both keys and certificates it manages -- *Network Extension entitlement* - the Smallstep app requests the *Network Extension* entitlement so that it can manage VPN connections +- *Location permission* - to enable management of Wifi networks, the Smallstep Agent needs location permission +- *Keychain access* - the Smallstep Agent uses the macOS keychain to store both keys and certificates it manages +- *Network Extension entitlement* - the Smallstep Agent requests the *Network Extension* entitlement so that it can manage VPN connections ### Linux -- *TPM read/write permission* - the Smallstep app communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`) +- *TPM read/write permission* - the Smallstep Agent communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`) + +## Connectivity Requirements + +The Smallstep Agent connects to the following Smallstep hosts: +- Your CA: `.ca.smallstep.com` and subdomains +- Agent API: `control.infra.smallstep.com` +- Smallstep API: `gateway.smallstep.com` +- TPM Attestation CA: `att.smallstep.com` ## File Access -On all platforms, the Smallstep app creates and manages a directory on the filesystem in a well-known location for management of keys and certificates. However, it does not access any other file on a device except the one it creates. + +On all platforms, the Smallstep Agent creates and manages a directory on the filesystem in a well-known location for management of keys and certificates. However, it does not access any other file on a device except the one it creates. - On macOS: `$HOME/Library/Application Support/Smallstep` - On Windows: `%LOCALAPPDATA%/Smallstep` @@ -74,7 +85,7 @@ On all platforms, the Smallstep app creates and manages a directory on the files ## Telemetry -The Smallstep app collects and reports some data from the host device as part of its normal operation. These are: +The Smallstep Agent collects and reports some data from the host device as part of its normal operation. These are: - Device Identifiers from TPM-enabled platforms - Device/Computer Name diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx new file mode 100644 index 00000000..77bbb3b7 --- /dev/null +++ b/platform/troubleshooting-agent.mdx @@ -0,0 +1,366 @@ +--- +updated_at: December 05, 2025 +title: Troubleshooting the Smallstep Agent +html_title: Smallstep Agent Troubleshooting Guide +description: Troubleshoot common issues with the Smallstep Agent. Learn how to use the doctor command and resolve connectivity, certificate, and configuration problems. +--- + +This guide helps you diagnose and resolve common issues with the Smallstep Agent. The agent includes built-in diagnostic tools to help identify problems quickly. + +## Prerequisites + +Before troubleshooting, ensure your system meets the requirements: +- Review [System Requirements](./smallstep-app.mdx#system-requirements) +- Check [Runtime Requirements](./smallstep-app.mdx#runtime-requirements) +- Verify [Connectivity Requirements](./smallstep-app.mdx#connectivity-requirements) + +## Using the Doctor Command + +The Smallstep Agent includes a `doctor` command that performs automated health checks and provides diagnostic information. This is the recommended first step when troubleshooting issues. + +### Running the Doctor Command + +**On macOS and Windows:** +```bash +step-agent-plugin doctor +``` + +**On Linux:** +```bash +sudo step-agent-plugin doctor +``` + +The doctor command runs a series of checks and displays results in a table format: + +``` ++------------------------------------------+--------+-------------+ +| Check | Status | Description | ++------------------------------------------+--------+-------------+ +| Check runtime requirements | PASS | | +| Ping the agent | PASS | | +| Check attestation CA connectivity | PASS | | +| Check API gateway connectivity | PASS | | +| Check mission control connectivity | PASS | | +| Bootstrap certificate authorities | PASS | | +| Verify issued certificates | PASS | | +| Sign with endpoint keys | PASS | | +| Enumerate PKCS#11 objects | PASS | | ++------------------------------------------+--------+-------------+ +``` + +### Understanding Doctor Output + +Each check validates a specific aspect of the agent's functionality. A **PASS** status means the check succeeded, while **FAIL** indicates a problem that needs attention. + +#### Check Runtime Requirements + +**What it checks:** Verifies that your system has the necessary components for the agent to function: +- **TPM 2.0 availability** - Ensures the Trusted Platform Module is accessible and can create/delete keys +- **systemd** (Linux only) - Confirms systemd is running for managing network connections + +**Common failure reasons:** +- No TPM 2.0 module present or enabled in BIOS/UEFI +- TPM is locked or inaccessible +- User lacks permissions to access the TPM (Linux) +- systemd is not the init system (Linux) + +**Troubleshooting steps:** +1. Verify TPM 2.0 is enabled in your system BIOS/UEFI settings +2. On Linux, check TPM permissions: `ls -l /dev/tpm*` +3. On Linux, ensure the user has read/write access to `/dev/tpmrm0` +4. On Windows, verify TPM is enabled: Run `tpm.msc` or check Device Manager +5. On Linux, confirm systemd is running: `ps -p 1 -o comm=` + +#### Ping the Agent + +**What it checks:** Verifies the agent background service is running and responding to IPC requests. + +**Common failure reasons:** +- Agent service is not running +- Agent service crashed or failed to start +- IPC socket is inaccessible + +**Troubleshooting steps:** +1. Check if the agent service is running: + - **macOS:** Look for Smallstep in Activity Monitor + - **Windows:** Check Task Manager for the Smallstep Agent process + - **Linux:** Run `sudo systemctl status step-agent` +2. Restart the agent service: + - **macOS/Windows:** Restart from the desktop app or System Settings + - **Linux:** Run `sudo systemctl restart step-agent` +3. Check agent logs for error messages: + - **Linux:** Run `sudo journalctl -u step-agent -n 50` + +#### Check Attestation CA Connectivity + +**What it checks:** Tests network connectivity to `att.smallstep.com` (TPM Attestation CA). + +**Common failure reasons:** +- Firewall blocking outbound HTTPS connections +- Proxy configuration required but not set +- Network connectivity issues +- DNS resolution failure + +**Troubleshooting steps:** +1. Test connectivity manually: `curl -v https://att.smallstep.com` +2. Check firewall rules allow HTTPS to `att.smallstep.com` +3. If behind a proxy, ensure proxy settings are configured +4. Verify DNS resolution: `nslookup att.smallstep.com` + +#### Check API Gateway Connectivity + +**What it checks:** Tests network connectivity to `gateway.smallstep.com` (Smallstep API). + +**Common failure reasons:** +- Same as attestation CA connectivity issues + +**Troubleshooting steps:** +1. Test connectivity manually: `curl -v https://gateway.smallstep.com` +2. Check firewall rules allow HTTPS to `gateway.smallstep.com` +3. Review network and proxy configuration + +#### Check Mission Control Connectivity + +**What it checks:** Tests gRPC connectivity to `control.infra.smallstep.com:443` (Agent API). + +**Common failure reasons:** +- Firewall blocking port 443 for gRPC traffic +- Deep packet inspection interfering with gRPC +- Proxy not configured for gRPC + +**Troubleshooting steps:** +1. Test connectivity manually: `curl -v https://control.infra.smallstep.com` +2. Check firewall rules allow HTTPS/gRPC to `control.infra.smallstep.com` +3. Some corporate firewalls may block gRPC - work with your network team + +#### Bootstrap Certificate Authorities + +**What it checks:** Verifies the agent can retrieve and validate CA root certificates from your Smallstep team's CA. + +**Common failure reasons:** +- Connectivity issues to `.ca.smallstep.com` +- Invalid or expired CA fingerprint in configuration +- Agent not properly registered with your team + +**Troubleshooting steps:** +1. Verify connectivity to your CA: `curl -v https://.ca.smallstep.com` +2. Check the agent configuration file for correct team name and fingerprint: + - **macOS/Windows:** Configuration in app settings + - **Linux:** Check `/etc/step-agent/agent.yaml` +3. Ensure the device is approved in your Smallstep console + +#### Verify Issued Certificates + +**What it checks:** Validates that all endpoint certificates are currently valid (not expired or not yet valid). + +**Common failure reasons:** +- Certificates expired due to agent being offline +- System clock is incorrect +- Certificate renewal failed + +**Troubleshooting steps:** +1. Verify system clock is accurate: `date` +2. If clock was wrong, correct it and restart the agent +3. Check when certificates will expire (look in agent logs or desktop app) +4. Run doctor with `--renew` flag to force certificate renewal (see below) + +#### Sign with Endpoint Keys + +**What it checks:** Tests that the agent can perform cryptographic signing operations with endpoint keys stored in the TPM/Secure Enclave. + +**Common failure reasons:** +- TPM/Secure Enclave access issues +- Keys were deleted or corrupted +- Permission issues accessing keys + +**Troubleshooting steps:** +1. Verify TPM/Secure Enclave is accessible (see runtime requirements above) +2. Check agent logs for key access errors +3. If keys are corrupted, the agent may need to re-register + +#### Enumerate PKCS#11 Objects + +**What it checks:** (Linux/macOS only) Verifies that certificates and keys are accessible via the PKCS#11 interface. + +**Common failure reasons:** +- PKCS#11 server not running +- `P11_KIT_SERVER_ADDRESS` environment variable not set correctly +- p11-kit not installed or configured + +**Troubleshooting steps:** +1. Verify the PKCS#11 socket exists: + ```bash + ls -l $XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock + ``` +2. Check the environment variable: + ```bash + echo $P11_KIT_SERVER_ADDRESS + ``` +3. Test PKCS#11 manually: + ```bash + pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so --list-slots + ``` +4. See [PKCS#11 Support](./smallstep-agent.mdx#openssl-and-pkcs11-support) for configuration details + +### Advanced Doctor Options + +#### Force Certificate Renewal + +To test certificate renewal as part of the doctor checks, use the `--renew` flag: + +```bash +step-agent-plugin doctor --renew +``` + +This will attempt to renew all endpoint certificates and report any failures. This is useful when: +- Certificates are close to expiration +- Testing the renewal workflow +- Recovering from a certificate expiration issue + + +The `--renew` flag will trigger certificate renewal for all endpoints, which may briefly interrupt services using those certificates. + + +#### JSON Output + +For scripting or integration with monitoring tools, use the `--json` flag: + +```bash +step-agent-plugin doctor --json +``` + +This outputs check results in JSON format: + +```json +{ + "authorities": { + "Description": "", + "State": "PASS" + }, + "certificates": { + "Description": "", + "State": "PASS" + }, + "network-attestation": { + "Description": "", + "State": "PASS" + }, + "network-control": { + "Description": "", + "State": "PASS" + }, + "network-gateway": { + "Description": "", + "State": "PASS" + }, + "ping": { + "Description": "", + "State": "PASS" + }, + "preflight": { + "Description": "", + "State": "PASS" + }, + "sign": { + "Description": "", + "State": "PASS" + } +} +``` + +## Common Issues and Solutions + +### Agent Won't Start + +**Symptoms:** +- Agent service fails to start +- Desktop app shows "Agent not running" +- Doctor ping check fails + +**Solutions:** +1. Check system requirements are met +2. Run `step-agent-plugin doctor` to identify specific issues +3. Check agent logs for startup errors +4. Restart the system if the TPM is in an inconsistent state +5. On Linux, check for conflicting services using the same ports + +### Network Connectivity Issues + +**Symptoms:** +- All network checks fail in doctor output +- Agent shows "offline" status +- Certificate renewal fails + +**Solutions:** +1. Verify internet connectivity: `ping 8.8.8.8` +2. Test DNS resolution: `nslookup gateway.smallstep.com` +3. Review [Connectivity Requirements](./smallstep-app.mdx#connectivity-requirements) +4. Check corporate firewall and proxy settings +5. Ensure all required Smallstep hosts are allowlisted + +### Certificate Expired or Invalid + +**Symptoms:** +- "Verify issued certificates" check fails +- Applications can't authenticate +- Certificate errors in browser or VPN + +**Solutions:** +1. Check system clock is accurate +2. Run `step-agent-plugin doctor --renew` to force renewal +3. If agent was offline for extended period, certificates may have expired +4. Check agent logs for renewal errors +5. Verify connectivity to your team's CA + +### TPM/Secure Enclave Access Issues + +**Symptoms:** +- Runtime requirements check fails +- "Sign with endpoint keys" check fails +- Agent can't create or access keys + +**Solutions:** +1. **Windows:** + - Run agent with administrator privileges + - Verify TPM is enabled in Device Manager + - Check TPM status: `Get-Tpm` in PowerShell +2. **macOS:** + - Ensure app has keychain access permission + - Check System Settings > Privacy & Security > Keychain +3. **Linux:** + - Check TPM permissions: `ls -l /dev/tpmrm0` + - Add user to tss group: `sudo usermod -a -G tss $USER` + - Verify tpm2-tss is installed + +### PKCS#11 Not Working (Linux/macOS) + +**Symptoms:** +- Applications can't access certificates via PKCS#11 +- Chrome/Firefox don't see Smallstep certificates +- NetworkManager can't use agent certificates + +**Solutions:** +1. Verify PKCS#11 socket exists and is accessible +2. Set environment variable correctly: + ```bash + export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock + ``` +3. Install p11-kit if not present +4. Test with `pkcs11-tool --list-slots` +5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#openssl-and-pkcs11-support) + +## Getting Help + +If you've tried the troubleshooting steps above and still have issues: + +1. **Run doctor command** and save the output +2. **Collect agent logs:** + - **Linux:** `sudo journalctl -u step-agent -n 200` + - **macOS/Windows:** Export logs from the desktop app +3. **Note your configuration:** + - Operating system and version + - Smallstep Agent version (`step-agent-plugin version`) + - Any error messages or failure descriptions +4. **Contact Smallstep support** with the information above + +For security issues or private questions, email support@smallstep.com. From c81b749764ffcbb75a7e4588b270f6d15ad17711 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 5 Jan 2026 17:07:52 -0600 Subject: [PATCH 06/10] Small changes to smallstep-agent.mdx --- platform/smallstep-agent.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index abd1d887..ed71414d 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 18, 2025 +updated_at: January 05, 2026 title: Deploy the Agent html_title: Deploy the Smallstep Agent description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment. @@ -9,7 +9,7 @@ The Smallstep Agent brings automated certificate management, device identity, an # Introduction -This guide covers manual installation of the Smallstep Agent on: +This guide covers **manual installation** of the Smallstep Agent on: * [Linux](#linux-installation) * [macOS](#macos-installation) @@ -20,11 +20,12 @@ want to install the agent via a software management tool separate from your MDM (eg Ansible, Munki), or if your MDM only supports limited software management workflows. -If you manage package deployments via MDM, see: + +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) - + # Network Access @@ -400,7 +401,7 @@ To uninstall the Smallstep Agent from a macOS system: 1. Download the agent installer from the [Smallstep releases page](https://github.com/smallstep/step-agent-plugin/releases): - For most systems: `step-agent-plugin_amd64_.msi` - For ARM64 systems: `step-agent-plugin_arm64_.msi` - - Setup (exe) installer also available: `step-agent-plugin-Setup_amd64_.exe` + - A Setup (exe) installer is also available: `step-agent-plugin-Setup_amd64_.exe` 2. Install the agent silently: From 4820ed251ad2a16268295e5fe7bf9cadf405b8a4 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 5 Jan 2026 17:17:06 -0600 Subject: [PATCH 07/10] Move api docs --- platform/enrollment-guide.mdx | 27 ++++++++++++++++++++------- platform/smallstep-api.mdx | 31 ++----------------------------- 2 files changed, 22 insertions(+), 36 deletions(-) diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 65de2b81..8fdf8626 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 11, 2025 +updated_at: January 05, 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. @@ -32,7 +32,7 @@ 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 Desktop App](./smallstep-app.mdx) -or the [Smallstep Agent for Linux](./smallstep-agent.mdx). +or the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators must approve a new device @@ -79,12 +79,25 @@ Devices added via API are automatically approved. but they will not be marked as high-assurance until Smallstep receives an attestation from the device. -#### Example: I have a list of device identifiers +Use the [Add Device](https://gateway.smallstep.com/v2025-01-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. + +Once added, +the devices will be automatically approved. -For each device, use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device. +You can see the device using the [List Devices](https://gateway.smallstep.com/v2025-01-01/operations/ListDevices) endpoint: -Devices are automatically approved when added via API. +```bash +set +o history +echo "Authorization: Bearer [your API token]" > api_headers +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 +``` -Once added, -you'll see devices in the Smallstep console, +You'll also see new devices in the Smallstep console, under [Devices](https://smallstep.com/app/?next=/devices). diff --git a/platform/smallstep-api.mdx b/platform/smallstep-api.mdx index ecdc0cc2..2a239fae 100644 --- a/platform/smallstep-api.mdx +++ b/platform/smallstep-api.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: January 05, 2026 title: Smallstep API html_title: Platform API Reference Documentation Guide description: Complete API reference for managing devices, certificates, and PKI programmatically. Integrate Smallstep into your security workflows. @@ -32,31 +32,4 @@ You can get an API token in two ways: ### Example: Add devices via the API You can import devices from any source into Smallstep using our API. - -Devices added via API are automatically approved. -but they will not be marked as high-assurance -until Smallstep receives an attestation from the device. - -Use the [Add Device](https://gateway.smallstep.com/v2025-01-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. - -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: - -```bash -set +o history -echo "Authorization: Bearer [your API token]" > api_headers -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 -``` - -Or, in your Smallstep console, -you'll see the device listed under Recent Devices. - +See [Build Your Inventory](./enrollment-guide.mdx) for details. From b0c437f72e4825b69e16c3092db8e20f99474618 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 5 Jan 2026 17:28:31 -0600 Subject: [PATCH 08/10] Add API-based enrollment instructions for Windows --- platform/enrollment-guide.mdx | 2 ++ platform/smallstep-agent.mdx | 38 +++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 8fdf8626..1d10724d 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -79,6 +79,8 @@ Devices added via API are automatically approved. but they will not be marked as high-assurance 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. - 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.) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index ed71414d..ef1291e8 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -417,6 +417,44 @@ To uninstall the Smallstep Agent from a macOS system: ## Registering the Agent +### Using the Smallstep API + +Before you begin, [create an API token](https://smallstep.com/app/?next=/settings/api/tokens/add) with at least all “device” scopes (put-device, patch-device, etc.) + +1. On the device, configure the agent for enrollment: + +``` +New-Item -Path "HKLM:\Software\Policies\Smallstep" +Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "TeamSlug" -Value "" +Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "CAFingerprint" -Value "" +``` + +Replace `` and `` with your Smallstep [team ID](https://smallstep.com/app/?next=/settings) and the CA fingerprint of your Smallstep Agents CA. + +2. On the device, navigate to the agent installation directory and obtain the device's TPM fingerprint: + +``` +cd 'C:\Program Files\Smallstep\SmallstepApp\' +.\smallstep-agent.exe tpm --fingerprint +``` + +3. Register the device's TPM [using Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) and the following request body: + +``` +{ + "os": "Windows", + "ownership": "company", + "permanentIdentifier": "", + "user": { + "email": "" + } +} +``` + +4. [Approve the device in the Smallstep console](https://smallstep.com/app/?next=/devices) + +5. Restart the device OR manually ensure the `Smallstep Agent` Windows service is started + After installation and configuration, the agent will automatically register with your Smallstep team. You can verify registration in the Smallstep UI by checking the device's profile page for an **Enrolled At** timestamp in the **Device Registration** section. ## Confirmation From 50eda98bf70a4969bdaf002710251d4d7baeaa5d Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 5 Jan 2026 17:56:42 -0600 Subject: [PATCH 09/10] Windows doctor command --- platform/troubleshooting-agent.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index 5c49b976..bc284512 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -20,11 +20,16 @@ The Smallstep Agent includes a `doctor` command that performs automated health c ### Running the Doctor Command -**On macOS and Windows:** +**On macOS:** ```bash step-agent-plugin doctor ``` +**On Windows:** +```bash +& 'C:\Program Files\Smallstep\SmallstepApp\smallstep-agent.exe' doctor +``` + **On Linux:** ```bash sudo step-agent-plugin doctor From 62c6489700c130bef3744817a4049baebb31d1b5 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 6 Jan 2026 11:32:10 -0600 Subject: [PATCH 10/10] Updates from devices standup --- platform/smallstep-agent.mdx | 37 +++++------------------------- platform/troubleshooting-agent.mdx | 4 ++-- 2 files changed, 8 insertions(+), 33 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index ef1291e8..0ec62ffd 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: January 05, 2026 +updated_at: January 06, 2026 title: Deploy the Agent html_title: Deploy the Smallstep Agent description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment. @@ -299,14 +299,7 @@ See the [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/) documenta To uninstall the Smallstep Agent from a Linux system: -1. Stop and disable the agent service: - - ```bash - sudo systemctl stop step-agent - sudo systemctl disable step-agent - ``` - -2. Remove the agent package: +1. Remove the agent package: **For Fedora/RHEL/Enterprise Linux:** ```bash @@ -318,7 +311,7 @@ To uninstall the Smallstep Agent from a Linux system: sudo apt-get remove step-agent-plugin ``` -3. Optionally, remove configuration and certificate files: +2. Optionally, remove configuration and certificate files: ```bash sudo rm -rf /etc/step-agent /var/lib/step-agent /run/step-agent @@ -360,17 +353,12 @@ There's two ways to confirm installation on a macOS endpoint: To uninstall the Smallstep Agent from a macOS system: -1. Stop and remove the launch agent: - - ```bash - launchctl stop com.smallstep.launchd.Agent - launchctl remove com.smallstep.launchd.Agent - ``` - -2. Run the agent's uninstall command: +1. Run the following to uninstall the launch agent and remove runtime state: ```bash /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent svc uninstall + /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent reset + rm /Library/LaunchAgents/com.smallstep.launchd.Agent.plist ``` 3. Remove the application directory: @@ -401,20 +389,13 @@ To uninstall the Smallstep Agent from a macOS system: 1. Download the agent installer from the [Smallstep releases page](https://github.com/smallstep/step-agent-plugin/releases): - For most systems: `step-agent-plugin_amd64_.msi` - For ARM64 systems: `step-agent-plugin_arm64_.msi` - - A Setup (exe) installer is also available: `step-agent-plugin-Setup_amd64_.exe` 2. Install the agent silently: - **For MSI installer:** ```powershell msiexec.exe /i "path\to\step-agent-plugin_amd64.msi" /quiet ``` - **For Setup (exe) installer:** - ```powershell - step-agent-plugin-Setup_amd64_.exe /silent - ``` - ## Registering the Agent ### Using the Smallstep API @@ -472,11 +453,5 @@ To uninstall the Smallstep Agent from a Windows system: msiexec /x "{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}" /quiet ``` -**Note:** The GUID shown above (`{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}`) is the product code for the Smallstep Agent MSI. To find the correct GUID for your installed version, you can run: - -```powershell -Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -like "*Smallstep*" } | Select-Object Name, IdentifyingNumber -``` - Alternatively, uninstall via the Windows "Add or Remove Programs" settings. diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index bc284512..f7319ce1 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: January 05, 2026 +updated_at: January 06, 2026 title: Troubleshooting the Smallstep Agent html_title: Smallstep Agent Troubleshooting Guide description: Troubleshoot common issues with the Smallstep Agent. Learn how to use the doctor command and resolve connectivity, certificate, and configuration problems. @@ -26,7 +26,7 @@ step-agent-plugin doctor ``` **On Windows:** -```bash +```powershell & 'C:\Program Files\Smallstep\SmallstepApp\smallstep-agent.exe' doctor ```