Skip to content

Suggestions for the Iru + Windows guide from testing #575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tashian merged 1 commit into from
Nov 2, 2026
Merged

Suggestions for the Iru + Windows guide from testing #575

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 55 additions & 33 deletions tutorials/connect-iru-to-smallstep.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
updated_at: October 15, 2026
updated_at: October 28, 2026
title: Connect Iru (Kandji) to Smallstep
html_title: Integrate Iru (Kandji) with Smallstep Tutorial
description: Integrate Iru (Kandji) with Smallstep for device security. Complete guide for enforcing device trust on macOS and Windows endpoints.
Expand Down Expand Up @@ -34,13 +34,13 @@ Client requirements:
Supported platforms:

- macOS — SCEP profile and agent, with agent configuration delivered through a `.mobileconfig` profile
- Windows 10 (Anniversary Edition) or higher, Pro or Enterprise — SCEP profile and agent, with agent configuration delivered through registry policy values.
- Windows 10 Anniversary Update (1607) or higher, Pro or Enterprise, with TPM 2.0 — SCEP profile and agent, with agent configuration delivered through registry policy values.

Limitations:

- Devices must be assigned to a Blueprint in Iru to be synced with Smallstep. Devices not in any Blueprint will not appear in your Smallstep inventory.
- Iru supports static SCEP for enrollment. This limitation only relates to the Smallstep provisional enrollment certificate for each device. Once the Smallstep agent is enrolled, all credentials are hardware-bound and attested.
- Iru Library items are specific to one operating system. If you manage both macOS and Windows endpoints, create a separate set of items for each platform, and assign each set only to devices running that platform.
- Iru Custom Apps and Custom Scripts are specific to one operating system. A SCEP item can target Apple devices, Windows devices, or both, using its **Install on** setting. If you manage both macOS and Windows endpoints, create a separate set of items for each platform, including a separate SCEP item, and assign each set only to devices running that platform.

## Create an API Token in Iru

Expand All @@ -55,9 +55,9 @@ This API token will allow Smallstep to read your Iru device inventory for ongoin
3. Note your **organization's API URL** (e.g., `your-org.api.kandji.io`) — you'll need this later
4. Choose **Add Token** and give it a name (e.g., `Smallstep`)
5. Choose **Copy Token** to copy the token value and save it temporarily — you'll use it in the next step
6. Save the token and choose **Continue** to manage its API permissions
7. On the API token page, choose **Edit** and enable the following permissions:
- **Device List**
6. Choose **Save**. Iru shows a **Manage API Permissions** dialog.
7. Choose **Configure** and enable the following permissions:
- **Device list**
- **Device ID**
8. Choose **Save**

Expand All @@ -70,18 +70,18 @@ Let's add the Iru credentials to Smallstep. You'll need the API URL and the API
3. Enter the following credentials:
- **Iru API URL**: Your organization's Iru API URL (e.g., `https://your-org.api.kandji.io`)
- **API Token**: The token you created in the previous step
4. Choose **Connect MDM**. Your device inventory will start syncing from Iru to Smallstep. You can check the Logs tab for sync status, and confirm that Iru is syncing by checking the Devices list. By default, all new devices will need to be approved in the Smallstep console.
4. Choose **Connect MDM**. Your device inventory will start syncing from Iru to Smallstep. You can check the Logs tab for sync status, and confirm that Iru is syncing by checking the Devices list. Devices synced from Iru are approved automatically by default.

Your Smallstep team is now linked to Iru. Smallstep will do a partial sync of your device inventory every hour, and a full sync every 8 hours.

## Get Smallstep CA Details

After connecting Iru to Smallstep, you'll find most of the certificate details you need on the Platform Settings page:
After connecting Iru to Smallstep, you'll find most of the certificate details you need on the connection's **Settings** tab:

1. In the Smallstep console, go to [**Device Management**](https://smallstep.com/app/?next=/settings/devices) in **Settings**
2. Click on your Iru connection
3. From this page, you can:
- Copy the **SCEP URL** (for example, `https://agents.example.ca.smallstep.com/scep/integration-iru-abc123`)
2. Click on your Iru connection, and select the **Settings** tab
3. From this tab, you can:
- Copy the **SCEP URL** (for example, `https://your-team.scep.smallstep.com/p/agents/integration-iru-abc123`)

@hslatman hslatman Nov 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with this change, but it assumes one is OK with trusting Web PKI.

@llewis1234 llewis1234 Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with this change, but it assumes one is OK with trusting Web PKI.

I changed this to match what my connection's Settings tab shows now (https://.scep.smallstep.com/p/agents/integration-iru-), so the example matches what people copy. Good point on Web PKI. Happy to switch it back to the *.ca.smallstep.com form if that's the endpoint you'd rather customers use. In that case the console probably should show it too.

@hslatman hslatman Nov 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that's what's shown (now), let's keep it like this.

I'm not sure if we ever documented this URL pattern somewhere, and what it implies w.r.t. Web PKI. If anything, it's outside the scope of this PR.

@tashian tashian Nov 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry to merge this one prematurely. I've been adding commits to Herman's PR

- Copy the **SCEP Challenge** value
- Copy the **Root Certificate Fingerprint** (macOS only)

Expand All @@ -99,21 +99,23 @@ Keep this page open or save these values temporarily — you'll need them for th
1. In the Iru sidebar, choose **Library**
2. Choose **Add Library Item**, then select **SCEP**, and click **Add and Configure**
3. Set a title (e.g., `Smallstep`)
4. Under **Assignment**, choose your desired Blueprint
5. In the **General Settings** section, configure the following:
4. Set **Install on** to Apple devices only
5. Under **Assignment**, choose your desired Blueprint
6. In the **General settings** section, configure the following:
- **URL**: Paste the SCEP URL from the previous step
- **Challenge**: Paste the SCEP Challenge from the previous step
- **Fingerprint**: Paste the Root Certificate Fingerprint from the previous step
- **Subject**: `CN=$PROFILE_UUID,OU=$BLUEPRINT_ID,L=step-agent-bootstrap`
- Enable **Subject Alternative Names (SAN)**:
- Key: `Uniform Resource Identifier`
- Value: `deviceid:$DEVICE_ID`
- **Key Size**: `2048`
- **Key Usage**: `Both signing and encryption`
6. In the **Additional Options** section, configure the following:
- Enable **Allow all apps to access the private key**
- **Key size**: `2048`
- **Key usage**: `Both signing and encryption`
7. In the **Additional options** section, configure the following:
- Enable **Automatic profile redistribution**, and set the number of days before certificate expiration when Iru should redistribute the profile (Iru defaults to 30 days). This is what lets the agent's enrollment certificate renew before it expires.
7. Choose **Save**
8. In the **Apple only settings** section, configure the following:
- Enable **Allow all apps to access the private key**
9. Choose **Save**

A note on the Subject: Iru replaces `$BLUEPRINT_ID` with the ID of the assigned Blueprint, and `L=step-agent-bootstrap` is a fixed marker value. In the agent configuration below, the agent uses these fields to look up the certificate on the device.

Expand Down Expand Up @@ -214,22 +216,27 @@ Windows enrollment uses the same SCEP flow as macOS: Iru issues a provisional en
1. In the Iru sidebar, choose **Library**
2. Choose **Add Library Item**, then select **SCEP**, and click **Add and Configure**
3. Set a title (e.g., `Smallstep (Windows)`)
4. Set the item to apply to **Windows** devices only
4. Set **Install on** to Windows devices only
5. Under **Assignment**, choose a Blueprint that only contains Windows devices
6. Configure the following settings:
6. In the **General settings** section, configure the following:
- **URL**: Paste the SCEP URL from the previous step
- **Challenge**: Paste the SCEP Challenge from the previous step
- **Fingerprint**: Paste the SHA-1 fingerprint of the **intermediate** certificate of your Agents authority
- **Subject**: `CN=step-agent-bootstrap,OU=$BLUEPRINT_ID`
- **Subject Alternative Names (SAN)**:
- Enable **Subject Alternative Names (SAN)**:
- Key: `Uniform Resource Identifier`
- Value: `deviceid:$DEVICE_ID`
- **Hash Algorithm**: `SHA-256`
- **Key Usage**: `Client Authentication`
- **Key Storage**: `TPM or Fail`
- **Validity period**: `30 days`
7. Enable **Retries** and set it to a value between `3` and `5`, with a retry delay of `5` minutes. Retries make enrollment resilient to a device being offline or the TPM being busy when the profile first arrives.
8. Enable **Automatic profile redistribution** and set it to `20` days. Keep this value comfortably inside the certificate's validity period, so the enrollment certificate is renewed before it expires. The example above assumes a 30-day certificate; adjust it if your authority issues certificates with a different lifetime.
- **Key size**: `2048`
- **Key usage**: `Both signing and encryption`
7. In the **Additional options** section, configure the following:
- Enable **Retries**, and set it to a value between `3` and `5`. Retries make enrollment resilient to a device being offline or the TPM being busy when the profile first arrives.
- Enable **Automatic profile redistribution**, and set it to `20` days. Your Agents authority sets the lifetime of the enrollment certificate, which is 30 days by default. Keep this value comfortably inside that lifetime, so the enrollment certificate is renewed before it expires.
8. In the **Windows only settings** section, configure the following:
- **Hash algorithm**: `SHA-256`
- **Retry wait time in minutes**: `5`
- **Extended key usage**: `Client authentication`
- **Key protection**: `TPM or Fail`
- **Valid period**: `Not configured`. Your Agents authority sets the certificate lifetime.
9. Choose **Save**

Iru replaces `$BLUEPRINT_ID` with the ID of the assigned Blueprint, and `$DEVICE_ID` with the Iru device ID. The agent uses the issuer and common name of this certificate to find it on the device, as configured in the next step.
Expand Down Expand Up @@ -257,7 +264,7 @@ Iru distributes Windows apps as a `.zip` archive, so you'll download the agent M
The product code is specific to the version and the architecture of the MSI, so read it from the exact file you are going to upload.
3. Compress the MSI into a `.zip` archive
4. In the Iru sidebar, choose **Library**
5. Choose **Add Library Item**, then select **Custom App**, and click **Add and Configure**
5. Choose **Add Library Item**, then select **Windows Custom App**, and click **Add and Configure**
6. Set a title (e.g., `Smallstep Agent`)
7. Under **Assignment**, choose the same Windows Blueprint you assigned the SCEP item to
8. Configure the following settings:
Expand All @@ -266,7 +273,7 @@ Iru distributes Windows apps as a `.zip` archive, so you'll download the agent M
- **Name**: `Smallstep Agent`
- **Version**: the version of the MSI you downloaded (e.g., `0.70.0`)
- **Icon**: upload an icon to show in the Iru app catalog
- **Architecture**: the architecture of the MSI you downloaded, `AMD64` or `ARM64`
- **Architecture**: the architecture of the MSI you downloaded, `x64` or `ARM64`
9. Upload the `.zip` archive you created
10. Set the install command, matching the MSI filename inside the archive:

Expand All @@ -289,10 +296,10 @@ The agent needs two values:
- `Certificate` — a URI that tells the agent where to find the enrollment certificate that the SCEP item issued

1. In the Iru sidebar, choose **Library**
2. Choose **Add Library Item**, then select **Custom Script**, and click **Add and Configure**
2. Choose **Add Library Item**, then select **Windows Custom Script**, and click **Add and Configure**
3. Set a title (e.g., `Smallstep Agent Configuration`)
4. Under **Assignment**, choose the same Windows Blueprint you assigned the SCEP item to
5. Add the following PowerShell script, replacing `<team-slug>` with your team slug and `<team-name>` with your full team name:
5. Select **Manually enter script**, and add the following PowerShell script, replacing `<team-slug>` with your team slug and `<team-name>` with your full team name:

```powershell
$RegistryPath = "HKLM:\Software\Policies\Smallstep"
Expand All @@ -313,7 +320,20 @@ If your team was created before October, 2024, your issuer CA may have a common
</div>
</Alert>

Set the script to run continuously, so the registry values are restored if they are removed or changed on a device.
The script runs once per device. Editing the script does not run it again. To apply it again, remove it from the Blueprint and assign it again.

If the registry values are missing, the agent keeps running and waits for them. When the values are restored, the agent reads them within about a minute, without a restart.

## Enroll Windows Devices in Iru

If your Windows devices are not enrolled in Iru yet, enroll them in the Windows Blueprint:

1. In the Iru sidebar, choose **Enrollment**, then select the **Manual Enrollment** tab
2. Under **Enrollment portal with code**, make sure **Enrollment Portal** is turned on, and copy the **Enrollment Portal link** (e.g., `https://your-org.iru.com/enroll`)
3. Copy the **Enrollment code** of your Windows Blueprint
4. On each Windows device, open the Enrollment Portal link and enter the enrollment code

When a device enrolls, Iru delivers the SCEP item, the agent, and the configuration script to it.

## Confirmation (Windows)

Expand All @@ -329,7 +349,7 @@ On a Windows endpoint in the assigned Blueprint:
3. Confirm the agent service is running:

```powershell
sc query "Smallstep Agent"
sc.exe query "Smallstep Agent"
```

4. In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp.
Expand All @@ -345,3 +365,5 @@ You can remove the Smallstep Agent from endpoints managed by Iru by deleting the
- **Smallstep Agent Configuration** (Custom Profile on macOS, Custom Script on Windows)
- **Smallstep** (SCEP), and **Smallstep (Windows)** (SCEP) if you created a separate item for Windows
- **Smallstep Login Item** (Login & Background Items, macOS only)

On Windows, deleting the Library items removes only the SCEP certificate. The Smallstep Agent stays installed on the device. To remove it, follow the uninstall steps in [Smallstep Agent Windows installation](../platform/smallstep-agent.mdx#windows-installation).
Loading