diff --git a/tutorials/connect-fleet-dm-to-smallstep.mdx b/tutorials/connect-fleet-dm-to-smallstep.mdx index fbb1c559..aacba8d6 100644 --- a/tutorials/connect-fleet-dm-to-smallstep.mdx +++ b/tutorials/connect-fleet-dm-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: February 05, 2026 +updated_at: May 21, 2026 title: Connect Fleet DM to Smallstep 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. @@ -33,8 +33,12 @@ Client requirements: Supported platforms: - macOS, iOS, iPadOS (via `.mobileconfig` profiles) -- Windows (via `.xml` SyncML profiles) - 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) + +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. ## Step 1. Get a Fleet API token @@ -135,7 +139,7 @@ If you plan to use GitOps instead of the Fleet UI, skip this step and see the [G Fleet deploys certificates to devices using configuration profiles. You'll need to create profiles that include the SCEP payload with Fleet's dynamic variables. -Fleet provides these variables for Smallstep certificate enrollment: +For macOS, iOS, and iPadOS, Fleet provides these variables for Smallstep certificate enrollment: | Variable | Description | |----------|-------------| @@ -146,7 +150,7 @@ Fleet provides these variables for Smallstep certificate enrollment: If you used a different name when adding the CA in Fleet, replace `SMALLSTEP_AGENT` accordingly. -### macOS/iOS SCEP profile (`smallstep-agent.mobileconfig`) +### SCEP profile (`smallstep-agent.mobileconfig`) Create a file called `smallstep-agent.mobileconfig` with the following structure. @@ -273,15 +277,183 @@ This profile contains three payloads: - 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 -### Windows SCEP profile (`smallstep-scep.xml`) +## 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 +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. + +## Step 6. Deploy the Smallstep agent (macOS) + +The macOS Smallstep agent picks up the bootstrap certificate from the keychain 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: + +1. Download the latest macOS package: [step-agent_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg) ([all versions](https://releases.smallstep.com)) +2. In Fleet, go to **Software**, choose **Custom Package**, and add the package +3. Scope the software install to your macOS hosts + +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 7. Confirmation (Apple) + +To confirm certificate deployment: + +1. In the Fleet console, go to **Hosts** and select an Apple 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 + +# Linux + +Linux does not support MDM configuration profiles, so the SCEP flow used for Apple and Windows devices does not apply. Instead, the Smallstep agent on Linux registers directly with your Smallstep team using TPM attestation. There is no certificate authority to configure in Fleet — you only need to deploy and configure the agent. + +## Step 1. Deploy the Smallstep agent + +You'll add a Linux agent package to Fleet and attach a post-install script that writes the agent configuration and starts the service. + +Pick the packages for your Linux distributions and architectures: + +- Debian/Ubuntu x64: [step-agent_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb) +- Debian/Ubuntu ARM64: [step-agent_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb) +- RHEL/Fedora x64: [step-agent_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm) +- RHEL/Fedora ARM64: [step-agent_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm) +- All past versions are available at [releases.smallstep.com](https://releases.smallstep.com) + +When adding the package in Fleet (**Software → Add software → Custom package**), attach this **post-install script**: + +```bash +#!/bin/bash + +# Configure the Smallstep agent +mkdir -p /etc/step-agent +cat > /etc/step-agent/agent.yaml << EOF +team: "" +fingerprint: "" +EOF + +# Enable and start the agent service +systemctl daemon-reload +systemctl enable --now step-agent +``` + +Replace `` with your Smallstep team slug (found in [**Settings → Team**](https://smallstep.com/app/?next=/settings/team)), and `` with the SHA-256 root fingerprint of your Smallstep Agents authority (found in [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities) under the Agents authority). + + +
+If your fleet includes multiple Linux distributions or architectures, create separate software entries for each package variant. Use [Fleet labels](https://fleetdm.com/guides/managing-labels-in-fleet) to target `.deb` packages to Debian/Ubuntu hosts and `.rpm` packages to RHEL/Fedora hosts. See the [GitOps section](#gitops-configure-fleet-with-fleetctl) for a complete example with label targeting. +
+ + +After deployment, Linux devices will self-register with your Smallstep team via TPM attestation. By default, new devices require admin approval in the [Smallstep console](https://smallstep.com/app/?next=/devices). To automate approval, you can [pre-register devices via API](../platform/smallstep-agent.mdx#pre-registration-via-api). + +## Step 2. Confirmation (Linux) + +On a Fleet-enrolled Linux host: + +1. Verify the agent service is running: + + ```bash + sudo systemctl status step-agent + ``` + +2. Confirm certificate files are present under `/var/lib/step-agent` +3. In the Smallstep console, check [**Devices**](https://smallstep.com/app/?next=/devices/all) for the host. Approve it if approval is required. +4. In the Smallstep console, check **Certificate Manager → Inventory** for a freshly issued certificate matching the device + +# Windows + +Fleet does not yet support Smallstep as a native CA type on Windows, but it does support Windows SCEP enrollment through its **Dynamic SCEP - Okta CA or Microsoft NDES** CA type. To issue Smallstep certificates to Fleet-managed Windows devices today, point Fleet at Smallstep's NDES-compatible SCEP endpoints. Those endpoints are exposed by Smallstep's Workspace ONE connector, which emulates Microsoft ADCS Dynamic SCEP and NDES. -For Windows devices, create a file called `smallstep-scep.xml` using the SyncML format. -This profile mirrors the macOS profile above, enrolling a SCEP certificate -and trusting the Smallstep Agent Root CA. +Yes, it's a little confusing. But Smallstep's Workspace ONE connector exposes NDES endpoints that Fleet can consume. Workspace ONE itself is not involved. -To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities), click **View details** on the **Agents** authority, and copy the **Root Fingerprint** (SHA-256). +Our integration with Fleet on Windows does not include device inventory sync. If you want the Smallstep agent on Windows, you can deploy it as Fleet software separately (covered below). + +## Step 1. Create a Workspace ONE connector in Smallstep + +Begin by setting up a "Workspace ONE" integration to your Smallstep team: + +1. In the Smallstep console, go to [**Settings → Device Management**](https://smallstep.com/app/?next=/settings/devices) +2. Under **Available Providers**, find **Omnissa Workspace ONE** and click **Connect** +3. Fill in the form. All four credential fields are required by the form, but only the SCEP/NDES endpoints derived from this connection are used by Fleet. The form does not test the OAuth credentials before saving, so placeholders are accepted: + - **Name/Alias**: for example, `Fleet-Windows-Bridge` + - **REST API URL**: Not used by Fleet. Provide any well-formed HTTPS URL, for example `https://placeholder.example.com/API` + - **OAuth Client ID**: Not used by Fleet. Provide any string, for example `placeholder-client-id` + - **Token URL**: Note used by Fleet. Provide any well-formed HTTPS URL, for example `https://placeholder.example.com/connect/token` + - **OAuth Client Secret**: Not used by Fleet. Provide any string, for example `placeholder-client-secret` +4. Click **Connect MDM**. The connector is created immediately. +5. Go to the **Settings** tab for your new MDM connection, and collect the following values for the next step: + - **SCEP URL** + - **SCEP Challenge URL** + - **Challenge Username** + - **Challenge Password** + - **Root Certificate Fingerprint** + - Click **Download Root** to save the Root CA certificate as a PEM file + +## Step 2. Add the NDES CA in Fleet + +1. In Fleet, go to **Settings → Integrations → Certificate authorities** +2. Click **+ Add CA** +3. From the type dropdown, choose **Dynamic SCEP - Okta CA or Microsoft Network Device Enrollment Service (NDES)** +4. Fill in: + - **SCEP URL**: the Smallstep **SCEP URL** + - **Admin URL**: the Smallstep **SCEP Challenge URL** + - **Username**: the Smallstep **Challenge Username** + - **Password**: the Smallstep **Challenge Password** +5. Click **Add CA**. Fleet will test the connection by retrieving a one-time challenge from the admin URL. A green check confirms the credentials and challenge endpoint are reachable. + + +
+Fleet's NDES CA type is single-instance — you can have at most one NDES CA at a time per Fleet server. The Fleet variable names for this CA do not include a suffix. +
+ + +## Step 3. Create the Windows SyncML profile (`smallstep-windows.xml`) + +Fleet does not let you order separately uploaded SyncML profiles, so we put everything Windows needs into a single file. Within one profile, Fleet processes top-level commands in document order, so we can guarantee: + +1. The Smallstep Root CA is installed in the device's Trusted Root store +2. The SCEP CSP nodes are populated +3. The SCEP `Enroll` is triggered last + +Fleet substitutes these variables per host at deployment time: + +| Variable | Description | +|----------|-------------| +| `$FLEET_VAR_NDES_SCEP_PROXY_URL` | Fleet-hosted SCEP proxy URL for certificate requests | +| `$FLEET_VAR_NDES_SCEP_CHALLENGE` | One-time dynamic challenge Fleet retrieves from Smallstep's admin URL | +| `$FLEET_VAR_SCEP_RENEWAL_ID` | Per-device renewal identifier | +| `$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID` | Per-device certificate node ID in the Windows MDM CSP | + +Get the **CA Thumbprint** from the Smallstep Workspace ONE connector Settings page: switch the dropdown next to **Root Certificate Fingerprint** to **sha1** and copy that value. The Windows SCEP CSP expects a SHA-1 fingerprint for `CAThumbprint`. + +Create `smallstep-windows.xml` with the following contents. Replace `YOUR_ROOT_CA_FINGERPRINT` (in two places) with the SHA-1 Root Certificate Fingerprint, and paste the Base64 body of the Root CA PEM (everything between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`) into the `` element of the first ``: ```xml + + + + + ./Device/Vendor/MSFT/RootCATrustedCertificates/Root/YOUR_ROOT_CA_FINGERPRINT/EncodedCertificate + + + b64 + + + + + + + @@ -333,7 +505,7 @@ To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](ht chr - CN=step-agent-bootstrap,OU=$FLEET_VAR_SCEP_RENEWAL_ID + CN=%COMPUTERNAME%,OU=$FLEET_VAR_SCEP_RENEWAL_ID @@ -355,7 +527,7 @@ To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](ht chr - $FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_SMALLSTEP_AGENT + $FLEET_VAR_NDES_SCEP_PROXY_URL @@ -366,7 +538,7 @@ To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](ht chr - $FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_SMALLSTEP_AGENT + $FLEET_VAR_NDES_SCEP_CHALLENGE @@ -377,9 +549,10 @@ To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](ht chr - YOUR_ROOT_CA_SHA256_FINGERPRINT + YOUR_ROOT_CA_FINGERPRINT + @@ -389,92 +562,95 @@ To get the **CA Thumbprint**, go to [**Certificate Manager → Authorities**](ht ``` -- Replace `YOUR_ROOT_CA_SHA256_FINGERPRINT` with the Root Fingerprint from the Smallstep Agents authority. -- If you used a different CA name in Fleet, replace `SMALLSTEP_AGENT` in the variable names accordingly. +## Step 4. Upload the profile to Fleet -### Windows Root CA profile (`smallstep-root-ca.xml`) +1. In the Fleet console, go to **Controls → OS settings → Configuration profiles** +2. Click **Add profile** +3. Upload `smallstep-windows.xml` +4. Scope the profile to the teams or labels containing your Windows hosts -To install the Smallstep Agent Root CA on Windows, create a second file called `smallstep-root-ca.xml` using the `RootCATrustedCertificates` CSP: +The profile will be deployed to devices at their next MDM check-in. Fleet substitutes the `$FLEET_VAR_*` values per host. -```xml - - - - ./Device/Vendor/MSFT/RootCATrustedCertificates/Root/YOUR_ROOT_CA_SHA256_FINGERPRINT/EncodedCertificate - - - b64 - - - - - - -``` +## Step 5. Configure the Smallstep agent via a PowerShell script -## Step 5. Deploy the configuration profiles and Smallstep agent +The Windows Smallstep agent reads its configuration from `HKLM:\Software\Policies\Smallstep`. Fleet does not have native registry-management, so we set those values with a PowerShell script run by Fleet's [Scripts](https://fleetdm.com/guides/scripts) feature. -### Upload profiles +The agent needs three values: -1. In Fleet, go to **Controls → OS settings → Custom settings** -2. Click **Add profile** -3. Upload your `smallstep-agent.mobileconfig` file (for macOS/iOS) or your `.xml` files (for Windows) -4. Assign the profile to your desired scope (teams or all devices) +- `TeamSlug` — your Smallstep team slug (found in [**Settings → Team**](https://smallstep.com/app/?next=/settings/team)) +- `CAFingerprint` — the SHA-256 root fingerprint of your Smallstep Agents authority (found in [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities) under the Agents authority) +- `Certificate` — a CAPI selector that points to the bootstrap certificate issued by the SyncML profile in Step 3 -The profiles will be deployed to devices at their next check-in. Fleet will automatically substitute the variables with the appropriate values for each device. +Save the following as `smallstep-agent-config.ps1`, replacing `` and `` with your values: -### Deploy the agent +```powershell +$RegistryPath = "HKLM:\Software\Policies\Smallstep" -The last step is to deploy the [Smallstep agent](../platform/smallstep-agent.mdx) to your endpoints. The agent manages certificates and makes it easy to configure endpoints. +If (-NOT (Test-Path $RegistryPath)) { + New-Item -Path $RegistryPath -Force | Out-Null +} -You can deploy the agent using Fleet's [software deployment](https://fleetdm.com/guides/deploy-software-packages) feature: -1. [Download the agent package for your platform](https://releases.smallstep.com/): - - Windows (x64): [step-agent_amd64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi) - - Windows (ARM64): [step-agent_arm64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi) - - Linux (Debian/Ubuntu x64): [step-agent_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb) - - Linux (Debian/Ubuntu ARM64): [step-agent_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb) - - Linux (RHEL/Fedora x64): [step-agent_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm) - - Linux (RHEL/Fedora ARM64): [step-agent_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm) -2. In Fleet, go to **Software**, choose **Custom Package**, and add the package for distribution +Set-ItemProperty -Path $RegistryPath -Name "TeamSlug" -Value "" +Set-ItemProperty -Path $RegistryPath -Name "CAFingerprint" -Value "" +Set-ItemProperty -Path $RegistryPath -Name "Certificate" -Value "capi:store-location=machine;store=My;issuer=Smallstep () Agents Intermediate CA;cn=$env:COMPUTERNAME" +``` -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. + +
+If your team was created before October 2024, your issuer CA may have a common name without the team slug (`Smallstep Agents Intermediate CA`). Check your [Authority list](https://smallstep.com/app/?next=/cm/authorities) to confirm. +
+ -### Linux agent configuration +Upload the script to Fleet and run it against your Windows hosts: -Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux registers directly using TPM attestation. After installing the agent package, you must configure it with your Smallstep team slug and CA fingerprint. +1. In the Fleet console, go to **Controls → Scripts** +2. Click **Upload script** and select `smallstep-agent-config.ps1` +3. Scope or target the script to your Windows hosts and run it -When adding a Linux agent package in Fleet, add the following **post-install script** to configure and start the agent: +For self-healing enforcement, you can pair this with a [policy automation](https://fleetdm.com/guides/policy-automation-run-script) that checks whether the registry values exist and re-runs the script if they're missing — Fleet documents this pattern in [Prevent tampering of Fleet Orbit](https://fleetdm.com/guides/prevent-tampering-of-fleet-agent). -```bash -#!/bin/bash +## Step 6. Deploy the Smallstep agent -# Configure the Smallstep agent -mkdir -p /etc/step-agent -cat > /etc/step-agent/agent.yaml << EOF -team: "" -fingerprint: "" -EOF +Add the Smallstep agent MSI as Fleet software so it installs on enrollment: -# Enable and start the agent service -systemctl daemon-reload -systemctl enable --now step-agent -``` +1. Download the agent: + - x64: [step-agent_amd64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi) + - ARM64: [step-agent_arm64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi) + - All past versions are available at [releases.smallstep.com](https://releases.smallstep.com) +2. In the Fleet console, go to **Software**, choose **Add software → Custom package**, and upload the MSI +3. Scope the install to your Windows hosts -Replace `` with your Smallstep team slug (found in [**Settings → Team**](https://smallstep.com/app/?next=/settings/team)), and `` with the SHA-256 root fingerprint of your Smallstep Agents authority (found in [**Certificate Manager → Authorities**](https://smallstep.com/app/?next=/cm/authorities) under the Agents authority). +The agent reads the registry values written in Step 5 on startup, finds the bootstrap certificate from Step 3, and completes TPM-attested registration with your Smallstep team. - -
-If your fleet includes multiple Linux distributions or architectures, create separate software entries for each package variant. Use [Fleet labels](https://fleetdm.com/guides/managing-labels-in-fleet) to target `.deb` packages to Debian/Ubuntu hosts and `.rpm` packages to RHEL/Fedora hosts. See the [GitOps section](#gitops-configure-fleet-with-fleetctl) for a complete example with label targeting. -
- +## Step 7. Confirmation (Windows) -After deployment, Linux devices will self-register with your Smallstep team via TPM attestation. By default, new devices require admin approval in the [Smallstep console](https://smallstep.com/app/?next=/devices). To automate approval, you can [pre-register devices via API](../platform/smallstep-agent.mdx#pre-registration-via-api). +On a Fleet-enrolled Windows test host: -## GitOps: Configure Fleet with `fleetctl` +1. Trigger a sync: either reboot, or run `gpupdate /force` then wait for the MDM scheduler, or use the **Sync** button on the device under **Settings → Accounts → Access work or school** +2. Open **certlm.msc** (local machine, since this profile uses Device scope) +3. Under **Personal → Certificates**, confirm a certificate issued by your Smallstep Agents Intermediate CA with `CN=` +4. Under **Trusted Root Certification Authorities → Certificates**, confirm the Smallstep Root CA is present +5. Confirm the registry values were written: -As an alternative to Steps 3 through 5, you can manage your entire Fleet configuration with YAML files and the `fleetctl gitops` command. This approach is ideal for version-controlled, repeatable deployments. + ```powershell + Get-ItemProperty -Path HKLM:\Software\Policies\Smallstep + ``` -### Directory layout +6. Confirm the agent service is running: + + ```powershell + sc query "Smallstep Agent" + ``` + +7. In the Smallstep console, check **Certificate Manager → Inventory** for a freshly issued certificate matching the device, and confirm the device appears in [**Devices**](https://smallstep.com/app/?next=/devices/all) with an **Enrolled At** timestamp. + +If enrollment fails, check Fleet's host detail page for profile errors and `Event Viewer → Applications and Services Logs → Microsoft → Windows → DeviceManagement-Enterprise-Diagnostics-Provider → Admin` on the host for the underlying CSP error. + +# GitOps with `fleetctl` + +As an alternative to configuring Fleet through the UI, you can manage your entire Fleet configuration with YAML files and the `fleetctl gitops` command. This approach is ideal for version-controlled, repeatable deployments. + +## Directory layout A typical GitOps repository for Fleet looks like this: @@ -485,40 +661,49 @@ fleet-gitops/ │ └── team.yml └── lib/ ├── smallstep-agent.mobileconfig - ├── smallstep-scep.xml - ├── smallstep-root-ca.xml + ├── smallstep-windows.xml └── smallstep-agent-setup.sh ``` - `default.yml` — Organization-wide settings, including certificate authorities - `teams/team.yml` — Per-team configuration for profiles and software -- `lib/` — Configuration profile files created in [Step 4](#step-4-create-scep-configuration-profiles) and Linux agent setup script +- `lib/` — Configuration profile files and the Linux agent setup script -### Add the Smallstep CA +## Add the certificate authorities -In `default.yml`, add the Smallstep certificate authority under `org_settings`: +In `default.yml`, declare the Smallstep CA (Apple) and the NDES CA (Windows) under `org_settings`: ```yaml org_settings: certificate_authorities: smallstep: - name: SMALLSTEP_AGENT - url: - challenge_url: + url: + challenge_url: username: $SMALLSTEP_CHALLENGE_USERNAME password: $SMALLSTEP_CHALLENGE_PASSWORD + integrations: + ndes_scep_proxy: + url: + admin_url: + username: $SMALLSTEP_NDES_USERNAME + password: $SMALLSTEP_NDES_PASSWORD ``` -The `$SMALLSTEP_CHALLENGE_USERNAME` and `$SMALLSTEP_CHALLENGE_PASSWORD` values are environment variables. Set them before running `fleetctl gitops`: +Omit the block you don't need if you're only targeting one OS family. + +Set the credential environment variables before running `fleetctl gitops`: ```bash export SMALLSTEP_CHALLENGE_USERNAME='your-challenge-username' export SMALLSTEP_CHALLENGE_PASSWORD='your-challenge-password' +export SMALLSTEP_NDES_USERNAME='' +export SMALLSTEP_NDES_PASSWORD='' ``` -### Add configuration profiles +## Add configuration profiles -In your team YAML file, reference the profile files from [Step 4](#step-4-create-scep-configuration-profiles): +In your team YAML file, reference the profile files: ```yaml controls: @@ -527,11 +712,10 @@ controls: - path: ../lib/smallstep-agent.mobileconfig windows_settings: custom_settings: - - path: ../lib/smallstep-scep.xml - - path: ../lib/smallstep-root-ca.xml + - path: ../lib/smallstep-windows.xml ``` -### Add the Smallstep agent software +## Add the Smallstep agent software In the same team YAML file, add the Smallstep agent packages: @@ -575,7 +759,9 @@ If your Linux fleet includes multiple architectures, add entries for each varian Adapt the label names to match your Fleet label configuration. Fleet includes built-in labels for common Linux distributions. For architecture-specific targeting, you can create [custom labels](https://fleetdm.com/guides/managing-labels-in-fleet) using osquery queries (for example, `SELECT 1 FROM system_info WHERE cpu_type = 'x86_64'`). -### Apply the configuration +The PowerShell registry script from the Windows [Step 5](#step-5-configure-the-smallstep-agent-via-a-powershell-script) is run from the Fleet UI rather than GitOps. If you want it under version control, manage it through Fleet's [scripts API](https://fleetdm.com/docs/rest-api/rest-api#scripts). + +## Apply the configuration Run `fleetctl gitops` to apply the configuration: @@ -594,18 +780,3 @@ fleetctl gitops -f default.yml -f teams/team.yml --dry-run The `--dry-run` flag is useful for CI pipelines. You can run it on pull requests to validate configuration changes before merging. - -## Confirmation - -To confirm certificate deployment: - -1. In Fleet, go to **Hosts** and select a 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** to verify the device has enrolled and received 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 installed profiles -- **Windows**: Open **certmgr.msc** and check the Personal certificates store -- **Linux**: Run `sudo systemctl status step-agent` to verify the agent is running, and check `/var/lib/step-agent` for certificate files