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": [ diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index 7a080d0f..78560ad7 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -5,7 +5,7 @@ html_title: Integrate Fleet DM with Smallstep Tutorial description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates and syncing device inventory using Fleet's device management platform. --- -Smallstep can integrate with [Fleet DM](https://fleetdm.com/) to deploy certificates to your Fleet-managed devices. Fleet has a native Smallstep integration that makes it easy to configure Dynamic SCEP for certificate enrollment. +Smallstep can integrate with [Fleet DM](https://fleetdm.com/) to deploy certificates to your Fleet-managed devices. In this document, we will configure your Fleet instance for use with your Smallstep team. @@ -18,7 +18,7 @@ You will need: Client requirements: -- For SCEP certificate enrollment, devices must be MDM-enrolled in Fleet +- For enrollment, devices must be MDM-enrolled in Fleet - The Smallstep agent will need to reach the following domains: ``` smallstep.com @@ -33,13 +33,16 @@ Client requirements: Supported platforms: -- macOS, iOS, iPadOS (via `.mobileconfig` profiles) +- macOS — Smallstep agent and osquery extension for full device identity sync, with configuration provided through a `.mobileconfig` profile - Linux (via agent software deployment) - Windows Pro or Enterprise — Fleet does not yet support its native Smallstep CA type on Windows, so Windows enrollment goes through Smallstep's NDES-compatible endpoints, configured in Fleet as a Dynamic SCEP CA. -# Apple devices (macOS, iOS, iPadOS) +# macOS -This flow uses Fleet's native Smallstep CA integration. Devices receive a SCEP certificate via a `.mobileconfig` profile, and the Smallstep agent (on macOS) takes over from there. +macOS enrollment combines two pieces: + +- A `.mobileconfig` profile, generated by Smallstep and imported into Fleet, that bootstraps the Smallstep agent, which then takes over enrollment. +- The Smallstep osquery extension registers additional device identity information directly in Fleet, for a richer device inventory and seamless enrollment experience. ## Step 1. Get a Fleet API token @@ -92,204 +95,69 @@ The default role for API-only users is **Observer**, which grants read-only acce -## Step 2. Connect Fleet to Smallstep + +## Step 2. Create a Smallstep enrollment report in Fleet + +Create a Fleet report to collect the enrollment data. Smallstep reads this report during device sync to include additional device identity details alongside the standard Fleet device inventory. + +1. In Fleet, go to **Reports** +2. Ensure **All Fleets** is active. If not, the report won't apply to all your hosts. +3. Click **Add report** +4. Enter the following query: + + ```sql + SELECT * FROM smallstep_enrollment; + ``` +5. Click **Save**; a modal should appear +6. In the modal, enter the following details: + - A **Name** for the query, such as "Smallstep Enrollment" + - Optionally, a **Description** + - The **Interval** can be set to **Every hour**. While testing, a shorter interval is helpful + - Optionally, enable the **Observers can run** checkbox + - Enable **macOS** as **Target** + - Select **All hosts** +7. Click **Save** +8. Note the numeric ID of the Smallstep enrollment report that was just created + +## Step 3. Connect Fleet to Smallstep Now you'll add your Fleet API credentials to Smallstep. 1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) 2. Under Available Providers, find **Fleet** and click **Connect** 3. Fill in the fields: + - **Name/Alias**: An optional identifier for this connection (for example, `Production Fleet`) - **API Base URL**: Your Fleet server URL (for example, `https://fleet.example.com`) - **API Token**: Paste the API token from the previous step - - **Name/Alias**: An optional identifier for this connection (for example, `Production Fleet`) + - **Enrollment Query ID**: The numeric ID of the Fleet enrollment report from the previous step 4. Click **Connect MDM** 5. After connecting, temporarily save the following values: - - **SCEP URL** (for example, `https://your-team.scep.smallstep.com/p/agents/integration-fleet-abc123`) - - **SCEP Challenge URL** (for example, `https://your-team.scep.smallstep.com/webhook/abc123-def4-5678-9abc-def012345678/challenge`) - - **Challenge Username** - - **Challenge Password** - Under **Authority Certificates**, download the Root CA certificate. -Within a few minutes, you will see your Fleet devices in the [Devices](https://smallstep.com/app/?next=/devices/all) tab. Your Smallstep device inventory syncs from Fleet approximately every four hours. - -## Step 3. Add the Smallstep Certificate Authority in Fleet - -Now we'll add the Smallstep SCEP credentials to Fleet. +Within a few minutes, you will see your Fleet devices in the [Devices](https://smallstep.com/app/?next=/devices/all) tab. Your Smallstep device inventory syncs from Fleet approximately every eight hours. -1. In Fleet, go to **Settings** (click your profile icon in the top right) -2. Navigate to **Integrations → Certificate authorities** -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. - - **SCEP URL**: Paste the SCEP URL from Smallstep - - **Challenge URL**: Paste the SCEP Challenge URL from Smallstep - - **Username**: Paste the Challenge Username from Smallstep - - **Password**: Paste the Challenge Password from Smallstep -6. Click **Add CA** +## Step 4. Download the configuration profile -Fleet will test the CA connection after you create it. - - -
-If you plan to use GitOps instead of the Fleet UI, skip this step and see the [GitOps section below](#gitops-configure-fleet-with-fleetctl) for the YAML-based alternative. -
- +Fleet deploys certificates and configuration to devices using a configuration profile. You can download this from the Smallstep dashboard and upload it to Fleet. No need to build the payloads or paste certificate data by hand. -## 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 - - -``` +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`. -- 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 downloaded profile bundles everything required to enroll a device: your root and intermediate CA certificates, the Smallstep agent settings, and the Login Items entry for the agent. -## Step 5. Upload the configuration profile to Fleet +## Step 6. 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 -4. Scope the profile to the teams or labels containing your macOS, iOS, or iPadOS hosts +3. Upload the `fleet-.mobileconfig` file you downloaded in the previous step +4. Scope the profile to the teams or labels containing your macOS hosts -The profile will be deployed to devices at their next MDM check-in. Fleet automatically substitutes the `$FLEET_VAR_*` values per host. +The profile will be deployed to devices at their next MDM check-in. -## Step 6. Deploy the Smallstep agent (macOS) +## Step 7. Deploy the Smallstep agent -The macOS Smallstep agent picks up the bootstrap certificate from the keychain and uses it to register the device with Smallstep. +The macOS Smallstep agent picks up the configuration that Fleet deployed to the device, and uses it to register the device with Smallstep. Deploy the agent using Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) feature: @@ -299,20 +167,37 @@ Deploy the agent using Fleet's [software deployment](https://fleetdm.com/guides/ Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the agent. See the [Smallstep Agent manual installation guide](../platform/smallstep-agent.mdx#macos-installation) for detailed instructions. -iOS and iPadOS do not run the Smallstep agent — the SCEP certificate issued by the profile is the end of the flow on those platforms. +## Step 8. Deploy the osquery extension + +Smallstep provides an osquery extension that registers additional device identity information directly in Fleet. When Smallstep syncs your device inventory from Fleet, it reads this data to enable a seamless enrollment experience on macOS. + +1. Download the `step-agent-osquery` package for macOS from [Smallstep's releases](https://releases.smallstep.com). +1. In Fleet, go to **Software** +1. Click **Add software**. Ensure a fleet is selected; software is configured per-fleet +1. Select **Custom package** +1. Click **Choose file**, and select the `step-agent-osquery` package that was downloaded before +1. Enable **Deploy** +1. Click **Add software**. + +A modal should appear, showing the package upload progress. + +After upload, a Fleet policy is created that automatically triggers package installation if the package is not yet installed. + +See https://fleetdm.com/guides/deploying-custom-osquery-extensions-in-fleet-a-step-by-step-guide for additional guidance and some troubleshooting options when deploying osquery extensions. + +Alternatively, you can use a separate software management system such as [Munki](https://github.com/munki/munki) to deploy the osquery extension. -## Step 7. Confirmation (Apple) +## Step 9. Confirmation To confirm certificate deployment: -1. In the Fleet console, go to **Hosts** and select an Apple device that received the profile +1. In the Fleet console, go to **Hosts** and select a macOS device that received the profile 2. Check the **OS settings** status to verify the profile was applied successfully 3. In the Smallstep console, go to [**Devices**](https://smallstep.com/app/?next=/devices/all) and confirm the device is enrolled with a certificate On the device itself: -- **macOS**: Open **Keychain Access** and look for a certificate issued by your Smallstep authority -- **iOS / iPadOS**: Go to **Settings → General → VPN & Device Management** to view the installed profile +- Check the output of `/Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent status` # Linux @@ -599,7 +484,7 @@ fleet-gitops/ ├── teams/ │ └── team.yml └── lib/ - ├── smallstep-agent.mobileconfig + ├── fleet-.mobileconfig └── smallstep-agent-setup.sh ``` @@ -633,13 +518,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 5** of the macOS 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 @@ -695,15 +580,17 @@ Add the Smallstep enrollment query to your team YAML. Fleet will collect results ```yaml queries: - name: Smallstep enrollment - description: Collects Smallstep enrollment data including TPM EK for device identity sync + description: Collects Smallstep enrollment data for device identity sync query: SELECT * FROM smallstep_enrollment; interval: 3600 - platform: linux + platform: darwin,linux,windows automations_enabled: true logging: snapshot discard_data: false ``` +The `smallstep_enrollment` table is provided by the Smallstep osquery extension, which runs on macOS, Linux, and Windows. Restrict the `platform` list to the operating systems you deploy the extension to. + ## Apply the configuration Run `fleetctl gitops` to apply the configuration: diff --git a/tutorials/connect-jamf-pro-to-smallstep.mdx b/tutorials/connect-jamf-pro-to-smallstep.mdx index 13685432..da622033 100644 --- a/tutorials/connect-jamf-pro-to-smallstep.mdx +++ b/tutorials/connect-jamf-pro-to-smallstep.mdx @@ -131,73 +131,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, your root and intermediate CA certificates, the Smallstep agent settings, and the 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.