Skip to content

Commit c00756e

Browse files
tashiantashian
authored
Merge pull request smallstep#368 from smallstep/carl/jamf-pro
Add Jamf Pro tutorial [CON-198]
2 parents 7f7d4f7 + dba53da commit c00756e

File tree

3 files changed

+204
-2
lines changed

3 files changed

+204
-2
lines changed

‎manifest.json

+4
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@
3838
{
3939
"title": "Smallstep Agent for Linux",
4040
"path": "/platform/smallstep-agent.mdx"
41+
},
42+
{
43+
"title": "Connect Jamf Pro to Smallstep",
44+
"path": "/tutorials/connect-jamf-pro-to-smallstep.mdx"
4145
}
4246
]
4347
},

‎step-ca/cryptographic-protection.mdx

-2
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,6 @@ description: Store your CA private keys in hardware or in a cloud KMS
55
updated_at: March 26, 2024
66
---
77

8-
# Cryptographic Protection
9-
108
By default, `step-ca` stores its signing keys encrypted on disk.
119

1210
For security hardening,

‎tutorials/connect-jamf-pro-to-smallstep.mdx

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
title: Connect Jamf Pro to Smallstep
3+
html_title: Connect Jamf Pro to Smallstep
4+
description: Configure Jamf Pro to deploy the Smallstep Agent and distribute certificates and configuration to Mac clients.
5+
---
6+
7+
Smallstep can integrate with Jamf Pro to synchronize your device inventory, and enroll your fleet with Smallstep using the Smallstep Agent. In this document, we will configure your Jamf Pro instance for use with your Smallstep team.
8+
9+
# Prerequisites
10+
11+
You will need:
12+
13+
- A [Smallstep team](https://smallstep.com/signup)
14+
- A [Jamf Pro](https://www.jamf.com/products/jamf-pro/) tenant
15+
- A [package distribution point](https://learn.jamf.com/en-US/bundle/jamf-pro-install-guide-linux-current/page/About_Distribution_Points.html) configured in Jamf Pro
16+
17+
# Step-by-step instructions
18+
19+
### Create an API Client in Jamf Pro
20+
21+
This API client will allow Smallstep to read your Jamf device inventory and manage the webhooks necessary for ongoing inventory syncing.
22+
23+
1. In Jamf Pro, choose ⚙️ **Settings**
24+
2. Under the **System** tab, choose **API Roles and Clients**
25+
3. Add an **API Role**
26+
27+
Display name: Smallstep
28+
29+
For Privileges, choose:
30+
31+
- Read Mobile Devices
32+
- Read Computers
33+
- Webhooks: Create, Delete, Read, Update
34+
4. Next, in the **API Clients** tab, add a **Client**
35+
- Display name: Smallstep
36+
- API Roles: Smallstep
37+
- Enabled: Yes, choose Enable
38+
- Choose **Save**
39+
5. Choose **Generate client secret**
40+
6. Temporarily save the **Client ID** and **Client Secret**. You’ll use them in the next step.
41+
42+
### Connect Jamf to Smallstep
43+
44+
Let’s add the Jamf API credentials you just created to Smallstep.
45+
46+
1. In the Smallstep UI, go to the [**Device Management**](https://smallstep.com/app/?next=/settings/devices) tab in ⛭ **Settings**
47+
2. Under Jamf, choose ➕ **Connect**
48+
3. Enter the API credentials from Jamf
49+
4. Choose **Add Platform**. Your device inventory will start syncing from Jamf to Smallstep.
50+
5. Temporarily save the **Webhook URL**, **Username**, and **Password** presented.
51+
52+
### Configure a SCEP Enrollment webhook in Jamf Pro
53+
54+
For compatibility reasons, Smallstep may use ACME or SCEP for certificate enrollment. The SCEP Enrollment webhook allows Jamf to request a dynamic, short-lived challenge string from Smallstep during a SCEP request. The challenge string is injected into a [SCEP payload](https://developer.apple.com/documentation/devicemanagement/scep) for your clients to authenticate to Smallstep.
55+
56+
1. In Jamf Pro, choose ⚙️ **Settings**
57+
2. Under the **Global** tab, Choose **Webhooks**
58+
3. Add a new Webhook
59+
1. Display name: Smallstep
60+
2. Webhook URL: (details from step #2)
61+
3. Authentication Type: Basic
62+
1. Basic Authentication Username: (details from step #2)
63+
2. Basic Authentication Password: (details from step #2)
64+
3. Basic Authentication Verify Password: (details from step #2)
65+
4. Content Type: JSON
66+
5. Webhook Event: SCEPChallenge
67+
4. Choose **Save**
68+
69+
### Create an Agent Package for Distribution
70+
71+
In this step, you’ll upload the Smallstep agent package to Jamf’s distribution network.
72+
73+
1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg)
74+
2. In Jamf Pro, choose ⚙️ **Settings**
75+
3. Under the **Computer Management** tab, Choose **Packages**
76+
4. Add a new Package
77+
1. Display name: Smallstep Agent
78+
2. Filename: (upload from step #1)
79+
5. Choose **Save**
80+
81+
### Create an Agent Bootstrap Script
82+
83+
This step will install a script on your client devices that bootstraps the connection between your devices and Smallstep.
84+
85+
1. In Jamf Pro, choose ⚙️ **Settings**
86+
2. Under the **Computer Management** tab, Choose **Scripts**
87+
3. Add a new Script
88+
1. In the **General tab**, for **Display Name**: `Smallstep Agent Install`
89+
2. In the Script tab:
90+
- Mode: `Shell/Bash`
91+
- Content:
92+
93+
```console
94+
launchctl stop com.smallstep.launchd.Agent
95+
/Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent svc install
96+
```
97+
98+
4. Choose **Save**
99+
100+
### Create an Agent Installation Policy
101+
102+
Next, we’ll configure the Script we just created to run on your client devices.
103+
104+
1. In Jamf Pro, choose 💻 **Computers**
105+
2. Under the **Content Management** tab, choose **Policies**
106+
3. Add a new **Policy**
107+
1. Under Options → General:
108+
- Display name: Smallstep Agent
109+
- Trigger: Login
110+
- Execution Frequency: Ongoing
111+
112+
*Note: With this policy, the package will be installed at the device’s next check-in, typically within 15 minutes.*
113+
114+
2. Under Options → Packages → Configure
115+
- Choose the **Smallstep Agent** package you created earlier
116+
- Distribution Point: (choose desired distribution point)
117+
- Action: Install
118+
3. Under Options → Scripts → Configure
119+
- Add the **Smallstep Agent Install** script you created earlier
120+
4. Under Scope, select your desired policy scope. The agent will be installed on all devices in this scope.
121+
4. Choose **Save**
122+
123+
### Configure an Agent Enrollment Profile
124+
125+
In this step, we’ll tie everything together by configuring Jamf to distribute the Smallstep Agent.
126+
127+
1. In the Smallstep dashboard, choose **Certificate Manager**
128+
1. Select [Authorities](https://smallstep.com/app/?next=/cm/authorities)
129+
2. Select the **Smallstep Agents** authority
130+
3. Download the Root Certificate
131+
4. Under the Provisioners section of the page, choose the provisioner beginning with **`integration-jamf`**
132+
5. Temporarily save the **URL shown on the page, eg.** `https://agents.example.ca.smallstep.com/scep/integration-jamf-b967f507`
133+
2. In the Smallstep dashboard, choose ⚙️ **Settings**
134+
1. Temporarily save the **Team Slug** value
135+
3. In Jamf Pro, choose 🖥️ **Computers**
136+
4. Under the **Content Management** tab, Choose **Configuration Profiles**
137+
5. Add a new Configuration Profile
138+
1. Choose **Options → General**
139+
- Name: Smallstep
140+
2. Add a [**Managed Login Items** payload](https://support.apple.com/guide/deployment/managed-login-items-payload-settings-dep07b92494/web)
141+
- Rule type: **Bundle Identifier**
142+
- Rule value: `com.smallstep.Agent`
143+
3. Add a [**Certificate payload**](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/web)
144+
- Certificate Name: **Smallstep Agents Authority**
145+
- Certificate Option: **Upload**
146+
- Certificate Upload: (upload the Root certificate you downloaded earlier)
147+
- Allow all apps access: ☑️
148+
4. Add a [**SCEP payload**](https://support.apple.com/guide/deployment/scep-payload-settings-dep495a6d79/web)
149+
- URL: (paste the provisioner URL you saved earlier)
150+
- Name: Smallstep
151+
- Redistribute Profile: 7 days
152+
- Challenge Type: Dynamic
153+
- Key Size: 2048
154+
- Allow all apps access: ☑️
155+
5. Select Options → Application & Custom Settings → External Applications
156+
157+
Add new custom settings:
158+
159+
- Options → External Applications → Source: Custom Schema
160+
- Options → External Applications → Preference Domain: `com.smallstep.Agent`
161+
- Options → External Applications → Custom Schema
162+
1. Choose Add Schema
163+
2. Copy the following JSON in to the window and choose Save
164+
165+
```json
166+
{
167+
"title": "Smallstep Agent (com.smallstep.agent)",
168+
"description": "Configure settings for the Smallstep Agent.",
169+
"properties": {
170+
"TeamSlug": {
171+
"type": "string",
172+
"title": "Smallstep Details: Team",
173+
"description": "The slug for your organization's Smallstep team, available in the Smallstep dashboard under Settings.",
174+
"property_order": 10
175+
},
176+
"Certificate": {
177+
"type": "string",
178+
"title": "Smallstep (Debug): Certificate URI",
179+
"description": "A KMS URI that points to a certificate that can be used for agent bootstrapping.",
180+
"property_order": 10
181+
}
182+
}
183+
}
184+
```
185+
186+
- Options → External Applications → Custom Schema → Smallstep Details: Team: (paste the Team Slug you saved earlier)
187+
- Options → External Applications → Custom Schema → Smallstep Details: Certificate URI: `mackms:label=$PROFILE_IDENTIFIER;se=false;tag=`
188+
1. Finally, set the profile scope:
189+
1. Choose Edit
190+
2. Set the desired scope. This should mirror the scope you chose when creating the Policy in step 5.
191+
3. Choose Save
192+
193+
Your Smallstep team is now linked to Jamf. The devices that you scoped will receive a certificate and have the agent installed and running.
194+
195+
### Confirmation
196+
197+
There's two ways to confirm installation on an endpoint:
198+
- In the Smallstep UI, go to the device's profile page. In the **Device Registration** section, you'll see an **Enrolled At** timestamp.
199+
- Alternatively, on the device itself, run `/Applications/SmallstepAgent/Contents/MacOS/SmallstepAgent version` to see that the agent is installed. And, in **System Settings**, check **Login Items** to confirm that there is a **Smallstep Agent** entry.
200+

0 commit comments

Comments
 (0)