From e6515cfa6aef0342fd66fb4de8d917456c610a51 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 63b3952deef72c754da96c5c72e6092b7afc8627 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 96fd742576759f1bbba101524296bf7aa31248be 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 262abb876896d7175c6ec62ce2144f1576f63c31 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 8ac579bc02ac8dd21f5250db4e19c15853db7a6f 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 4605d2d7d330c9bf63e43a822dbea54d76a484d1 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