From 0c73f66d9a5074e40901f3fae2a42d6797fccf95 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 12 Nov 2025 20:37:06 +0100 Subject: [PATCH 1/4] 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 2/4] 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 3/4] 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 4/4] 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.