Skip to content

docs: correct the JumpCloud tutorial against the live consoles - #554

Merged
joshdrake merged 3 commits into
mainfrom
docs/jumpcloud-fixes
Sep 5, 2026
Merged

docs: correct the JumpCloud tutorial against the live consoles#554
joshdrake merged 3 commits into
mainfrom
docs/jumpcloud-fixes

Conversation

@joshdrake

Copy link
Copy Markdown
Contributor

Walked both consoles — the JumpCloud Admin Portal and the Smallstep
console — and fixed every step that did not match what an operator
actually sees.

JumpCloud console

Doc said Actually
account menu "in the top right" bottom left of the sidebar (your name)
"Windows Install Certificate" policy Install Certificate
Software Management → "Private Repository" Add NewJumpCloud Private Repo
"Choose New Command" Command opens a three-option menu; pick the plain Command
"select Windows as the type" Type defaults to Linux; selecting Windows auto-checks Windows PowerShell
Command Name is required and was never mentioned; suggest Configure Smallstep Agent
"Set the Launch Event" the field is Event

Smallstep console

  • The connection form takes a Name/Alias. Undocumented.
  • The SHA-1 fingerprint is in the console. The doc claimed it "is not
    shown" and had the reader compute it with step or openssl and strip
    colons. The authority page has an Intermediate Fingerprint row with
    a sha256 / sha1 / md5 dropdown and a copy button; the value is
    already unbroken lowercase hex. Removed the CLI commands and the
    colon-stripping step.
    (The step command was also wrong — --sha1 requires --insecure.)
  • Say plainly that CA ThumbPrint wants the intermediate, even
    though JumpCloud's tooltip calls it a root thumbprint. Verified against
    a working policy.
  • The console has no "Intermediate CA common name" field to read. The
    issuer name is the Authority Name plus Intermediate CA.
  • Restored the pre-October-2024 caveat that the Intune and Workspace ONE
    docs both carry, and linked the Authority list as every other tutorial
    does.
  • The SCEP challenge is masked — reveal it, and it is 32 hex characters.
    Worth stating, so nobody copies the UUID that also appears on that page.
  • Take the team slug from the console URL. (Settings → Team Settings did
    not finish loading on the tenant I checked; the URL is more robust
    anyway.)

Agent install and configuration

  • Windows MSI now comes from
    releases.smallstep.com, per request.
    Worth flagging in review: every other tutorial links
    packages.smallstep.com/.../step-agent_amd64_latest.msi, so this is
    now the only one pointing elsewhere. There is a reason — JumpCloud
    Private Repo takes a specific versioned file, which a _latest URL
    does not give you — but it is a deliberate divergence.
  • Replaced 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. Much
    shorter, and no dependency on the agent config file's location or
    shape. Quoted, so PowerShell does not try to execute the substituted id.

Conventions

  • "Smallstep UI" → "Smallstep console" (error-level vale Branding rule;
    would have failed CI).
  • Added JumpCloud to the vale vocabulary.
  • Borrowed the wireless tutorial's stronger wording for the intermediate
    going into the Root store — it names the consequence.

Related

  • smallstep/web#3054 adds the SCEP panel this doc now tells readers to
    copy the URL and challenge from.
  • smallstep/inventory#598 adds the Name/Alias field.

Vale is not installed locally, so the substitution list was checked by
hand rather than run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YYBwHCnG1u3JziQVuZgKY5

joshdrake and others added 3 commits September 4, 2026 17:35
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YYBwHCnG1u3JziQVuZgKY5
The connection page shows the challenge masked, and the value is a
32-character hex string — not the UUID that also appears on that page.
Say so, so an operator does not copy the wrong one. Show the SCEP URL in
the form the console actually renders for JumpCloud.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YYBwHCnG1u3JziQVuZgKY5
Cross-checked against the Intune, Workspace ONE, Iru, Mosyle and
wireless tutorials:

- "Smallstep UI" violates the error-level Branding vale rule, which
  swaps it for "Smallstep console". Two occurrences.
- Add JumpCloud to the vale vocabulary, beside Jamf and Mosyle.
- Both other capi: docs carry a pre-October-2024 caveat: teams created
  before then may have an issuer CA with no team name in it. It was
  missing here.
- Link the Authority list, as every other tutorial does, and name the
  "Hosted Authorities" section — linked authorities have no fingerprint
  dropdown.
- Borrow the wireless tutorial's stronger wording for the intermediate
  going into the Root store: it names the consequence, which is what
  makes the warning stick.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YYBwHCnG1u3JziQVuZgKY5
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@joshdrake
joshdrake marked this pull request as ready for review September 4, 2026 23:16
@joshdrake
joshdrake requested a review from a team as a code owner September 4, 2026 23:16
@joshdrake
joshdrake merged commit edc1dcd into main Sep 5, 2026
3 of 4 checks passed
@joshdrake
joshdrake deleted the docs/jumpcloud-fixes branch September 5, 2026 00:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants