diff --git a/manifest.json b/manifest.json index 47e9b1a8..fb78171b 100644 --- a/manifest.json +++ b/manifest.json @@ -70,9 +70,13 @@ "path": "/platform/smallstep-app.mdx" }, { - "title": "Deploy to Linux", + "title": "Deploy the Agent", "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/enrollment-guide.mdx b/platform/enrollment-guide.mdx index 65de2b81..1d10724d 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,27 @@ 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 - -For each device, use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a 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.). -Devices are automatically approved when added via API. +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, -you'll see devices in the Smallstep console, +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 +``` + +You'll also see new devices in the Smallstep console, under [Devices](https://smallstep.com/app/?next=/devices). diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index c89047b8..0ec62ffd 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,19 +1,43 @@ --- -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: 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. --- -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. + + +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 + +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` -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. +# Linux Installation -# System Requirements +## System Requirements - Supported operating systems: - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc) @@ -22,26 +46,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 +212,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 +227,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 +243,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 +295,163 @@ 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. 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 + ``` + +2. 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. 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: + + ```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` + +2. Install the agent silently: + + ```powershell + msiexec.exe /i "path\to\step-agent-plugin_amd64.msi" /quiet + ``` + +## 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 + +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 +``` + +Alternatively, uninstall via the Windows "Add or Remove Programs" settings. + 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. diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx index cb785bab..e7b5ad07 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. +updated_at: January 05, 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. +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..f7319ce1 --- /dev/null +++ b/platform/troubleshooting-agent.mdx @@ -0,0 +1,371 @@ +--- +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. +--- + +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:** +```bash +step-agent-plugin doctor +``` + +**On Windows:** +```powershell +& 'C:\Program Files\Smallstep\SmallstepApp\smallstep-agent.exe' 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. diff --git a/tutorials/connect-intune-to-smallstep.mdx b/tutorials/connect-intune-to-smallstep.mdx index d1f5a178..27bd76cd 100644 --- a/tutorials/connect-intune-to-smallstep.mdx +++ b/tutorials/connect-intune-to-smallstep.mdx @@ -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 e51c43f9..a81d6810 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”