Connect JumpCloud to Smallstep

Smallstep can integrate with JumpCloud to synchronize your device inventory, and to enroll your Windows fleet with Smallstep using the Smallstep Agent. In this document, we will configure your JumpCloud tenant for use with your Smallstep team.

This document covers Windows only. macOS support through JumpCloud is not covered here yet.

This document also contains uninstall instructions.

You will need:

• A Smallstep team
• A JumpCloud tenant
• Windows devices enrolled in JumpCloud MDM. The SCEP policy is delivered over Windows MDM, so a device that only runs the JumpCloud agent will not receive it.

Client requirements:

• Windows 10 or later. Windows Home editions are not supported.
• A TPM 2.0. Smallstep identifies a Windows device by its TPM endorsement key.
• The agent will need to reach the following domains:

  smallstep.com
  api.smallstep.com
  gateway.smallstep.com
  control.infra.smallstep.com
  *.[team-name].ca.smallstep.com
  auth.smallstep.com
  att.smallstep.com
  tel.smallstep.com
  

Limitations:

• JumpCloud supports static SCEP only; its SCEP policy will not work with a dynamic challenge. This limitation relates only to the Smallstep provisional enrollment certificate for each device. Once the Smallstep Agent is enrolled, all credentials are hardware-bound and attested.
• Because the challenge is static, every device in the assigned scope presents the same SCEP secret. Scope the policy to the device group you intend to enroll, and rotate the connection if the secret is exposed.
• Within a SCEP policy, JumpCloud only substitutes device variables in the Subject Name field, so the device identifier is carried in the certificate's common name rather than in a subject alternative name. (JumpCloud Commands have their own, separate set of variables, which the agent configuration step below uses.)

This API key allows Smallstep to read your JumpCloud device inventory for ongoing inventory syncing, and to read the user bound to each device so that devices arrive in Smallstep already associated with a person.

1. In the JumpCloud Admin Portal, open your account menu at the bottom left of the navigation sidebar (your name) and choose My API Key
2. Choose Generate New API Key
3. Copy the key and save it temporarily — you'll use it in the next step

Let's add the JumpCloud credentials to Smallstep.

1. In the Smallstep console, go to the Device Management tab in ⚙️ Settings
2. Under JumpCloud, choose ➕ Connect
3. Enter the following:
   • Name/Alias: A label for this connection, e.g. JumpCloud. This is the name the connection is shown under in Smallstep
   • API Key: The key you created in the previous step
   • JumpCloud API URL: Leave blank unless you use a non-default console URL
   • Organization ID: Only required for multi-tenant (MSP) JumpCloud accounts
4. Choose Connect MDM. Your device inventory will start syncing from JumpCloud to Smallstep. You can check the Logs tab for sync status, and confirm that JumpCloud is syncing by checking the Devices list.

Your Smallstep team is now linked to JumpCloud. Smallstep will do a partial sync of your device inventory every hour, and a full sync every 8 hours.

You need four things from Smallstep: a SCEP URL, a SCEP challenge, the CA certificates, and the CA's SHA-1 fingerprint. The first two come from the JumpCloud connection page; the last two come from the authority page.

SCEP URL and SCEP challenge

1. In the Smallstep console, go to Device Management in ⚙️ Settings
2. Choose Manage on your JumpCloud connection, then open the Settings tab
3. Copy the SCEP URL (for example, https://your-team.scep.smallstep.com/p/agents/integration-jumpcloud-abc123) and the SCEP Challenge — reveal the challenge with the 👁 button and copy it. It is a 32-character hexadecimal string

CA certificates and fingerprint

1. In the Smallstep console, go to Certificate Manager > Authorities
2. Under Hosted Authorities, choose View details on the Smallstep (<team-name>) Agents authority
3. In Authority Settings:
   • Download the Root Certificate and the Intermediate Certificate
   • Next to Intermediate Fingerprint, change the hash dropdown from sha256 to sha1, then copy the value

The fingerprint is already an unbroken lowercase hexadecimal string, which is the format JumpCloud expects. Keep these values handy — you'll need them below.

The device must trust the Smallstep Agents CA before it will accept a certificate from it.

1. In JumpCloud, go to Device Management > Policy Management
2. Choose Add New > Device Policy, select the Windows tab, and search for Certificate
3. Choose Configure on the Install Certificate policy, and configure it for the Root certificate you downloaded, with the destination store set to Root
4. Repeat for the Intermediate certificate

1. In JumpCloud, go to Device Management > Policy Management
2. Choose Add New > Device Policy
3. Select the Windows tab, search for SCEP, and choose Configure on SCEP Profiles
4. Give the policy a name (e.g., Smallstep)
5. Configure the settings:
   • CA ThumbPrint: The SHA-1 Intermediate Fingerprint you copied above
   • Challenge: The SCEP Challenge from Smallstep
   • Key Length: 2048 — JumpCloud defaults to 1024, which Smallstep rejects
   • Subject Name: CN=%JumpCloudSystemID%
   • Server URL: The SCEP URL from Smallstep
   • Renew Period: A value shorter than the certificate lifetime, e.g. 21
   • Enable Include Client Authentication EKU
   • Leave Subject Alternative Names empty
6. Under Device Groups or Devices, scope the policy to the Windows devices you want to enroll
7. Choose Create Policy

A note on the Subject: JumpCloud replaces %JumpCloudSystemID% with the device's JumpCloud system ID, and Smallstep uses that ID to identify which device is asking for a certificate. It must be the entire common name, with nothing else in it.

There are two ways to install the agent:

• via JumpCloud (below): Use JumpCloud's Software Management or Commands
• separately: Use a separate software management tool, or install the agent manually. See the Smallstep Agent Manual Installation guide for detailed Windows installation instructions.

1. Download the installer from releases.smallstep.com: choose Smallstep Agent, then Windows, and from the Stable column download step-agent_<version>_amd64.msi (or step-agent_<version>_arm64.msi for ARM devices)
2. In JumpCloud, go to Device Management > Software Management, and select the Windows tab
3. Choose ➕ Add New > JumpCloud Private Repo
4. Upload the .msi file and assign it to the same device group you scoped the SCEP policy to

Alternatively, run a JumpCloud Command that installs the agent with Winget. Create it the same way as the configuration command below — ➕ Command > Command, with Type set to Windows:

winget install --exact --id Smallstep.step-agent --silent --accept-package-agreements --accept-source-agreements

The Smallstep Agent reads its configuration from the registry. Deploy it with a JumpCloud Command.

First, collect two values from the Smallstep console:

• Your team slug. It is the path segment after /app/ in the console URL — for a team at https://smallstep.com/app/acme-corp, the slug is acme-corp.
• Your Agents intermediate CA issuer name. In your Authority list, copy the Authority Name of the Smallstep (<team-name>) Agents authority, then append Intermediate CA to it. The result looks like Smallstep (<team-name>) Agents Intermediate CA. (This is the subject common name of the intermediate certificate you downloaded earlier, so you can also read it out of that file.) If your team was created before October, 2024, your issuer CA may have a common name without the team name (Smallstep Agents Intermediate CA).

Then create the command:

1. In JumpCloud, go to Device Management > Commands
2. Choose ➕ Command, and pick Command from the menu — not Command From Template or Command After Agent Install
3. Under Type, select Windows. The type defaults to Linux, and selecting Windows checks Windows PowerShell, so the script below runs in PowerShell
4. Paste the script below, replacing YOUR-TEAM-SLUG and YOUR-AGENTS-INTERMEDIATE-CA
5. Under Details, set Command Name to something recognizable, e.g. Configure Smallstep Agent
6. Set Event to Run as Repeating, so devices that enroll later are configured without another manual run
7. Choose Save, then use the Device Groups or Devices tab to scope the command to the same devices as the SCEP policy

$teamSlug = 'YOUR-TEAM-SLUG'
$issuer   = 'YOUR-AGENTS-INTERMEDIATE-CA'

# JumpCloud substitutes {{device.id}} with this device's JumpCloud system ID,
# which is the same value the SCEP policy puts in the certificate's common
# name. That is how the agent finds its own certificate.
$deviceId = '{{device.id}}'

New-Item -Path 'HKLM:\Software\Policies\Smallstep' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\Software\Policies\Smallstep' -Name 'TeamSlug' -Value $teamSlug
Set-ItemProperty -Path 'HKLM:\Software\Policies\Smallstep' -Name 'Certificate' `
  -Value "capi:store-location=machine;store=My;issuer=$issuer;cn=$deviceId"

Restart-Service -Name 'Smallstep Agent' -ErrorAction SilentlyContinue

The agent waits for this configuration, so it does not matter whether the command runs before or after the agent is installed.

To confirm the agent is installed and running:

• In the Smallstep console, 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: sc query "Smallstep Agent"
• Confirm the SCEP certificate arrived: Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like '*Agents Intermediate CA*' }

By default, devices synced from JumpCloud are approved automatically, and become high assurance once the agent has attested the device's TPM and the device is bound to a user. You can change approval behavior in Team Settings.

1. In JumpCloud, remove the SCEP policy, the certificate policies, and the configuration command from the assigned device groups
2. Remove the Smallstep Agent software assignment
3. To remove the agent from devices that already have it, run a JumpCloud Command:

& cmd /c "$(((Get-ItemProperty HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\* | Where-Object { $_.DisplayName -like "*Smallstep Agent*" }).UninstallString -replace '/I', '/X')) /quiet"
Remove-Item -Path 'HKLM:\Software\Policies\Smallstep' -Recurse -Force -ErrorAction SilentlyContinue