diff --git a/manifest.json b/manifest.json index f6eb9919..83c0fcd5 100644 --- a/manifest.json +++ b/manifest.json @@ -78,11 +78,7 @@ "title": "Configure Devices for Smallstep", "routes": [ { - "title": "Install the Smallstep App", - "path": "/platform/smallstep-app.mdx" - }, - { - "title": "Deploy the Agent", + "title": "Install the Smallstep Agent", "path": "/platform/smallstep-agent.mdx" }, { diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 1b75d3cc..a671f932 100644 --- a/platform/enrollment-guide.mdx +++ b/platform/enrollment-guide.mdx @@ -31,8 +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 Desktop App](./smallstep-app.mdx) -or the [Smallstep Agent](./smallstep-agent.mdx). +using the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators must approve a new device @@ -48,8 +47,7 @@ With IdP self-enrollment enabled, when you connect Smallstep to your identity provider, your users will be able to self-enroll via single sign-on, -using the [Smallstep Desktop App](./smallstep-app.mdx) -or the [Smallstep Agent](./smallstep-agent.mdx). +using the [Smallstep Agent](./smallstep-agent.mdx). By default, administrators must approve newly enrolled devices diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 7d8d47ae..6fd24745 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,25 +1,22 @@ --- -updated_at: February 03, 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. +updated_at: May 21, 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. --- -The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints. +The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints across macOS, Windows, and Linux. + +The agent runs as a background service on all platforms. Smallstep also has an optional desktop UI for transparency and troubleshooting, offered as a separate package. # Introduction -This guide covers **manual installation** of the Smallstep Agent on: +This guide covers 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 limited software management workflows. - Using an MDM? See: - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS) @@ -27,29 +24,93 @@ Using an MDM? See: - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows) -# Network access +Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx). -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` +# System requirements -# Linux installation +## Windows -## System requirements +- Windows 10 or later (Windows Home editions are _not_ supported) +- Trusted Platform Module (TPM 2.0) +- Architectures: `amd64`, `arm64` + +## macOS + +- macOS 13 (Ventura) or later +- Secure Enclave +- The agent must be installed for a single user (multi-user deployments are not yet supported) + +## Linux - Supported operating systems: - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc) - Ubuntu (Current Stable and LTS) - Debian (Current Releases) - Fedora (Current Releases) +- `systemd`-based service manager - 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: - - runtime state in `/run/step-agent` - - configuration in `/etc/step-agent` - - certificates in `/var/lib/step-agent` and in your configured locations +- `p11-kit`, `tpm-tss2` +- Architectures: `amd64`, `arm64` + +# Runtime requirements + +All platforms require an internet connection for normal operation. + +## Windows + +- *Administrator privileges* — the Smallstep Agent requires privilege escalation to be able to communicate with the TPM. + +## macOS + +- *Location permission* — only required if the agent will manage Wi-Fi network configurations. +- *Keychain access* — the 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 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 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` + +# Downloads + +## All versions + +See [releases.smallstep.com](https://releases.smallstep.com) for all release history of +the Smallstep Agent, Smallstep Desktop app, and more. + +## Latest stable agent packages + +Here are URLs that always point at the latest stable release of the agent: + +**macOS** + +- [step-agent_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg) + +**Windows** + +- [step-agent_amd64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi) +- [step-agent_arm64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi) + +**Linux** + +- [step-agent_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb) +- [step-agent_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb) +- [step-agent_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm) +- [step-agent_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm) +- [step-agent_amd64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.pkg.tar.zst) +- [step-agent_arm64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.pkg.tar.zst) + +# Linux installation + +Smallstep also offers Debian and RPM package repositories. ## Quick install @@ -292,18 +353,7 @@ In Chrome, you should now have access to certificates managed by Smallstep. For regular usage, add `P11_KIT_SERVER_ADDRESS` to your environment more permanently. For example, you might add `P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock` to your global `/etc/environment` file. -#### Troubleshooting - -The agent produces a log file or journal entries in systemd, depending on how it is installed and run. - -You can use tools like `pkcs11-tool` for troubleshooting PKCS#11 support: - -```bash -pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \ - --list-slots -``` - -See the [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/) documentation for more details. +If PKCS#11 isn't working as expected, see [PKCS#11 troubleshooting](./troubleshooting-agent.mdx#pkcs11-not-working-linuxmacos). ## Uninstall @@ -329,12 +379,6 @@ 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_latest.pkg) @@ -373,13 +417,13 @@ To uninstall the Smallstep Agent from a macOS system: Replace `` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)). -3. Remove the application directory: +2. Remove the application directory: ```bash rm -rf /Applications/SmallstepAgent.app ``` -4. Remove the package receipt: +3. Remove the package receipt: ```bash if pkgutil --packages | grep -q com.smallstep.Agent; then @@ -389,13 +433,6 @@ 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 - ## Install via Winget Install the agent via [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/): diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx deleted file mode 100644 index 2690c893..00000000 --- a/platform/smallstep-app.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -updated_at: February 03, 2026 -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. - -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 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 - - -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. - - -Install packages are available from the [Smallstep package repository](https://releases.smallstep.com): - -- https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg -- https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi -- https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi -- https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb -- https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb -- https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm -- https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm -- https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.pkg.tar.zst -- https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.pkg.tar.zst - -For Linux installation instructions, see [Deploy the Agent](./smallstep-agent.mdx#linux-installation). - -## System requirements - -### Windows - -- Windows 10 or later (Windows Home editions are _not supported_.) -- Trusted Platform Module (TPM 2.0) - -### Linux - -- Debian 12+, Ubuntu 22.04+, Fedora 38+ -- `systemd`-based service manager -- Trusted Platform Module (TPM 2.0) -- p11-kit -- tpm-tss2 - -### macOS - -- macOS 13 (Ventura) or later -- Secure Enclave - -## Runtime requirements - -All platforms require an internet connection for normal operation. - -### Windows - -- *Administrator privileges* - the Smallstep Agent requires privilege escalation to be able to communicate to the TPM - -### macOS - -- *Location permission* - to enable management of Wi-Fi 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 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 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` -- On Linux: `$XDG_RUNTIME_DIR/step-agent` and `$XDG_CONFIG_HOME/step-agent` - -## Telemetry - -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 -- Device/Computer Hostname -- Chipset Architecture -- Operating System Version -- WAN IP Address diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index 6c1eee72..6fcc5492 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -127,9 +127,9 @@ This section covers issues with individual devices, the Smallstep Agent, and end ### Prerequisites Before troubleshooting endpoint issues, verify the device meets 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) +- Review [System Requirements](./smallstep-agent.mdx#system-requirements) +- Check [Runtime Requirements](./smallstep-agent.mdx#runtime-requirements) +- Verify [Connectivity Requirements](./smallstep-agent.mdx#connectivity-requirements) ### Using the doctor command @@ -417,7 +417,7 @@ This outputs check results in JSON format: **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) +3. Review [Connectivity Requirements](./smallstep-agent.mdx#connectivity-requirements) 4. Check corporate firewall and proxy settings 5. Ensure all required Smallstep hosts are allowlisted @@ -462,6 +462,19 @@ This outputs check results in JSON format: - Chrome/Firefox don't see Smallstep certificates - NetworkManager can't use agent certificates +**Diagnose:** + +The agent produces a log file or journal entries in systemd, depending on how it is installed and run. Start there. + +You can also use tools like `pkcs11-tool` to enumerate the slots exposed by the PKCS#11 server: + +```bash +pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \ + --list-slots +``` + +The location of `p11-kit-client.so` may vary by distribution. + **Solutions:** 1. Verify PKCS#11 socket exists and is accessible 2. Set environment variable correctly: @@ -471,6 +484,7 @@ This outputs check results in JSON format: 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) +6. See the [p11-kit documentation](https://p11-glue.github.io/p11-glue/p11-kit/manual/) for general PKCS#11 reference #### Cannot access a resource (wi-fi, VPN, web app)