From c6e663671d5b8f42749e2071bd0231b1795f8180 Mon Sep 17 00:00:00 2001 From: Josh Drake Date: Fri, 4 Sep 2026 17:35:02 -0500 Subject: [PATCH 1/3] docs: correct JumpCloud tutorial against the live consoles Walked the JumpCloud Admin Portal and the Smallstep console and fixed every step that did not match what an operator actually sees. JumpCloud console: - the account menu holding "My API Key" is at the bottom left of the navigation sidebar, not the top right - the certificate policy is named "Install Certificate", not "Windows Install Certificate" - Software Management > Add New offers "JumpCloud Private Repo", not "Private Repository" - the Commands page's "+ Command" button opens a three-option menu; say to pick the plain "Command", and that Type defaults to Linux - name the required "Command Name" field and suggest "Configure Smallstep Agent" - the launch field is labelled "Event", not "Launch Event" - note that Windows commands run as PowerShell Smallstep console: - the connection form takes a Name/Alias; it was undocumented - the Agents authority page exposes the SHA-1 fingerprint directly: switch the Intermediate Fingerprint dropdown from sha256 to sha1. Drop the step/openssl computation and the colon-stripping step. - state that JumpCloud's "CA ThumbPrint" needs the intermediate fingerprint even though its own tooltip says "root CA thumbprint" (verified against a working policy) - the intermediate issuer name is the authority name plus " Intermediate CA"; the console has no "Intermediate CA common name" field to read - take the team slug from the console URL Agent install and configuration: - get the Windows MSI from releases.smallstep.com - replace the jcagent.conf JSON parsing with JumpCloud's built-in {{device.id}} command variable, which resolves to the same system ID that %JumpCloudSystemID% resolves to in the SCEP subject Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01YYBwHCnG1u3JziQVuZgKY5 --- tutorials/connect-jumpcloud-to-smallstep.mdx | 94 ++++++++++---------- 1 file changed, 48 insertions(+), 46 deletions(-) diff --git a/tutorials/connect-jumpcloud-to-smallstep.mdx b/tutorials/connect-jumpcloud-to-smallstep.mdx index b0785eda..5353f3b1 100644 --- a/tutorials/connect-jumpcloud-to-smallstep.mdx +++ b/tutorials/connect-jumpcloud-to-smallstep.mdx @@ -39,7 +39,7 @@ 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. -- JumpCloud only substitutes device variables in the SCEP **Subject Name** field, so the device identifier is carried in the certificate's common name rather than in a subject alternative name. +- 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.) ## Step-by-step instructions @@ -51,7 +51,7 @@ We recommend creating a dedicated JumpCloud API key for the Smallstep integratio 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 in the top right and choose **My API Key** +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 @@ -65,7 +65,8 @@ Let's add the JumpCloud credentials to Smallstep. 1. In the Smallstep UI, go to the [**Device Management**](https://smallstep.com/app/?next=/settings/devices) tab in ⚙️ **Settings** 2. Under JumpCloud, choose ➕ **Connect** -3. Enter the following credentials: +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 @@ -77,30 +78,27 @@ Your Smallstep team is now linked to JumpCloud. Smallstep will do a partial sync ### Get Smallstep CA Details -After connecting JumpCloud to Smallstep, you'll find the certificate details you need on the Platform Settings page: +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. -1. In the Smallstep console, go to [**Device Management**](https://smallstep.com/app/?next=/settings/devices) in **Settings** -2. Click on your JumpCloud connection -3. From this page, you can: - - Copy the **SCEP URL** (for example, `https://agents.example.ca.smallstep.com/scep/integration-jumpcloud-abc123`) - - Copy the **SCEP Challenge** value - - Download the **Root Certificate** and the **Intermediate Certificate** - -Keep this page open or save these values temporarily — you'll need them below. +**SCEP URL and SCEP challenge** -JumpCloud's SCEP policy identifies the CA by **SHA-1 thumbprint**, which is not shown in the Smallstep console. Compute it from the intermediate certificate you downloaded: +1. In the Smallstep console, go to [**Device Management**](https://smallstep.com/app/?next=/settings/devices) in ⚙️ **Settings** +2. Choose **Manage** on your JumpCloud connection, then open the **Settings** tab +3. Copy the **SCEP URL** (for example, `https://agents.example.ca.smallstep.com/scep/integration-jumpcloud-abc123`) and the **SCEP Challenge** -```bash -step certificate fingerprint --format hex --sha1 intermediate.crt -``` +**CA certificates and fingerprint** -Or, without the `step` CLI: +1. In the Smallstep console, go to **Certificate Manager** > **Authorities** +2. Choose **View details** on the **Smallstep (your-team) 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 -```bash -openssl x509 -in intermediate.crt -noout -fingerprint -sha1 -``` +The fingerprint is already an unbroken lowercase hexadecimal string, which is the format JumpCloud expects. Keep these values handy — you'll need them below. -Remove the colons from the result — JumpCloud expects an unbroken hexadecimal string. + ### Trust the Smallstep CA on your devices @@ -108,7 +106,7 @@ The device must trust the Smallstep Agents CA before it will accept a certificat 1. In JumpCloud, go to **Device Management** > **Policy Management** 2. Choose **Add New** > **Device Policy**, select the **Windows** tab, and search for `Certificate` -3. Configure a **Windows Install Certificate** policy for the **Root** certificate you downloaded, with the destination store set to **Root** +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