Device Containment — Jamf Pro

Device Containment — Jamf Pro

Challenge locks Jamf-managed computers and mobile devices using the Jamf Pro API. For macOS locks, Challenge generates a 6-digit unlock PIN and returns it in the containment result.

Prerequisites

• A Jamf Pro instance with MDM-enrolled devices
• Administrator access to Jamf Pro
• Ability to create API roles and clients
• Device containment enabled in Challenge (Owner or Admin role)

Configuration Steps

1. Create an API Role in Jamf Pro

1. Log into your Jamf Pro instance as an administrator
2. Navigate to Settings → System → API roles and clients
3. Click New in the API Roles section
4. Give the API role a name (for example, Challenge Device Containment Role)
5. Grant the API role the following privileges:
   • Read Computers — inventory lookup by email, hostname, or serial
   • Read User — Classic API fallback when resolving devices by user email
   • Send Computer Remote Lock Command — send DEVICE_LOCK via /api/v2/mdm/commands
   • View Computer Device Lock Pin — read lock PIN state when needed
6. Save the API role

Note: Challenge uses a dedicated API client with this API role, which grants only the privileges above. That least-privilege approach means the integration does not require full Jamf Pro administrator rights on the automation principal.

2. Create an API Client

1. On the same API roles and clients page, click New in the API Clients section
2. Give the API client a name (for example, Challenge Device Containment)
3. Select the API role created in Step 1
4. Click Save and copy the Client ID and Client Secret

3. Configure the Connector in Challenge

1. In Challenge, open Integrations → Device Containment
2. Expand the Jamf Pro connector tile
3. Enter the following configuration:
   • Jamf server URL: Your Jamf Pro instance URL (for example, https://yourorg.jamfcloud.com)
   • API client ID: Paste the Client ID from Step 2
   • API client secret: Paste the Client Secret from Step 2
   • Lock screen message (optional): Text shown on the locked device screen
   • Lock screen phone number (optional): Contact number shown on the lock screen
4. Check Enable this integration
5. Click Save

API calls Challenge makes

Step	Method	Endpoint	Expected status
Auth	POST	/api/oauth/token	200
Lookup (email)	GET	/api/v1/computers-inventory?filter=userAndLocation.email=="..."	200
Lookup (hostname)	GET	/api/v1/computers-inventory?filter=general.name=="..."	200
Lookup (serial)	GET	/api/v1/computers-inventory?filter=hardware.serialNumber=="..."	200
Lock	POST	/api/v2/mdm/commands (commandType: DEVICE_LOCK)	201

Challenge may also query /api/v1/mobile-devices for mobile inventory and fall back to the Classic /JSSResource/users/email/{email} endpoint when needed.

Lookup formats

Lookup type	Value example
user_email	[email protected]
hostname	alice-mac.corp.example
serial_number	C02XXXX
provider_device_id	Jamf managementId

Lock PIN behavior

Jamf requires a PIN for macOS device lock. Challenge generates a random 6-digit PIN, sends it in the MDM command, and returns lock_pin in per-device result metadata. Store the PIN securely — analysts need it to unlock the device at the keyboard.

Troubleshooting

Symptom	Check
http_401	OAuth client ID/secret or API role
http_403	API role missing Read Computers, Read User, Send Computer Remote Lock Command, or View Computer Device Lock Pin
http_500 on lock	Device not MDM-managed or missing managementId
device_not_found	Email not assigned on Jamf device record

Related

• Device Containment
• Responder