Skip to content

Commit a45570c

Browse files
tashiantashian
committed
Workspace ONE docs
1 parent 60386e5 commit a45570c

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

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

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
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+
## 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:
30+
Choose API → REST on the left, and choose ✅ Read for the row “Devices”
31+
32+
![Workspace ONE API Panel](workspace-one/api-panel.png)
33+
34+
4. Choose **Save**
35+
36+
Next, we’ll create an OAuth client for Smallstep:
37+
38+
1. In Workspace ONE UEM, navigate to **Groups & Settings → Configurations** and find **OAuth Client Management** in the list.
39+
2. Choose **Add** and add a new client with a name of “Smallstep” and description of “Smallstep MDM Integration for Device Sync”
40+
3. For **Organization Group**, select the group most appropriate for managing your desired device inventory.
41+
4. For **Role**, choose **Smallstep**
42+
5. Choose **Save.**
43+
6. Copy the resulting client ID and secret value.
44+
45+
### 2. Configure Smallstep OAuth settings
46+
47+
In Smallstep, navigate to [Settings → Device Management](https://smallstep.com/app/?next=/settings/devices).
48+
49+
Configure a new Omnissa Workspace ONE Integration with the values you gathered above:
50+
51+
- The Workspace ONE UEM REST API URL for your tenant.
52+
- This URL is shown in UEM’s settings. Navigate to
53+
54+
**Groups and Settings** → **All Settings →** **System** → **Advanced** → **API** → **Rest API**
55+
56+
and copy the REST API URL from that page.
57+
58+
- 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)
59+
- The OAuth client ID and secret you saved in Step 1
60+
61+
After saving the Workspace ONE connection, you will see settings for your integration. Copy the following details for later:
62+
63+
- SCEP URL
64+
- SCEP Challenge URL
65+
- Challenge Basic Authentication Username
66+
- Challenge Basic Authentication Password
67+
68+
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.
69+
70+
### 3. Deploy and configure the Smallstep Agent
71+
72+
In this step, we’ll add the Smallstep Agent to Workspace One UEM for distribution to devices.
73+
74+
1. In Workspace One UEM,
75+
- Go to Resources → Native Apps.
76+
- Choose Add → Application File.
77+
- 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.
78+
- Choose **Continue**
79+
2. In the Add Application panel’s **Details tab**,
80+
- Set Supported Processor Architecture to `64-bit` (or `ARM64` if used)
81+
- For Minimum OS, select Windows 10 (10.0.15063)
82+
3. In the Add Application panel’s **Deployment Options** tab,
83+
- Set Install Context to **Device**
84+
4. FInally, choose **Save & Assign**
85+
86+
### For ARM64 devices
87+
88+
If you also are deploying to ARM-based devices, repeat these steps for the `arm64` MSI installer from the [releases page](https://github.com/smallstep/step-agent-plugin/releases/latest).
89+
90+
Workspace ONE will try to distribute *both* installers to both `arm64` and `amd64` devices. You’ll need to 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.
91+
92+
The Application Distribution Assignment page appears next.
93+
94+
1. Give the Assignment a name
95+
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.
96+
3. Select App Delivery Method: Auto
97+
4. Create the Assignment.
98+
5. Choose **Save**
99+
6. Choose **Publish** to begin distributing the app.
100+
101+
### Create a script for Smallstep Agent configuration
102+
103+
1. In Workspace One UEM, visit **Resources → Scripts**
104+
2. Choose **Add** and then **Windows**
105+
1. In the General tab, provide a name for the script, such as “Smallstep Agent Enrollment”
106+
2. On the Details tab, ensure the **Language** is “Poweshell” and the **Execution Context & Privileges** is “System Context”
107+
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.
108+
109+
```xml
110+
New-Item -Path "HKLM:\Software\Policies\Smallstep"
111+
Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "TeamSlug" -Value "<team-id>"
112+
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"
113+
```
114+
115+
4. In the Variables tab, click **Add**. Set the variable **Key** to `DEVICE_ID` and the variable **Value** to `{DeviceUuId}`
116+
117+
### 4. Configure Agent Enrollment Profiles
118+
119+
In this step, we’ll tie everything together by creating Windows policy to enroll devices using the Smallstep Agent.
120+
121+
### Gather required details
122+
123+
1. You’ll need the following values from when your configuration your Workspace ONE connection:
124+
- SCEP URL
125+
- SCEP Challenge URL
126+
- Challenge Basic Authentication Username
127+
- Challenge Basic Authentication Password
128+
129+
If you need to retrieve these again, you can always visit: [**Settings → Device Management](https://smallstep.com/app/?next=/settings/devices) → Omnissa Workspace ONE**
130+
131+
132+
### Add a Workspace ONE CA resource
133+
134+
For compatibility with Workspace ONE, Smallstep emulates the Microsoft ADCS’s Dynamic SCEP and NDES enrollment protocols.
135+
136+
1. In Workspace One UEM, visit **Resources → Certificate Authorities**
137+
2. Choose **+ Add**
138+
1. Provide a name for the CA connection, e.g. Smallstep Agents CA
139+
2. For Authority Type, choose `Microsoft ADCS`
140+
3. For Protocol, choose `SCEP`
141+
4. For Version, choose `NDES 2008/2012` ([NDES for SCEP](https://docs.omnissa.com/bundle/CertificateAuthorityIntegrationsV2410/page/NDESforSCEP.html))
142+
5. Provide the SCEP URL from Step 1
143+
6. For Challenge Type, choose `Dynamic`
144+
7. Provide the Challenge Username and Password from Step 1
145+
8. No client certificate is needed
146+
9. Provide the SCEP Challenge URL from Step 1
147+
10. Choose **Show Advanced Options**
148+
- For SCEP Challenge Length, choose `32`
149+
11. Choose **Test Connection** and wait for a ✅ success modal
150+
3. Choose **Save and Add Template**
151+
152+
### Add a Workspace ONE certificate request template
153+
154+
A new modal screen will be presented with the empty Request Template configuration
155+
156+
1. Provide a name for the Template, e.g. `Smallstep Agents`
157+
2. For Certificate Authority, choose the Smallstep CA you just connected
158+
3. For the subject name, use a value of `CN={DeviceUuid}`
159+
4. For Private Key Length, use 2048
160+
5. For Private Key Type, choose both Signing and Encryption
161+
6. Add a new SAN Type of type URL, and set the value to `deviceid://{DeviceUuid}`
162+
7. For Automatic Certificate Renewal, choose Enabled
163+
- Pick an appropriate Auto Renewal Period (5 days is common)
164+
8. Ensure Publish Private Key is Disabled
165+
9. Choose **Save**
166+
167+
### Creating a Windows Profile
168+
169+
1. In Workspace One UEM,
170+
1. Go to Resources → Profiles.
171+
2. Click Add, and pick Add Profile from the drop-down
172+
3. Click Windows, and then select Windows again
173+
4. Click Device Profile
174+
5. Under General, Provide a name (e.g. “Smallstep Device Enrollment”)
175+
1. Select the All Devices group in the Smart Groups dropdown
176+
2. Other options can be left as-is
177+
3. Optionally, click the View Device Assignment button to see the devices to which the profile will be distributed
178+
6. Add a Credential by clicking the **Configure** button , and set the following settings:
179+
1. Credential Store: Defined Certificate Authority
180+
2. Certificate Authority: Choose the CA connection you created earlier
181+
3. The certificate template should be selected automatically. If not, select an appropriate one.
182+
4. Key Location: TPM Required
183+
5. Certificate Store: Personal
184+
7. Click Save and Publish to finalize the configuration of the profile.
185+
8. A modal screen will be shown with the devices to which the profile will be distributed. Click Publish if the assignment looks OK.
186+
187+
### Confirmation
188+
189+
There's two ways to confirm installation on an endpoint:
190+
191+
- 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)