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..abd1d887 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,19 +1,42 @@ --- -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 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 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. # 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](#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. + +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) + -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. +# Network Access -# System Requirements +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) @@ -22,26 +45,20 @@ 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 -# Quick Install +## Quick Install -On a system with `bash` and `curl`, run the following: +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 +211,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 +226,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 +242,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 +294,150 @@ 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 + +## 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 built-in `installer` command) + +## Registering the Agent + +Your agent needs to enroll with your team. +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)). + +## 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 + +## 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` + - Setup (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 Setup (exe) installer:** + ```powershell + step-agent-plugin-Setup_amd64_.exe /silent + ``` + +## 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. + +## 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..f675646a 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 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,7 +9,7 @@ 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. +To configure the connection, let's first set up an Application in Entra ID. Then, we'll add the client credentials to Smallstep. # Prerequisites @@ -93,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 b7eff7fb..0344bb52 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 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. @@ -87,10 +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: Install the agent via Jamf +- **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. + +### Install the agent via Jamf #### Create an Agent Package for Distribution @@ -260,46 +262,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 e2ef20e2..3b4d6c97 100644 --- a/tutorials/connect-workspace-one-to-smallstep.mdx +++ b/tutorials/connect-workspace-one-to-smallstep.mdx @@ -7,7 +7,7 @@ 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. +To configure the connection, let's first set up an Application in Entra ID. Then, we'll add the client credentials to Smallstep. # Prerequisites @@ -65,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”