Converting Jamf Custom Schema JSON for Workspace ONE UEM
Overview
Background
Periodically, I see app vendors providing custom JSON schema files to help build app-specific configuration profiles for MDM (specifically Jamf). Workspace ONE UEM supports app-specific configuration, but currently via Custom Settings in an XML format. While many vendors also suppply a custom mobileconfig file or Custom Settings dictionary that can be used with Workspace ONE UEM, I hope in this post to show how any Workspace ONE admin can manually convert a Custom Schema JSON file to Custom Settings XML.
Example Custom JSON Schema
First, let's start with an example of a typical custom JSON schema. The example below comes from cmdSecurity, the company that makes cmdReporter (recently purchased by Jamf). While the actual JSON content is lengthy and scary-looking, the bits you need to actually create Custom Settings XML are easy to pick out.
Custom Schema JSON for cmdReporter
1{
2 "title": "cmdReporter Settings",
3 "description": "Domain: com.cmdsec.cmdreporter",
4 "options": {
5 "remove_empty_properties": true
6 },
7 "properties":
8 {
9 "AuditLevel":
10 {
11 "type": "integer",
12 "title": "AuditLevel",
13 "description": "Log Verbosity Level. Recommended: 1 or 2",
14 "enum": [1, 2, 3],
15 "enum_titles": [1, 2, 3],
16 "default": 1
17 },
18 "AuditEventLogVerboseMessages":
19 {
20 "type": "boolean",
21 "title": "AuditEventLogVerboseMessages",
22 "default": false,
23 "description": "Log messages cmdReporter deems non-critical. Recommended: false"
24 },
25 "AuditEventExcludedUsers":
26 {
27 "type": "array",
28 "description": "Users to exclude from audit logging. Recommended: None",
29 "title": "AuditEventExcludedUsers",
30 "options":
31 {
32 "infoText": "Key: AllowedEmailDomains"
33 },
34 "items":
35 {
36 "type": "string",
37 "title": "Excluded User",
38 "options":
39 {
40 "inputAttributes":
41 {
42 "placeholder": "dan"
43 }
44 }
45 }
46 },
47 "AuditEventExcludedProcesses":
48 {
49 "type": "array",
50 "title": "AuditEventExcludedProcesses",
51 "description": "Applications or processes to exclude from logging. Recommended: Only other security software",
52 "items":
53 {
54 "type": "string",
55 "title": "Excluded Processes",
56 "options":
57 {
58 "inputAttributes":
59 {
60 "placeholder": "/Applications/Security Tool.app"
61 }
62 }
63 }
64 },
65
66 "LogRemoteEndpointEnabled":
67 {
68 "type": "boolean",
69 "title": "LogRemoteEndpointEnabled",
70 "description": "Master switch for sending logs to remote destinations. Recommended: true",
71 "default": true
72 },
73 "LogRemoteEndpointURL":
74 {
75 "type": "string",
76 "title": "LogRemoteEndpointURL",
77 "description": "Full URL with port number where logs will be sent.",
78 "options":
79 {
80 "inputAttributes":
81 {
82 "placeholder": "https://company.splunk.server:443/services/collector/raw"
83 }
84 }
85 },
86 "LogRemoteEndpointType":
87 {
88 "type": "string",
89 "title": "LogRemoteEndpointType",
90 "description": "Switch which configuration is used for remote transmission. LogRemoteEndpoint(value) are additional configurations. Recommended: Splunk",
91 "enum": ["Syslog", "REST", "Kafka", "Splunk", "TLS", "AWSKinesis"],
92 "enum_titles": ["Syslog", "REST", "Kafka", "Splunk", "TLS", "AWSKinesis"],
93 "default": "Splunk"
94 },
95 "LogRemoteEndpointAWSKinesis":
96 {
97 "type": "object",
98 "title": "LogRemoteEndpointAWSKinesis",
99 "description": "Send logs directly to an AWS Kinesis stream",
100 "properties":
101 {
102 "AccessKeyID":
103 {
104 "type": "string",
105 "title": "AWS Access Key ID",
106 "description": "(Required) AWS Access Key ID",
107 "options":
108 {
109 "inputAttributes":
110 {
111 "placeholder": "EJNPQUNWGIJ..."
112 }
113 }
114 },
115 "SecretKey":
116 {
117 "type": "string",
118 "title": "AWS Secret Key",
119 "description": "(Required) AWS Secret Key",
120 "options":
121 {
122 "inputAttributes":
123 {
124 "placeholder": "vOQd2pqNMyNR3..."
125 }
126 }
127 },
128 "StreamName":
129 {
130 "type": "string",
131 "title": "AWS Kinesis Stream Name",
132 "description": "(Required) AWS Kinesis Stream Name (NOT ARN)",
133 "options":
134 {
135 "inputAttributes":
136 {
137 "placeholder": "cmdReporter"
138 }
139 }
140 },
141 "Region":
142 {
143 "type": "string",
144 "title": "Region",
145 "description": "(Required)",
146 "default": "us-east-1"
147 }
148 }
149 },
150 "LogRemoteEndpointKafka":
151 {
152 "type": "object",
153 "title": "LogRemoteEndpointKafka",
154 "description": "Configure certificate and topic for Apache Kafka",
155 "properties":
156 {
157 "TopicName":
158 {
159 "type": "string",
160 "title": "TopicName",
161 "description": "(Required) Kafka topic cmdReporter will publish to",
162 "default": "cmdReporter"
163 },
164 "TLSServerCertificate":
165 {
166 "type": "array",
167 "title": "TLSServerCertificate",
168 "description": "(Required) Common names for server certificate trust chain.",
169 "items":
170 {
171 "type": "string",
172 "title": "Certificate Common Name",
173 "options":
174 {
175 "infoText": "Maps to Kafka setting ssl.ca.location",
176 "inputAttributes":
177 {
178 "placeholder": "Apple Root CA - G2"
179 }
180 }
181 }
182
183 },
184 "TLSClientCertificate":
185 {
186 "type": "array",
187 "title": "TLSClientCertificate",
188 "description": "(Optional) common name of client certificate in system keychain.",
189 "options":
190 {
191 "infoText": "Maps to Kafka setting ssl.certificate.location",
192 "inputAttributes":
193 {
194 "placeholder": "server_name.company.com"
195 }
196 }
197 },
198 "TLSClientPrivateKey":
199 {
200 "type": "string",
201 "title": "TLSClientPrivateKey",
202 "description": "(Optional) PEM formatted client private key",
203 "options":
204 {
205 "infoText": "Maps to Kafka setting ssl.key.location",
206 "inputAttributes":
207 {
208 "placeholder": "-----BEGIN CERTIFICATE-----..."
209 }
210 }
211 }
212 }
213 },
214 "LogRemoteEndpointREST":
215 {
216 "type": "object",
217 "title": "LogRemoteEndpointREST",
218 "description": "REST or Splunk HEC settings. PublicKeyHash applies to both methods.",
219 "properties":
220 {
221 "PublicKeyHash":
222 {
223 "type": "string",
224 "title": "PublicKeyHash",
225 "description": "(Required) REST or Splunk HEC API key"
226 }
227 }
228 },
229 "LogRemoteEndpointTLS":
230 {
231 "type": "object",
232 "title": "LogRemoteEndpointTLS",
233 "description": "",
234 "properties":
235 {
236 "TLSServerCertificate":
237 {
238 "type": "array",
239 "title": "TLSServerCertificate",
240 "description": "(Required) Common names for server certificate trust chain.",
241 "items":
242 {
243 "type": "string",
244 "title": "Certificate Common Name",
245 "options":
246 {
247 "inputAttributes":
248 {
249 "placeholder": "Apple Root CA - G2"
250 }
251 }
252 }
253
254 }
255 }
256 },
257 "UnifiedLogPredicates":
258 {
259 "type": "array",
260 "title": "UnifiedLogPredicates",
261 "description": "Search terms that will be collected from the unified log systems.",
262 "items":
263 {
264 "type": "string",
265 "title": "Predicates",
266 "description": "Search terms that will be collected from the unified log systems.",
267 "options":
268 {
269 "inputAttributes":
270 {
271 "placeholder": "(subsystem == \"com.apple.securityd\")"
272 }
273 }
274 }
275 },
276 "LicenseEmail":
277 {
278 "type": "string",
279 "title": "LicenseEmail",
280 "description": "(Required)",
281 "placeholder": "[email protected]"
282 },
283 "LicenseExpirationDate":
284 {
285 "type": "string",
286 "title": "LicenseExpirationDate",
287 "description": "(Required) Format: 01/20/2020",
288 "placeholder": "01/20/2020"
289 },
290 "LicenseKey":
291 {
292 "type": "string",
293 "title": "LicenseKey",
294 "description": "(Required)",
295 "placeholder": "asdfh38chdj..."
296 },
297 "LicenseType":
298 {
299 "type": "string",
300 "title": "LicenseType",
301 "enum": ["Trial", "Annual"],
302 "enum_titles": ["Trial", "Annual"],
303 "default": "Annual",
304 "description": "(Required)"
305 },
306 "LicenseVersion":
307 {
308 "type": "string",
309 "title": "LicenseVersion",
310 "description": "(Required) Always leave at 1",
311 "default": "1"
312 },
313 "LogFileMaxNumberBackups":
314 {
315 "type": "integer",
316 "title": "LogFileMaxNumberBackups",
317 "description": "Maximum number of archived backups to keep before deleting oldest.",
318 "default": "10"
319 },
320 "LogFileMaxSizeMegaBytes":
321 {
322 "type": "integer",
323 "title": "LogFileMaxSizeMegaBytes",
324 "description": "Maximum log file size before rotating.",
325 "default": "50"
326 },
327 "LogFileOwnership":
328 {
329 "type": "string",
330 "title": "LogFileOwnership",
331 "description": "User and group ownership of log files",
332 "default": "root:wheel"
333 },
334 "LogFilePermission":
335 {
336 "type": "string",
337 "title": "LogFilePermission",
338 "description": "Octal permissions for live and archived log files.",
339 "default": "644"
340 },
341 "SecurityBaseline":
342 {
343 "type": "string",
344 "title": "SecurityBaseline",
345 "description": "Name of the security baseline to report on",
346 "enum": ["800-53_high","800-53_low","800-53_moderate","cnssi-1253","all_rules"],
347 "enum_titles": ["NIST 800-53_high","NIST 800-53_low","NIST 800-53_moderate","cnssi-1253","all_rules"],
348 "default": "all_rules"
349 },
350 "SecurityBaselineReportingInterval":
351 {
352 "type": "integer",
353 "title": "SecurityBaselineReportingInterval",
354 "description": "Number of minutes between security baseline reports.",
355 "default": "720"
356 },
357 "ProhibitedApps":
358 {
359 "type": "object",
360 "title": "ProhibitedApps",
361 "description": "Configure applications to be blocked from user sessions.",
362 "properties":
363 {
364 "PAExecutableNames":
365 {
366 "type": "array",
367 "title": "PAExecutableNames",
368 "description": "Process names to block from launching from a user session.",
369 "items":
370 {
371 "type": "string",
372 "title": "Executable Name",
373 "options":
374 {
375 "inputAttributes":
376 {
377 "placeholder": "fdesetup"
378 }
379 }
380 }
381
382 },
383 "PASigningIdentifiers":
384 {
385 "type": "array",
386 "title": "PASigningIdentifiers",
387 "description": "Process signing IDs to block from launching from a user session.",
388 "items":
389 {
390 "type": "string",
391 "title": "Executable App Signing ID",
392 "options":
393 {
394 "inputAttributes":
395 {
396 "placeholder": "com.apple.fdesetup"
397 }
398 }
399 }
400
401 },
402 "PATeamIdentifiers":
403 {
404 "type": "array",
405 "title": "PATeamIdentifiers",
406 "description": "Process team IDs to block from launching from a user session",
407 "items":
408 {
409 "type": "string",
410 "title": "Executable App Signing ID",
411 "options":
412 {
413 "inputAttributes":
414 {
415 "infoText": "This is the team ID for Wireshark as an example.",
416 "placeholder": "7Z6EMTD2C6"
417 }
418 }
419 }
420 }
421 }
422 }
423 }
424}
Yeah, there's a lot to unpack there. Or is there?
Step 1 - The Custom Settings Template
First, we start with the NSUserDefaults Custom Settings template. To this, we must modify the following:
- String Value for PayloadDisplayName (this can be whatever you want to show up in the Profiles preference pane)
- Sting Value for PayloadType (from the "Domain: " line in the schema - this is the App's defaults domain)
- String Value for PayloadUUID (any UUID created by typing uuidgen in Terminal.app)
- String Value for PayloadIdentifier (a combination of the PayloadType.UUID)
1<dict>
2 <key>PayloadDisplayName</key>
3 <string>com.cmdsec.cmdreporter Settings</string>
4 <key>PayloadEnabled</key>
5 <true/>
6 <key>PayloadIdentifier</key>
7 <string>com.cmdsec.cmdreporter.A216A1AD-6B96-497A-B6CF-3E167318B127</string>
8 <key>PayloadType</key>
9 <string>com.cmdsec.cmdreporter</string>
10 <key>PayloadUUID</key>
11 <string>A216A1AD-6B96-497A-B6CF-3E167318B127</string>
12 <key>PayloadVersion</key>
13 <integer>1</integer>
Step 2 - Adding the Custom Settings Key-Value Pairs
Each Key-Value Pair in the Custom Settings XML results from a JSON Property and Type. Proceeding down the schema file, you'll use these JSON objects to build a list of key-value pairs. A few instructions to note:
- The
"properties":{key means you're about to see a list of<key>names. In other words, substitute"properties":{for the XML<dict></dict>nodes. - An
objecttype with multiple properties results in a<key>where the value is a<dict>of multiple key-value pairs. - An
arraytype with anoptionskey anditemstypes results in a<key>where the value is an<array>of<type>(e.g. one or more values). - A
stringtype withenumvalues requires the use of one of the specific enumerated values. You cannot use an arbitrary string value.
Converting Object Types
For example, take the property LogRemoteEndpointKafka:
1 "LogRemoteEndpointKafka":
2 {
3 "type": "object",
4 "title": "LogRemoteEndpointKafka",
5 "description": "Configure certificate and topic for Apache Kafka",
6 "properties":
7 {
8 "TopicName":
9 {
10 "type": "string",
11 "title": "TopicName",
12 "description": "(Required) Kafka topic cmdReporter will publish to",
13 "default": "cmdReporter"
14 },
15 "TLSServerCertificate":
16 {
17 "type": "array",
18 "title": "TLSServerCertificate",
19 "description": "(Required) Common names for server certificate trust chain.",
20 "items":
21 {
22 "type": "string",
23 "title": "Certificate Common Name",
24 "options":
25 {
26 "infoText": "Maps to Kafka setting ssl.ca.location",
27 "inputAttributes":
28 {
29 "placeholder": "Apple Root CA - G2"
30 }
31 }
32 }
33
34 },
35 "TLSClientCertificate":
36 {
37 "type": "array",
38 "title": "TLSClientCertificate",
39 "description": "(Optional) common name of client certificate in system keychain.",
40 "options":
41 {
42 "infoText": "Maps to Kafka setting ssl.certificate.location",
43 "inputAttributes":
44 {
45 "placeholder": "server_name.company.com"
46 }
47 }
48 },
49 "TLSClientPrivateKey":
50 {
51 "type": "string",
52 "title": "TLSClientPrivateKey",
53 "description": "(Optional) PEM formatted client private key",
54 "options":
55 {
56 "infoText": "Maps to Kafka setting ssl.key.location",
57 "inputAttributes":
58 {
59 "placeholder": "-----BEGIN CERTIFICATE-----..."
60 }
61 }
62 }
63 }
64 },
The <key> comes from the JSON name (e.g. "LogRemoteEndpointKafka":) but with leading and ending punctuation removed. As mentioned earlier, the "properties":{ key is changed out for the XML <dict></dict> nodes. Finally, we build the remaining key-value pairs within the dictionary using each JSON name (as the key), and the placeholder value in each type (optionally as arrays).
To make it easier to read, here's the pieces that you need to be picking out:
1 "LogRemoteEndpointKafka":
2 {
3 <snip>
4 "properties":
5 {
6 "TopicName":
7 {
8 "type": "string",
9 <snip>
10 "default": "cmdReporter"
11 },
12 "TLSServerCertificate":
13 {
14 "type": "array",
15 <snip>
16 "type": "string",
17 <snip>
18 "placeholder": "Apple Root CA - G2"
19 }
20 }
21 }
22 },
23 "TLSClientCertificate":
24 {
25 "type": "array",
26 <snip>
27 <snip>
28 "placeholder": "server_name.company.com"
29 }
30 }
31 },
32 "TLSClientPrivateKey":
33 {
34 "type": "string",
35 <snip>
36 "placeholder": "-----BEGIN CERTIFICATE-----..."
37 }
38 }
39 }
40 }
41 },
The Custom Settings XML output would look similar to:
1<key>LogRemoteEndpointKafka</key>
2<dict>
3 <key>TopicName</key>
4 <string>cmdReporter</string>
5 <key>TLSServerCertificate</key>
6 <array>
7 <string>Apple Root CA - G2</string>
8 </array>
9 <key>TLSClientCertificate</key>
10 <array>
11 <string>server_name.company.com</string>
12 </array>
13 <key>TLSClientPrivateKey</key>
14 <string>-----BEGIN CERTIFICATE-----...</string>
15</dict>
Converting Array Types
For example, take the property AuditEventExcludedUsers:
1"AuditEventExcludedUsers":
2 {
3 "type": "array",
4 "description": "Users to exclude from audit logging. Recommended: None",
5 "title": "AuditEventExcludedUsers",
6 "options":
7 {
8 "infoText": "Key: AllowedEmailDomains"
9 },
10 "items":
11 {
12 "type": "string",
13 "title": "Excluded User",
14 "options":
15 {
16 "inputAttributes":
17 {
18 "placeholder": "dan"
19 }
20 }
21 }
22 },
The resulting custom settings XML would be as follows:
1 <key>AuditEventExcludedUsers</key>
2 <array>
3 <string>dan</string>
4 </array>
Putting It All Together
In the interest of time, I don't plan to convert the whole JSON Schema, but you can see how I've come up with a small snippet of the appropriate Custom Settings XML:
1<dict>
2 <key>AuditLevel</key>
3 <integer>1</integer>
4 <key>AuditEventLogVerboseMessages</key>
5 <false />
6 <key>AuditEventExcludedUsers</key>
7 <array>
8 <string>dan</string>
9 </array>
10 <key>AuditEventExcludedProcesses</key>
11 <array>
12 <string>/Applications/Security Tool.app</string>
13 </array>
14 <key>LogRemoteEndpointEnabled</key>
15 <false />
16 <key>LogRemoteEndpointKafka</key>
17 <dict>
18 <key>TopicName</key>
19 <string>cmdReporter</string>
20 <key>TLSServerCertificate</key>
21 <array>
22 <string>Apple Root CA - G2</string>
23 </array>
24 <key>TLSClientCertificate</key>
25 <array>
26 <string>server_name.company.com</string>
27 </array>
28 <key>TLSClientPrivateKey</key>
29 <string>-----BEGIN CERTIFICATE-----...</string>
30 </dict>
31 <key>AuditEventExcludedUsers</key>
32 <array>
33 <string>dan</string>
34 </array>
35</dict>
Final Thoughts
Converting the Schema by hand is tedious and potentially error-prone. Hopefully, converting these JSON Schema documents via automation will soon be made an easy (or not at all required) task.