Skip to content

Commit db474f4

Browse files
tashiantashian
authored
Merge pull request #411 from smallstep/carl/intune
Workspace ONE docs
2 parents a961e5a + 016f14b commit db474f4

File tree

3 files changed

+196
-3
lines changed

3 files changed

+196
-3
lines changed

‎manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,10 @@
5151
{
5252
"title": "Connect Intune",
5353
"path": "/tutorials/connect-intune-to-smallstep.mdx"
54+
},
55+
{
56+
"title": "Connect Workspace One UEM",
57+
"path": "/tutorials/connect-workspace-one-to-smallstep.mdx"
5458
}
5559
]
5660
},

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
updated_at: May 08, 2025
2+
updated_at: May 13, 2025
33
title: Connect Intune to Smallstep
44
html_title: Connect Intune to Smallstep
55
description: Configure Intune to deploy the Smallstep Agent and distribute certificates and configuration to Mac clients.
@@ -99,7 +99,7 @@ In this step, we’ll add the Smallstep Agent to Intune for distribution to devi
9999
1. In Intune,
100100
1. Start at [Windows Apps](https://intune.microsoft.com/#view/Microsoft_Intune_DeviceSettings/AppsWindowsMenu/~/windowsApps)
101101
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.
102+
3. [Download the Smallstep agent package](https://github.com/smallstep/step-agent-plugin/releases/latest) and select it for upload in Intune.
103103
- For the App Information tab:
104104
- Under Publisher, use “Smallstep”
105105
- Choose “Next”
@@ -151,7 +151,7 @@ In this step, we’ll tie everything together by creating Windows policy to enro
151151
2. Visit [Team Settings](https://smallstep.com/app/?next=/settings/team)
152152
1. Copy and temporarily save the **Team ID** value
153153

154-
### Create a Policy in Intune
154+
### 6. Create a Policy in Intune
155155

156156
1. In Intune, choose 🖥️ **Devices**
157157
2. Under the **Manage Devices** tab, Choose **Configuration**

‎tutorials/connect-workspace-one-to-smallstep.mdx‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
updated_at: May 13, 2025
3+
title: Connect Workspace One UEM to Smallstep
4+
html_title: Connect Workspace One to Smallstep
5+
description: Configure Workspace One UEM to deploy the Smallstep Agent and distribute certificates and configuration to clients.
6+
---
7+
8+
Smallstep can integrate with [Omnissa Workspace ONE UEM](https://www.omnissa.com/products/workspace-one-unified-endpoint-management/) to keep your device inventory in sync and to exchange SCEP tokens. A SCEP token is a single-use password that's used by devices to get a certificate from Smallstep.
9+
10+
To configure the connection, let’s first set up an Application in Entra ID. Then, we’ll add the client credentials to Smallstep.
11+
12+
# Prerequisites
13+
14+
You will need:
15+
16+
- A [Smallstep team](https://smallstep.com/signup)
17+
- A [Workspace ONE UEM](https://www.omnissa.com/products/workspace-one-unified-endpoint-management/) tenant
18+
- A test device to enroll for management
19+
- This can be a Windows VM, but you may need a physical device or additional Wi-Fi adapter for testing an Enterprise Wi-Fi connection. Windows Home edition is not supported.
20+
21+
# Step-by-step instructions
22+
23+
### 1. Connect Smallstep to Workspace ONE via OAuth
24+
25+
First, we’ll create a scoped API role for Smallstep:
26+
27+
1. In Workspace ONE UEM, navigate to **Accounts → Admin Roles** and choose **+ Add Role**
28+
2. Create a role named “Smallstep” with a description of “Smallstep Integration”
29+
3. Smallstep needs Read access to Devices, using the REST API. Choose API → REST on the left, and choose ✅ Read for the row “Devices”
30+
31+
![Workspace ONE API Panel](workspace-one/api-panel.png)
32+
33+
4. Choose **Save**
34+
35+
Next, we’ll create an OAuth client for Smallstep:
36+
37+
1. In Workspace ONE UEM, navigate to **Groups & Settings → Configurations** and find **OAuth Client Management** in the list
38+
2. Choose **Add** and add a new client with a name of “Smallstep” and description of “Smallstep MDM Integration for Device Sync”
39+
3. For **Organization Group**, select the group most appropriate for managing your desired device inventory
40+
4. For **Role**, choose **Smallstep**
41+
5. Choose **Save**
42+
6. Copy the resulting client ID and secret value
43+
44+
### 2. Configure Smallstep OAuth settings
45+
46+
In Smallstep, navigate to [Settings → Device Management](https://smallstep.com/app/?next=/settings/devices).
47+
48+
Configure a new Omnissa Workspace ONE Integration with the values you gathered above:
49+
50+
- The Workspace ONE UEM REST API URL for your tenant.
51+
- This URL is shown in UEM’s settings. Navigate to
52+
**Groups and Settings** → **All Settings →** **System** → **Advanced** → **API** → **Rest API**
53+
- Copy the REST API URL from that page
54+
- The Workspace ONE UEM [OAuth 2.0 Token URL for your region](https://docs.omnissa.com/bundle/WorkspaceONE-UEM-Console-BasicsVSaaS/page/UsingUEMFunctionalityWithRESTAPI.html#datacenter_and_token_urls_for_oauth_20_support)
55+
- The OAuth client ID and secret you saved in Step 1
56+
57+
After saving the Workspace ONE connection, you will see settings for your integration. Copy the following details for later:
58+
59+
- SCEP URL
60+
- SCEP Challenge URL
61+
- Challenge Basic Authentication Username
62+
- Challenge Basic Authentication Password
63+
64+
Within a few minutes after adding the connection, you should see all of your Workspace ONE devices in the [Devices](https://smallstep.com/app/?next=/devices/all) tab. Device inventory is synced approximately every four hours.
65+
66+
### 3. Create a script for Smallstep Agent configuration
67+
68+
1. In Workspace One UEM, visit **Resources → Scripts**
69+
2. Choose **Add** and then **Windows**
70+
1. In the General tab, provide a name for the script, such as “Smallstep Agent Enrollment”
71+
2. On the Details tab, ensure the **Language** is “Poweshell” and the **Execution Context & Privileges** is “System Context”
72+
3. Use the following snippet as the **Code**, making sure to replace `<team-id>` with the Team ID value you copied from the Smallstep UI earlier.
73+
74+
```xml
75+
New-Item -Path "HKLM:\Software\Policies\Smallstep"
76+
Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "TeamSlug" -Value "<team-id>"
77+
Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "Certificate" -Value "capi:store-location=machine;store=My;issuer=Smallstep (<team-id>) Agents Intermediate CA;cn=$env:DEVICE_ID"
78+
```
79+
80+
4. In the Variables tab, click **Add**. Set the variable **Key** to `DEVICE_ID` and the variable **Value** to `{DeviceUuId}`
81+
82+
### 4. Deploy and configure the Smallstep Agent
83+
84+
In this step, we’ll add the Smallstep Agent to Workspace One UEM for distribution to devices.
85+
86+
1. In Workspace One UEM,
87+
- Go to Resources → Native Apps.
88+
- Choose Add → Application File.
89+
- Download the [latest version](https://github.com/smallstep/step-agent-plugin/releases/latest) of `step-agent-plugin_amd64_<version>.msi` and select it for upload to UEM. Note the version number you downloaded—you’ll need it later.
90+
- Choose **Continue**
91+
2. In the Add Application panel’s **Details tab**,
92+
- Set Supported Processor Architecture to `64-bit` (or `ARM64` if used)
93+
- For Minimum OS, select Windows 10 (10.0.15063)
94+
3. In the Add Application panel’s **Deployment Options** tab,
95+
- Set Install Context to **Device**
96+
4. FInally, choose **Save & Assign**
97+
98+
<Alert severity="info">
99+
<div>
100+
**Got ARM64 devices?**<br />
101+
If you also are deploying to ARM-based devices, add another Native App for the `arm64` version of our [MSI installer](https://github.com/smallstep/step-agent-plugin/releases/latest). Workspace ONE will try to distribute *both* installers to both `arm64` and `amd64` devices. To avoid this, segregate your devices by OS and CPU Architecture. To do this, create two new Smart Groups in **Groups & Settings → Assignment Groups**—one for `arm64` devices, and one for `amd64` devices. Assign each application to the appropriate Smart Group.
102+
</div>
103+
</Alert>
104+
105+
#### Assigning the application
106+
107+
After saving the Native App, you'll see the Application Assignment panel.
108+
109+
1. Give the Assignment a name
110+
2. Choose the groups you’d like to assign the application to. Assign the app to a single devices or a small group of test devices for a staged rollout.
111+
3. Select App Delivery Method: Auto
112+
4. Create the Assignment.
113+
5. Choose **Save**
114+
6. Choose **Publish** to begin distributing the app.
115+
116+
### 5. Configure Agent Enrollment Profiles
117+
118+
In this step, we’ll tie everything together by creating Windows policy to enroll devices using the Smallstep Agent.
119+
120+
#### Gather required details
121+
122+
1. You’ll need the following values from when your configuration your Workspace ONE connection:
123+
- SCEP URL
124+
- SCEP Challenge URL
125+
- Challenge Basic Authentication Username
126+
- Challenge Basic Authentication Password
127+
128+
If you need to retrieve these again, you can always visit: [**Settings → Device Management](https://smallstep.com/app/?next=/settings/devices) → Omnissa Workspace ONE**
129+
130+
#### Add a Workspace ONE CA resource
131+
132+
For compatibility with Workspace ONE, Smallstep emulates the Microsoft ADCS’s Dynamic SCEP and NDES enrollment protocols.
133+
134+
1. In Workspace One UEM, visit **Resources → Certificate Authorities**
135+
2. Choose **+ Add**
136+
1. Provide a name for the CA connection, e.g. Smallstep Agents CA
137+
2. For Authority Type, choose `Microsoft ADCS`
138+
3. For Protocol, choose `SCEP`
139+
4. For Version, choose `NDES 2008/2012` ([NDES for SCEP](https://docs.omnissa.com/bundle/CertificateAuthorityIntegrationsV2410/page/NDESforSCEP.html))
140+
5. Provide the SCEP URL from Step 1
141+
6. For Challenge Type, choose `Dynamic`
142+
7. Provide the Challenge Username and Password from Step 1
143+
8. No client certificate is needed
144+
9. Provide the SCEP Challenge URL from Step 1
145+
10. Choose **Show Advanced Options**
146+
- For SCEP Challenge Length, choose `32`
147+
11. Choose **Test Connection** and wait for a ✅ success modal
148+
3. Choose **Save and Add Template**
149+
150+
#### Add a Workspace ONE certificate request template
151+
152+
A new modal screen will be presented with the empty Request Template configuration
153+
154+
1. Provide a name for the Template, e.g. `Smallstep Agents`
155+
2. For Certificate Authority, choose the Smallstep CA you just connected
156+
3. For the subject name, use a value of `CN={DeviceUuid}`
157+
4. For Private Key Length, use 2048
158+
5. For Private Key Type, choose both Signing and Encryption
159+
6. Add a new SAN Type of type URL, and set the value to `deviceid://{DeviceUuid}`
160+
7. For Automatic Certificate Renewal, choose Enabled
161+
- Pick an appropriate Auto Renewal Period (5 days is common)
162+
8. Ensure Publish Private Key is Disabled
163+
9. Choose **Save**
164+
165+
#### Create a Windows Profile
166+
167+
1. In Workspace One UEM,
168+
1. Go to Resources → Profiles.
169+
2. Click Add, and pick Add Profile from the drop-down
170+
3. Click Windows, and then select Windows again
171+
4. Click Device Profile
172+
5. Under General, Provide a name (e.g. “Smallstep Device Enrollment”)
173+
1. Select the All Devices group in the Smart Groups dropdown
174+
2. Other options can be left as-is
175+
3. Optionally, click the View Device Assignment button to see the devices to which the profile will be distributed
176+
6. Add a Credential by clicking the **Configure** button , and set the following settings:
177+
1. Credential Store: Defined Certificate Authority
178+
2. Certificate Authority: Choose the CA connection you created earlier
179+
3. The certificate template should be selected automatically. If not, select an appropriate one.
180+
4. Key Location: TPM Required
181+
5. Certificate Store: Personal
182+
7. Click Save and Publish to finalize the configuration of the profile.
183+
8. A modal screen will be shown with the devices to which the profile will be distributed. Click Publish if the assignment looks OK.
184+
185+
### Confirmation
186+
187+
There's two ways to confirm installation on an endpoint:
188+
189+
- In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp.

0 commit comments

Comments
 (0)