From b6281e9769759ca3cf402a6ee9cfbf281760da34 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 14 Jul 2026 18:48:09 -0700 Subject: [PATCH 1/6] Support SCEP automatic profile redistribution in Iru tutorial With Iru's automatic profile redistribution enabled, the SCEP library item's UUID is appended to the certificate Subject, so the agent's keychain lookup label must include it. Without this, the agent's exact-match certificate lookup fails after the first renewal and the agent cannot start. - Enable automatic profile redistribution in the SCEP profile steps - Add a step to copy the SCEP library item's UUID from its URL - Include the UUID in the agent's mackms: certificate label - Require creating the SCEP profile before the agent Custom Profile - Warn against $PROFILE_UUID in the agent profile and against recreating the SCEP library item Co-Authored-By: Claude Fable 5 --- tutorials/connect-iru-to-smallstep.mdx | 40 +++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/tutorials/connect-iru-to-smallstep.mdx b/tutorials/connect-iru-to-smallstep.mdx index 29a39c16..05fec7f9 100644 --- a/tutorials/connect-iru-to-smallstep.mdx +++ b/tutorials/connect-iru-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: March 24, 2026 +updated_at: July 14, 2026 title: Connect Iru (Kandji) to Smallstep html_title: Integrate Iru (Kandji) with Smallstep Tutorial description: Integrate Iru (Kandji) with Smallstep for Apple device security. Complete guide for enforcing device trust in macOS environments. @@ -101,9 +101,29 @@ Keep this page open or save these values temporarily — you'll need them for th - Value: `deviceid:$DEVICE_ID` - **Key Size**: `2048` - **Key Usage**: `Both signing and encryption` -6. In the **Additional Options** section, enable **Allow all apps to access the private key** +6. In the **Additional Options** section, configure the following: + - Enable **Allow all apps to access the private key** + - 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** +When automatic profile redistribution is enabled, Iru appends the SCEP library item's UUID (its `$PROFILE_UUID` value) to the Subject on every request. The Common Name of the issued certificate will be `step-agent-bootstrap ` (with a single space before the UUID) rather than `step-agent-bootstrap` alone. The agent configuration below must reference this full name. + +### Copy the SCEP Library Item UUID + +The agent configuration in the next section requires the UUID of the SCEP library item you just created, so the SCEP library item must exist before you create the agent's Custom Profile. + +The UUID is the last path segment of the library item's URL in your browser's address bar: + +``` +https://.iru.com/library/scep/ +``` + +Copy the UUID and save it temporarily. You'll need it when configuring the agent settings below. + + + ## Install the Smallstep Agent There are two ways to install the agent: @@ -125,7 +145,9 @@ There are two ways to install the agent: #### Configure the Agent Settings -The Smallstep Agent requires configuration settings to connect to your Smallstep team. Deploy these via a Custom Profile: +The Smallstep Agent requires configuration settings to connect to your Smallstep team. Deploy these via a Custom Profile. + +The configuration includes the UUID of the SCEP library item, so you must [create the SCEP library item](#create-a-scep-profile-in-iru) and copy its UUID before creating this profile. 1. In the Smallstep console, choose ⚙️ **Settings** and temporarily save the **Team Slug** value 2. In the Iru sidebar, choose **Library** @@ -153,7 +175,7 @@ The Smallstep Agent requires configuration settings to connect to your Smallstep TeamSlug YOUR-TEAM-SLUG Certificate - mackms:label=step-agent-bootstrap;se=false;tag= + mackms:label=step-agent-bootstrap SCEP_LIBRARY_ITEM_UUID;se=false;tag= PayloadDisplayName @@ -172,8 +194,18 @@ The Smallstep Agent requires configuration settings to connect to your Smallstep Replace `YOUR-TEAM-SLUG` with your actual team slug from Smallstep. + Replace `SCEP_LIBRARY_ITEM_UUID` with the UUID of the SCEP library item you copied earlier. The agent looks up its certificate by an exact, case-sensitive match on this label, and the label must match the issued certificate's Common Name: `step-agent-bootstrap`, followed by a single space, followed by the UUID. For example: + + ``` + mackms:label=step-agent-bootstrap 0be2373f-40ce-4675-8a97-c25a2b0e51b2;se=false;tag= + ``` + 7. Choose **Save** + + #### Configure Login Items (macOS) To ensure the Smallstep Agent starts automatically on macOS devices: From f49025fefdb9d20e72f73e13405b88bd7dc86850 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 14 Jul 2026 18:54:17 -0700 Subject: [PATCH 2/6] Clarify that recreating the SCEP library item breaks the agent Co-Authored-By: Claude Fable 5 --- tutorials/connect-iru-to-smallstep.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/connect-iru-to-smallstep.mdx b/tutorials/connect-iru-to-smallstep.mdx index 05fec7f9..aa031583 100644 --- a/tutorials/connect-iru-to-smallstep.mdx +++ b/tutorials/connect-iru-to-smallstep.mdx @@ -121,7 +121,7 @@ https://.iru.com/library/scep/ Copy the UUID and save it temporarily. You'll need it when configuring the agent settings below. ## Install the Smallstep Agent From b06b2423569ce3e433c9c6b9ce4eeb9a46a35f90 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 16 Jul 2026 15:35:23 -0700 Subject: [PATCH 3/6] Use DN component search instead of SCEP item UUID in agent config Iru requires the profile identifier in the CN, so the CN is not a stable lookup key. Instead of copying the SCEP library item's UUID into the agent profile, set stable OU/L components in the SCEP Subject and have the agent search by those via mackms ou= and l=. Requires the SCEP profile and the agent Custom Profile to be assigned to the same Blueprint so $BLUEPRINT_ID renders identically in both. Co-Authored-By: Claude Fable 5 --- tutorials/connect-iru-to-smallstep.mdx | 40 +++++--------------------- 1 file changed, 7 insertions(+), 33 deletions(-) diff --git a/tutorials/connect-iru-to-smallstep.mdx b/tutorials/connect-iru-to-smallstep.mdx index aa031583..ae71b127 100644 --- a/tutorials/connect-iru-to-smallstep.mdx +++ b/tutorials/connect-iru-to-smallstep.mdx @@ -1,5 +1,5 @@ --- -updated_at: July 14, 2026 +updated_at: July 16, 2026 title: Connect Iru (Kandji) to Smallstep html_title: Integrate Iru (Kandji) with Smallstep Tutorial description: Integrate Iru (Kandji) with Smallstep for Apple device security. Complete guide for enforcing device trust in macOS environments. @@ -95,7 +95,7 @@ Keep this page open or save these values temporarily — you'll need them for th - **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=step-agent-bootstrap` + - **Subject**: `CN=$PROFILE_UUID,OU=$BLUEPRINT_ID,L=step-agent-bootstrap` - Enable **Subject Alternative Names (SAN)**: - Key: `Uniform Resource Identifier` - Value: `deviceid:$DEVICE_ID` @@ -106,23 +106,7 @@ Keep this page open or save these values temporarily — you'll need them for th - 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** -When automatic profile redistribution is enabled, Iru appends the SCEP library item's UUID (its `$PROFILE_UUID` value) to the Subject on every request. The Common Name of the issued certificate will be `step-agent-bootstrap ` (with a single space before the UUID) rather than `step-agent-bootstrap` alone. The agent configuration below must reference this full name. - -### Copy the SCEP Library Item UUID - -The agent configuration in the next section requires the UUID of the SCEP library item you just created, so the SCEP library item must exist before you create the agent's Custom Profile. - -The UUID is the last path segment of the library item's URL in your browser's address bar: - -``` -https://.iru.com/library/scep/ -``` - -Copy the UUID and save it temporarily. You'll need it when configuring the agent settings below. - - +A note on the Subject: with automatic profile redistribution enabled, Iru puts the SCEP profile's UUID in the Common Name, so the CN isn't a stable way to identify the certificate. The other two components give the agent stable values to search on instead. Iru replaces `$BLUEPRINT_ID` with the ID of the assigned Blueprint, and `L=step-agent-bootstrap` is a fixed marker value. The agent configuration below looks up the certificate by these two fields. ## Install the Smallstep Agent @@ -145,15 +129,13 @@ There are two ways to install the agent: #### Configure the Agent Settings -The Smallstep Agent requires configuration settings to connect to your Smallstep team. Deploy these via a Custom Profile. - -The configuration includes the UUID of the SCEP library item, so you must [create the SCEP library item](#create-a-scep-profile-in-iru) and copy its UUID before creating this profile. +The Smallstep Agent requires configuration settings to connect to your Smallstep team. Deploy these via a Custom Profile: 1. In the Smallstep console, choose ⚙️ **Settings** and temporarily save the **Team Slug** value 2. In the Iru sidebar, choose **Library** 3. Choose **Add Library Item**, then select **Custom Profile**, and click **Add and Configure** 4. Set a title (e.g., `Smallstep Agent Configuration`) -5. Under **Assignment**, choose your desired Blueprint (should match the agent installation scope) +5. Under **Assignment**, choose the same Blueprint you assigned to the SCEP profile. This is required: Iru renders `$BLUEPRINT_ID` in both library items, and the values only match when both are assigned to the same Blueprint. 6. In the **Settings** section, create a `.mobileconfig` file with the following content and upload it: ```xml @@ -175,7 +157,7 @@ The configuration includes the UUID of the SCEP library item, so you must [creat TeamSlug YOUR-TEAM-SLUG Certificate - mackms:label=step-agent-bootstrap SCEP_LIBRARY_ITEM_UUID;se=false;tag= + mackms:ou=$BLUEPRINT_ID;l=step-agent-bootstrap;se=false;tag= PayloadDisplayName @@ -194,18 +176,10 @@ The configuration includes the UUID of the SCEP library item, so you must [creat Replace `YOUR-TEAM-SLUG` with your actual team slug from Smallstep. - Replace `SCEP_LIBRARY_ITEM_UUID` with the UUID of the SCEP library item you copied earlier. The agent looks up its certificate by an exact, case-sensitive match on this label, and the label must match the issued certificate's Common Name: `step-agent-bootstrap`, followed by a single space, followed by the UUID. For example: - - ``` - mackms:label=step-agent-bootstrap 0be2373f-40ce-4675-8a97-c25a2b0e51b2;se=false;tag= - ``` + Leave `$BLUEPRINT_ID` as-is; Iru replaces it with the assigned Blueprint's ID when it deploys the profile. The `ou` and `l` values in the `Certificate` URI must match the `OU` and `L` components of the SCEP profile's Subject, which is why both library items must be assigned to the same Blueprint. 7. Choose **Save** - - #### Configure Login Items (macOS) To ensure the Smallstep Agent starts automatically on macOS devices: From dcb7455db6be447e809c3f221ac5bbb1ca4b405b Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 16 Jul 2026 16:07:40 -0700 Subject: [PATCH 4/6] Update tutorials/connect-iru-to-smallstep.mdx --- tutorials/connect-iru-to-smallstep.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/tutorials/connect-iru-to-smallstep.mdx b/tutorials/connect-iru-to-smallstep.mdx index ae71b127..e49a2351 100644 --- a/tutorials/connect-iru-to-smallstep.mdx +++ b/tutorials/connect-iru-to-smallstep.mdx @@ -176,8 +176,6 @@ The Smallstep Agent requires configuration settings to connect to your Smallstep Replace `YOUR-TEAM-SLUG` with your actual team slug from Smallstep. - Leave `$BLUEPRINT_ID` as-is; Iru replaces it with the assigned Blueprint's ID when it deploys the profile. The `ou` and `l` values in the `Certificate` URI must match the `OU` and `L` components of the SCEP profile's Subject, which is why both library items must be assigned to the same Blueprint. - 7. Choose **Save** #### Configure Login Items (macOS) From 8859bcaf4df0c6c1a6309d642d456a6c3d09fbb9 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 16 Jul 2026 16:07:46 -0700 Subject: [PATCH 5/6] Update tutorials/connect-iru-to-smallstep.mdx --- tutorials/connect-iru-to-smallstep.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tutorials/connect-iru-to-smallstep.mdx b/tutorials/connect-iru-to-smallstep.mdx index e49a2351..b9ae28b2 100644 --- a/tutorials/connect-iru-to-smallstep.mdx +++ b/tutorials/connect-iru-to-smallstep.mdx @@ -106,8 +106,7 @@ Keep this page open or save these values temporarily — you'll need them for th - 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** -A note on the Subject: with automatic profile redistribution enabled, Iru puts the SCEP profile's UUID in the Common Name, so the CN isn't a stable way to identify the certificate. The other two components give the agent stable values to search on instead. Iru replaces `$BLUEPRINT_ID` with the ID of the assigned Blueprint, and `L=step-agent-bootstrap` is a fixed marker value. The agent configuration below looks up the certificate by these two fields. - +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. ## Install the Smallstep Agent There are two ways to install the agent: From 9ddd5d45731287971f820c19b285fb6f657eb92d Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 16 Jul 2026 16:07:52 -0700 Subject: [PATCH 6/6] Update tutorials/connect-iru-to-smallstep.mdx --- tutorials/connect-iru-to-smallstep.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/connect-iru-to-smallstep.mdx b/tutorials/connect-iru-to-smallstep.mdx index b9ae28b2..bbdb2323 100644 --- a/tutorials/connect-iru-to-smallstep.mdx +++ b/tutorials/connect-iru-to-smallstep.mdx @@ -134,7 +134,7 @@ The Smallstep Agent requires configuration settings to connect to your Smallstep 2. In the Iru sidebar, choose **Library** 3. Choose **Add Library Item**, then select **Custom Profile**, and click **Add and Configure** 4. Set a title (e.g., `Smallstep Agent Configuration`) -5. Under **Assignment**, choose the same Blueprint you assigned to the SCEP profile. This is required: Iru renders `$BLUEPRINT_ID` in both library items, and the values only match when both are assigned to the same Blueprint. +5. Under **Assignment**, choose the same Blueprint you assigned to the SCEP profile. This is required for the agent to find the certificate. 6. In the **Settings** section, create a `.mobileconfig` file with the following content and upload it: ```xml