From 0a0e48c2300013d456fa69947520e78d2173e87c Mon Sep 17 00:00:00 2001 From: Joe Wagstaff Date: Mon, 15 Jun 2026 11:12:07 -0400 Subject: [PATCH 1/2] update fleet and jamf mdm docs --- tutorials/connect-fleet-dm-to-smallstep.mdx | 164 +++----------------- tutorials/connect-jamf-pro-to-smallstep.mdx | 79 ++-------- 2 files changed, 32 insertions(+), 211 deletions(-) diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index cb7ac66b..29b01079 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -120,7 +120,7 @@ Now we'll add the Smallstep SCEP credentials to Fleet. 3. Click **Add CA** 4. From the dropdown, select **Smallstep** 5. Fill in the fields: - - **Name**: A unique identifier using letters, numbers, and underscores only (for example, `SMALLSTEP_AGENT`). Fleet will create configuration profile variables with this name as a suffix. + - **Name**: Enter `SMALLSTEP_AGENT`. Fleet creates configuration profile variables with this name as a suffix, and the configuration profile you download from Smallstep in the next step references the `SMALLSTEP_AGENT` suffix. If you choose a different name here, you must edit the downloaded profile to match. - **SCEP URL**: Paste the SCEP URL from Smallstep - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep - **Username**: Paste the Challenge Username from Smallstep @@ -135,153 +135,27 @@ If you plan to use GitOps instead of the Fleet UI, skip this step and see the [G -## Step 4. Create SCEP configuration profiles - -Fleet deploys certificates to devices using configuration profiles. You'll need to create profiles that include the SCEP payload with Fleet's dynamic variables. - -For macOS, iOS, and iPadOS, Fleet provides these variables for Smallstep certificate enrollment: - -| Variable | Description | -|----------|-------------| -| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_SMALLSTEP_AGENT` | The dynamic SCEP challenge string | -| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_SMALLSTEP_AGENT` | The SCEP proxy URL for certificate requests | -| `$FLEET_VAR_SCEP_RENEWAL_ID` | A unique renewal identifier for the device | -| `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` | The end user's email from the identity provider | - -If you used a different name when adding the CA in Fleet, replace `SMALLSTEP_AGENT` accordingly. - -### SCEP profile (`smallstep-agent.mobileconfig`) - -Create a file called `smallstep-agent.mobileconfig` with the following structure. - -This profile contains three payloads: - -1. **SCEP payload**: Issues a provisional SCEP certificate that the Smallstep agent uses for bootstrapping into a Device Attested environment -2. **Root CA trust payload**: Installs the Smallstep Agent Root CA so the agent can validate its certificate chain. - To create this payload, open the downloaded `.pem` file in a text editor and copy the Base64-encoded certificate contents (everything between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, not including those lines) - You will paste this value inside the `` field of the Root CA trust payload below. -3. **Agent Configuration**: A configuration payload for the Smallstep Agent that includes your Smallstep team slug. - -```xml - - - - - PayloadContent - - - - PayloadDisplayName - Smallstep SCEP - PayloadIdentifier - com.smallstep.scep - PayloadType - com.apple.security.scep - PayloadUUID - C15F6CB6-473E-4B66-9B5B-A7B01C07152F - PayloadVersion - 1 - PayloadContent - - Challenge - $FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_SMALLSTEP_AGENT - Key Type - RSA - Key Usage - 5 - Keysize - 2048 - Subject - - - - CN - step-agent-bootstrap - - - - - OU - $FLEET_VAR_SCEP_RENEWAL_ID - - - - URL - $FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_SMALLSTEP_AGENT - - - - - PayloadDisplayName - Smallstep Agent Root CA - PayloadIdentifier - com.smallstep.root-ca - PayloadType - com.apple.security.pem - PayloadUUID - CCE7C356-A5DB-4796-86B5-E8DFAEA7F08E - PayloadVersion - 1 - PayloadContent - - - - - - - PayloadContent - - - PayloadType - com.smallstep.Agent - PayloadVersion - 1 - PayloadIdentifier - com.smallstep.Agent.settings - PayloadUUID - EBEA31C0-C9A4-4862-A939-E16DA63DE35B - PayloadDisplayName - Smallstep Agent Settings - TeamSlug - - Certificate - mackms:label=step-agent-bootstrap;se=false;tag= - - - PayloadDisplayName - Smallstep Agent - PayloadIdentifier - com.smallstep.Agent - PayloadType - Configuration - PayloadUUID - 18F9A37B-AEDB-4D9E-808F-F946ACBF3A46 - PayloadVersion - 1 - - - PayloadDisplayName - Smallstep Certificate - PayloadIdentifier - com.smallstep.certificate-profile - PayloadType - Configuration - PayloadUUID - AD981C97-F3F4-41D8-996A-9DE254012810 - PayloadVersion - 1 - - -``` +## Step 4. Download the configuration profile + +Fleet deploys certificates to devices using a configuration profile. Smallstep generates this profile for your Fleet connection, so you can download it from the Smallstep dashboard and upload it to Fleet. There's no need to build the payloads or paste certificate data by hand. + +1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) +2. Open your Fleet connection, then choose the **Settings** tab +3. Under **Configuration Profile (macOS only)**, click **Download** to save the profile. The downloaded file is named `fleet-.mobileconfig`. + +The downloaded profile bundles everything required to enroll a device: the SCEP payload, the root and intermediate CA trust certificates (pre-filled), the agent's managed settings (including your Smallstep team slug), and the Managed Login Items entry for the agent. Its SCEP URL and challenge are embedded as Fleet's `$FLEET_VAR_*` placeholders; Fleet substitutes them per host at deploy time using the certificate authority you added in Step 3, so that CA must be in place and named `SMALLSTEP_AGENT`. -- If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. -- Replace the `` value with your Smallstep team slug + +
+The dashboard labels this **macOS only** because the agent-specific payloads (managed settings and Managed Login Items) apply only to macOS. The SCEP and CA trust payloads still apply to iOS and iPadOS, so you can scope this same profile to your iOS and iPadOS hosts — the macOS-only payloads are simply ignored there. On iOS and iPadOS, the SCEP certificate issued by this profile is the end of the flow, since those platforms do not run the Smallstep agent. +
+ ## Step 5. Upload the configuration profile to Fleet 1. In the Fleet console, go to **Controls → OS settings → Configuration profiles** 2. Click **Add profile** -3. Upload your `smallstep-agent.mobileconfig` file +3. Upload the `fleet-.mobileconfig` file you downloaded in the previous step 4. Scope the profile to the teams or labels containing your macOS, iOS, or iPadOS hosts The profile will be deployed to devices at their next MDM check-in. Fleet automatically substitutes the `$FLEET_VAR_*` values per host. @@ -598,7 +472,7 @@ fleet-gitops/ ├── teams/ │ └── team.yml └── lib/ - ├── smallstep-agent.mobileconfig + ├── fleet-.mobileconfig └── smallstep-agent-setup.sh ``` @@ -632,13 +506,13 @@ export SMALLSTEP_CHALLENGE_PASSWORD='your-challenge-password' ## Add configuration profiles -In your team YAML file, reference the profile files: +Download the configuration profile for your Fleet connection from the Smallstep dashboard, as described in **Step 4** of the Apple section above, and place the `fleet-.mobileconfig` file in your `lib/` directory. Then reference it from your team YAML file: ```yaml controls: macos_settings: custom_settings: - - path: ../lib/smallstep-agent.mobileconfig + - path: ../lib/fleet-.mobileconfig ``` ## Add the Smallstep agent software diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index 4caba7ee..204fa908 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/tutorials/connect-jamf-pro-to-smallstep.mdx @@ -130,73 +130,20 @@ Next, we’ll configure the Script we just created to run on your client devices #### Configure an agent enrollment profile -In this step, we’ll tie everything together by creating a managed policy to enroll devices using the Smallstep Agent. - -1. In the Smallstep console, choose **Certificate Manager** - 1. Select [Authorities](https://smallstep.com/app/?next=/cm/authorities) - 2. Select the **Smallstep Agents** authority - 3. Download the Root Certificate - 4. Under the Provisioners section of the page, choose the provisioner beginning with **`integration-jamf`** - 5. Temporarily save the **URL shown on the page, eg.** `https://agents.example.ca.smallstep.com/scep/integration-jamf-b967f507` -2. In the Smallstep console, choose ⚙️ **Settings** - 1. Temporarily save the **Team Slug** value -3. In Jamf Pro, choose 🖥️ **Computers** -4. Under the **Content Management** tab, Choose **Configuration Profiles** -5. Add a new Configuration Profile - 1. Choose **Options → General** - - Name: Smallstep - 2. Add a [**Managed Login Items** payload](https://support.apple.com/guide/deployment/managed-login-items-payload-settings-dep07b92494/web) - - Rule type: **Bundle Identifier** - - Rule value: `com.smallstep.Agent` - 3. Add a [**Certificate payload**](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web) - - Certificate Name: **Smallstep Agents Authority** - - Certificate Option: **Upload** - - Certificate Upload: (upload the Root certificate you downloaded earlier) - - Allow all apps access: ☑️ - 4. Add a [**SCEP payload**](https://support.apple.com/guide/deployment/scep-payload-settings-dep495a6d79/web) - - URL: (paste the provisioner URL you saved earlier) - - Name: Smallstep - - Redistribute Profile: 7 days - - Challenge Type: Dynamic - - Key Size: 2048 - - Allow all apps access: ☑️ - 5. Select Options → Application & Custom Settings → External Applications - - Add new custom settings: - - - Options → External Applications → Source: Custom Schema - - Options → External Applications → Preference Domain: `com.smallstep.Agent` - - Options → External Applications → Custom Schema - 1. Choose Add Schema - 2. Copy the following JSON in to the window and choose Save - - ```json - { - "title": "Smallstep Agent (com.smallstep.agent)", - "description": "Configure settings for the Smallstep Agent.", - "properties": { - "TeamSlug": { - "type": "string", - "title": "Smallstep Details: Team", - "description": "The slug for your organization's Smallstep team, available in the Smallstep console under Settings.", - "property_order": 10 - }, - "Certificate": { - "type": "string", - "title": "Smallstep (Debug): Certificate URI", - "description": "A KMS URI that points to a certificate that can be used for agent bootstrapping.", - "property_order": 10 - } - } - } - ``` +In this step, we’ll tie everything together by deploying a configuration profile that enrolls devices using the Smallstep Agent. Smallstep generates this profile for your Jamf connection, so you can download it from the Smallstep dashboard and upload it directly to Jamf Pro. There’s no need to build the payloads by hand. + +The downloaded profile bundles everything required to enroll a device: the SCEP payload (with your provisioner URL pre-filled), the root and intermediate CA certificates, the agent’s managed settings (including your Team Slug), and the Managed Login Items entry for the agent. The SCEP payload relies on the dynamic challenge served by the SCEP enrollment webhook you configured earlier, so that webhook must be in place for enrollment to succeed. - - Options → External Applications → Custom Schema → Smallstep Details: Team: (paste the Team Slug you saved earlier) - - Options → External Applications → Custom Schema → Smallstep Details: Certificate URI: `mackms:label=$PROFILE_IDENTIFIER;se=false;tag=` - 1. Finally, set the profile scope: - 1. Choose Edit - 2. Set the desired scope. This should mirror the scope you chose when creating the Policy in step 5. - 3. Choose Save +1. In the Smallstep UI, go to the [**Device Management**](https://smallstep.com/app/?next=/settings/devices) tab in ⛭ **Settings** +2. Open your Jamf connection, then choose the **Settings** tab +3. Under **Configuration Profile (macOS only)**, choose **Download** to save the profile. The downloaded file is named `jamf-.mobileconfig`. +4. In Jamf Pro, choose 💻 **Computers** +5. Under the **Content Management** tab, choose **Configuration Profiles** +6. Choose **Upload**, then upload the `.mobileconfig` file you downloaded +7. Set the profile scope: + 1. Choose the **Scope** tab, then choose **Edit** + 2. Set the desired scope. This should mirror the scope you chose when creating the agent installation policy earlier. + 3. Choose **Save** The devices that you scoped will receive a certificate and have the agent installed and running. From a51a7e117aaa5a70d375ba883d4d1f9526841ad5 Mon Sep 17 00:00:00 2001 From: Joe Wagstaff Date: Mon, 15 Jun 2026 11:24:51 -0400 Subject: [PATCH 2/2] allow-list jamf.com in markdown-link-check config --- .github/mdl.config.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/mdl.config.json b/.github/mdl.config.json index 001dc72c..ccb2b99d 100644 --- a/.github/mdl.config.json +++ b/.github/mdl.config.json @@ -71,6 +71,9 @@ }, { "pattern": "^https://datatracker.ietf.org" + }, + { + "pattern": "^https://.*jamf.com" } ], "replacementPatterns": [