Skip to content

Commit a961e5a

Browse files
tashiantashian
authored
Merge pull request #407 from smallstep/carl/intune
Intune docs
2 parents cbacf39 + ec33fd4 commit a961e5a

File tree

2 files changed

+271
-0
lines changed

2 files changed

+271
-0
lines changed

‎manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@
4747
{
4848
"title": "Connect Jamf Pro",
4949
"path": "/tutorials/connect-jamf-pro-to-smallstep.mdx"
50+
},
51+
{
52+
"title": "Connect Intune",
53+
"path": "/tutorials/connect-intune-to-smallstep.mdx"
5054
}
5155
]
5256
},

‎tutorials/connect-intune-to-smallstep.mdx‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
---
2+
updated_at: May 08, 2025
3+
title: Connect Intune to Smallstep
4+
html_title: Connect Intune to Smallstep
5+
description: Configure Intune to deploy the Smallstep Agent and distribute certificates and configuration to Mac clients.
6+
---
7+
8+
Smallstep can integrate with Microsoft Intune to synchronize your device inventory, to excahnge SCEP tokens, and to enroll your fleet with Smallstep using the Smallstep Agent. A SCEP token is a single-use password that's used by devices to get a certificate from Smallstep for bootstrapping.
9+
10+
In this document, we will configure your Microsoft Intune instance for use with your Smallstep team and any Windows endpoints.
11+
12+
To configure the connection, let’s first set up an Application in Entra ID. Then, we’ll add the client credentials to Smallstep.
13+
14+
# Prerequisites
15+
16+
You will need:
17+
18+
- A [Smallstep team](https://smallstep.com/signup)
19+
- A [Microsoft Azure / Entra ID](https://azure.microsoft.com/en-us/pricing/purchase-options/azure-account?icid=azurefreeaccount) Tenant
20+
- A [Microsoft Intune](https://www.microsoft.com/en-us/security/business/microsoft-intune) Tenant
21+
- A test device to enroll for management. This can be a Windows VM, but you may need a physical device or additional Wi-Fi adapter if you are testing an Enterprise Wi-Fi connection.
22+
23+
Client requirements:
24+
25+
- The agent will need to reach the following domains:
26+
```
27+
smallstep.com
28+
api.smallstep.com
29+
gateway.smallstep.com
30+
control.infra.smallstep.com
31+
*.[team-name].ca.smallstep.com
32+
auth.smallstep.com
33+
att.smallstep.com
34+
```
35+
- Windows 10 (Anniversary Edition) or higher is supported. Windows Home is not supported.
36+
37+
# Step-by-step instructions
38+
39+
### 1. Register an Entra ID Application
40+
41+
You’ll need to register an Application in Entra ID that connects Smallstep to Intune.
42+
43+
In the Entra Admin Center, [Register an Application](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false) with the following properties:
44+
45+
- Name the application “Smallstep”
46+
- Leave all other values alone
47+
- Select **Register**
48+
49+
In your new App Registration, copy the **Application (client) ID** value, which you will register with Smallstep later.
50+
51+
Next, visit the **Certificates & secrets** blade.
52+
53+
Select **＋ New client secret**, and use the following properties:
54+
55+
- Name the secret “Smallstep Secret”
56+
- Select **Add** to create the secret
57+
58+
Copy the **Client Secret Value**, which you will register with Smallstep later.
59+
60+
Choose a validity period that matches your security policies. When your client secret expires, you will need to update it in your Smallstep settings.
61+
62+
### 2. Grant API Permissions
63+
64+
Now we’ll connect the App Registration to Intune by adding application permissions.
65+
66+
In the App Registration, visit the **API Permissions** blade.
67+
68+
First, add the following permissions:
69+
70+
- Microsoft Graph → Application permissions → `Application.Read.All`
71+
- Microsoft Graph → Application permissions → `DeviceManagementManagedDevices.Read.All`
72+
- Intune → Application permissions → `scep_challenge_provider`
73+
- Intune → Application permissions → `get_data_warehouse`
74+
75+
Next, select **✓ Grant admin consent** on the API permissions page, and confirm.
76+
77+
Here’s how the Configured permissions should look:
78+
79+
![](/graphics/Intune_permissions.png)
80+
81+
You’ve completed the App Registration setup.
82+
83+
### 3. Configure Smallstep
84+
85+
In Smallstep, navigate to [Settings → Device Management](https://smallstep.com/app/?next=/settings/devices).
86+
87+
Configure the Integration with the values you gathered above:
88+
89+
- The Entra ID tenant **Primary domain**, from your [Entra ID Tenant Overview](https://entra.microsoft.com/#view/Microsoft_AAD_IAM/TenantOverview.ReactView) (eg. `contoso.onmicrosoft.com`)
90+
- The App Registration **Application (client) ID**
91+
- The App Registration **Secret Value**
92+
93+
Within a few minutes, you will see all of your Intune devices in the [Devices](https://smallstep.com/app/?next=/devices/all) tab. Your Smallstep device inventory is synced approximately every four hours.
94+
95+
### 4. Add the Smallstep Agent for app distribution
96+
97+
In this step, we’ll add the Smallstep Agent to Intune for distribution to devices.
98+
99+
1. In Intune,
100+
1. Start at [Windows Apps](https://intune.microsoft.com/#view/Microsoft_Intune_DeviceSettings/AppsWindowsMenu/~/windowsApps)
101+
2. Choose **+ Create,** and then select **Windows App (Win32)**
102+
3. [Download the Smallstep agent package](https://github.com/smallstep/agent/releases/download/intune-win-prerelease/step-agent-plugin-Setup_amd64_0.43.0.intunewin) and select it for upload in Intune.
103+
- For the App Information tab:
104+
- Under Publisher, use “Smallstep”
105+
- Choose “Next”
106+
- For the Program tab:
107+
- For Install Command, use:
108+
```
109+
step-agent-plugin-Setup_amd64_<version>.exe /silent
110+
```
111+
Replace `<version>` with the version of the Smallstep Agent being distributed.
112+
- For Uninstall Command, use:
113+
```
114+
msiexec /x "{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}"
115+
```
116+
- Choose “Next”
117+
- For the Requirements tab:
118+
- Operating System Architecture: 64-bit
119+
- Minimum operating system: Windows 10 1607
120+
- For the Detection rules tab:
121+
- Rules format: Manually configure detection rules
122+
- Choose **+ Add**
123+
- Rule Type: Registry
124+
- Key Path:
125+
```
126+
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}}_is1
127+
```
128+
- Value Name: `VersionMinor`
129+
- Detection Method: Integer Comparison
130+
- Operator: Greater than or equal to
131+
- Value: `<smallstep-agent-minor-version>`
132+
- Make sure you replace this with the current **minor** version (using SemVer conventions) of the Smallstep Agent being distributed. For example: `51` for version `0.51.0`.
133+
- Choose “Next”
134+
- For the Dependencies tab:
135+
- Choose “Next”
136+
- For the Supersedence tab:
137+
- Choose “Next”
138+
- For the Assignments tab:
139+
- Assign the app to devices as desired.
140+
- On “Review and Create” click **Create**
141+
142+
### 5. Configure Agent Enrollment Policy Set
143+
144+
In this step, we’ll tie everything together by creating Windows policy to enroll devices using the Smallstep Agent.
145+
146+
1. In the Smallstep dashboard, visit [Device Settings](https://smallstep.com/app/?next=/settings/devices) and choose your Intune connection.
147+
1. Select the **Settings** tab from the left-
148+
2. Download the Root Certificate
149+
3. Download the Intermediate Certificate
150+
4. Copy and temporarily save the **SCEP server URL** shown on the page, eg. `https://agents.example.ca.smallstep.com/scep/integration-intune-b967f507`
151+
2. Visit [Team Settings](https://smallstep.com/app/?next=/settings/team)
152+
1. Copy and temporarily save the **Team ID** value
153+
154+
### Create a Policy in Intune
155+
156+
1. In Intune, choose 🖥️ **Devices**
157+
2. Under the **Manage Devices** tab, Choose **Configuration**
158+
3. From the tabs at the top, select **Import ADMX**
159+
1. Select **Import**
160+
2. ADMX file: (upload [smallstep.admx](https://files.smallstep.com/intune/smallstep.admx))
161+
3. ADML file for the default language: (upload [smallstep-en-US.adml](https://files.smallstep.com/intune/smallstep-en-US.adml))
162+
4. Click **Next**
163+
5. On “Review and Create”, click **Create**
164+
4. From the tabs at the top, select **Policies**
165+
5. Click **Create** and then select **New Policy**
166+
1. Select **Platform**
167+
- Windows 10 and Later
168+
2. Select **Profile Type**
169+
- Templates
170+
3. Select **Template Name**:
171+
- Imported Administrative templates (Preview)
172+
4. Configure the policy
173+
1. Name: “Smallstep Agent”
174+
2. Choose “Next”
175+
3. Choose Setting Name: Smallstep → Settings → Smallstep Enrollment Settings
176+
4. Within the settings pane:
177+
1. Supported on: Enabled
178+
2. Team Slug: (paste the Team ID you saved earlier)
179+
3. Certificate URI:
180+
```
181+
capi:store-location=machine;store=My;issuer=Smallstep (<TeamSlug>) Agents Intermediate CA;cn=step-agent-bootstrap
182+
```
183+
Replace `<TeamSlug>` in the “Certificate URI” with your team’s slug.
184+
4. Leave the other settings as is.
185+
5. Choose “OK”
186+
5. In the Assignments tab:
187+
1. Assign the same devices that you deployed the Smallstep app to.
188+
6. Click **Next**
189+
7. On “Review and Create”, click **Create**
190+
6. Again, select **New Policy**
191+
1. Select **Platform**
192+
- Windows 10 and Later
193+
2. Select **Profile Type**
194+
- Templates
195+
3. Select **Template Name**
196+
- Trusted Certificate
197+
4. Choose “Create”
198+
5. Configure the policy
199+
- Name: **Smallstep Agents Authority Root**
200+
- In Configuration Settings
201+
- Certificate file: (upload the Root certificate you downloaded earlier)
202+
6. Set assignments
203+
1. Set the assignments as desired
204+
7. Click **Next** until “Review and Create”
205+
8. Click **Create**
206+
7. Again, select **New Policy**
207+
1. Select **Platform**
208+
- Windows 10 and Later
209+
2. Select **Profile Type**
210+
- Templates
211+
3. Select **Template Name**
212+
- Trusted Certificate
213+
4. Choose “Create”
214+
5. Configure the policy
215+
- Name: **Smallstep Agents Authority Intermediate**
216+
- In Configuration Settings
217+
- Certificate file: (upload the Intermediate certificate you downloaded earlier)
218+
- Destination store: Computer Certificate Store — Root
219+
220+
For legacy reasons, even though we are uploading an Intermediate CA here, we want to store it in the Root store, *not* the Intermediate store.
221+
222+
6. Set assignments
223+
1. Set the assignments as desired
224+
7. Click **Next** until “Review and Create”
225+
8. Click **Create**
226+
8. Click **Create** and then select **New Policy**
227+
1. Select **Platform**
228+
- Windows 10 and Later
229+
2. Select **Profile Type**
230+
- Templates
231+
3. Select **Template Name**
232+
1. SCEP Certificate
233+
4. Configure the policy
234+
- Name: **Smallstep SCEP**
235+
- Under Configuration Settings
236+
- Certificate Type: Device
237+
- Subject name format: `CN=step-agent-bootstrap`
238+
- Certificate validity period: 1 year (default)
239+
- Key storage provider (KSP): **Enroll to Trusted Platform Module (TPM) KSP** (if present), or **Software KSP**
240+
- Key usage: Digital Signature, Key Encipherment
241+
- Key Size: 2048
242+
- Hash Algorithm: SHA-2
243+
- Root Certificate: **Smallstep Agents Authority Intermediate**
244+
- Extended Key Usage:
245+
- Choose “Client Authentication” in the Predefined Values column
246+
- SCEP Server URLs: (paste the SCEP server URL you saved earlier)
247+
5. Set assignments
248+
1. Set the assignments as desired
249+
6. Click **Next** until “Review and Create”
250+
7. Click **Create**
251+
252+
Your Smallstep team is now linked to Intune. The devices that you scoped will receive a certificate and have the agent installed and running.
253+
254+
### Confirmation
255+
256+
There's two ways to confirm installation on an endpoint:
257+
258+
- In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp.
259+
- When viewing a Windows/Intune device in the Smallstep UI, you can review device logs to confirm connectivity to the platform and issued certificates.
260+
261+
### Uninstall Smallstep on Intune
262+
263+
In Intune, go to Apps and choose the Smallstep agent app.
264+
265+
Under the Assignments tab, remove all devices from Required and Available sections, and add all devices to the Uninstall section.
266+
267+
[OMA-URI Settings for Intune Wifi and Smallstep Agent](https://www.notion.so/OMA-URI-Settings-for-Intune-Wifi-and-Smallstep-Agent-1d6d17a91249808a8f29ee3a88f3394c?pvs=21)

0 commit comments

Comments
 (0)