DEV Community

Cover image for Zero-touch macOS onboarding with ADE and Jamf
beefed.ai
beefed.ai

Posted on • Originally published at beefed.ai

Zero-touch macOS onboarding with ADE and Jamf

#programming
  • Get ABM and Jamf talking: tokens, APNs, and device assignments
  • Design ADE enrollment profiles that actually work at scale
  • Orchestrate post-enrollment installs and the order that prevents breakages
  • How I test, validate, and troubleshoot an ADE workflow
  • Zero-touch checklist, scripts, and Jamf API examples

Zero-touch onboarding removes human handoffs from device provisioning and turns delivery into a repeatable pipeline: a shipped Mac arrives configured, encrypted, and ready for work. Treat ADE + Jamf Pro as the provisioning pipeline you must instrument, monitor, and maintain like any other critical service.

When onboarding still requires a technician to touch every machine you see the same symptoms: delayed time-to-productivity, inconsistent security posture (unencrypted disks, missing SSO), spikes in helpdesk tickets, and invisible drift across sites and vendors. You need a workflow that guarantees the same outcome every time the device powers on, and that requires building your ADE integration and Jamf PreStage configuration as a single, auditable pipeline.

Get ABM and Jamf talking: tokens, APNs, and device assignments

Why this matters: Automated Device Enrollment (ADE) is the foundation for supervised, locked-down macOS provisioning — it only works if Apple Business/School Manager (ABM/ASM), Apple Push Notification service (APNs), and Jamf Pro are configured correctly and kept current. ADE automates enrollment and supervision through ABM and requires a trust token exchanged between Jamf and Apple.

What to prepare and why

  • Create or confirm an Apple Business Manager account and assign an Administrator or Device Enrollment Manager role to the person who will manage tokens and device assignments. ABM is where devices are assigned to MDM servers and enrollment profiles are held.
  • Generate the Jamf public key, upload it to ABM, then download and import the server token (.p7m) back into Jamf Pro — that establishes the ADE instance in Jamf. This token is what lets Jamf see and claim devices that belong to your organization.
  • Obtain and maintain an APNs (Apple Push Notification service) certificate for Jamf Pro — APNs is required for MDM commands to reach devices and for management state to be maintained. Jamf Pro won’t operate correctly without a valid APNs certificate.
  • Assign devices to the MDM Server in ABM by serial number, order number, or reseller record so they land in the right PreStage in Jamf when first powered on. Devices added after-the-fact can be assigned, but a wipe is required to force enrollment at Setup Assistant.

Key operational rules

  • The server token (.p7m) that ABM issues to Jamf must be renewed on a regular cadence (Apple’s tooling and MDM vendors call this out as an annual renewal flow); track the Apple ID used to generate tokens so renewal survives staff churn.
  • Make APNs reachable from client networks: allow outbound to Apple’s IP block (17.0.0.0/8) on the APNs ports (device → APNs over TCP 5223; server → APNs over TCP 443/2197 as appropriate). Blocking these leads to intermittent or broken MDM behavior.

Quick step-by-step (high level)

  1. In Jamf Pro: Settings → Global Management → Automated Device Enrollment → download the public key.
  2. In ABM: Preferences → MDM Servers → Add MDM Server → upload the public key → Download the server token (.p7m) and save the generating Apple ID.
  3. In Jamf Pro: Upload the .p7m token to create your ADE instance and verify the sync.
  4. Upload or renew your APNs certificate via Jamf Pro (use the documented Jamf flow that walks you to Apple’s Push Certificates Portal).
  5. Assign devices in ABM to your MDM server and create a corresponding PreStage Enrollment in Jamf.
Artifact What it is Renewal / Note
server token (.p7m) ABM ↔ MDM trust token used to sync devices Renew annually; store generating Apple ID.
APNs certificate Push channel for MDM (Jamf ↔ Apple ↔ device) Expires annually; renew before expiry to avoid management loss.
PreStage Enrollment Jamf-side ADE profile that customizes Setup Assistant Created per use-case/site; scope to ABM-assigned devices.

Important: ADE enrollment triggers only from out-of-box or factory-reset devices — any previously active device must be wiped to pick up its PreStage configuration.

Design ADE enrollment profiles that actually work at scale

PreStage enrollment is where the user experience and the technical guarantees meet. The PreStage is Jamf’s control-plane for ADE that determines Setup Assistant behavior, local account creation, and what installs during OOBE. Configure it deliberately and conservatively.

What to decide up-front

  • Authentication model: choose whether devices enroll with user affinity (user signs in during Setup Assistant) or without user affinity (device is userless / shared). This choice changes how SSO and conditional access integrate.
  • Account creation pattern: Jamf can create a managed local admin before the Setup Assistant completes, or you can Skip Account Creation and use a tool like Jamf Connect to create the user at first login. Each pattern has trade-offs for SecureToken and FileVault workflows.
  • Setup Assistant steps to skip: skipping everything is tempting, but skipping all screens can create race conditions where the MDM hasn’t applied critical profiles before the user’s first login. Avoid skipping all steps when you need pre-login installations (SSO, disk encryption enrollment, or bootstrap-token dependent actions). Jamf specifically recommends not skipping all steps when you must guarantee pre-login software delivery.

Practical PreStage payloads you will use

  • General: name, site, description, Automatically assign new devices (useful for automatic on-boarding as orders are delivered).
  • Account Settings: create/hide a local admin or skip account creation for Jamf Connect flows.
  • Configuration Profiles: Wi-Fi provisioning, network proxies, certificates (root CA), MDM payloads. Upload these before scoping PreStage.
  • Enrollment Packages: attach installers (Jamf Connect, company CA certs) to a PreStage so they run early; be conservative about package priority — Jamf installs higher-priority packages first.

Contrarian, pragmatic insights

  • Minimalism wins during a rollout: start with a PreStage that only sets basic Setup Assistant behavior and Wi‑Fi so you can validate the device assignment and MDM handshake. Then add profiles and packages in small increments and re-test. Jamf’s troubleshooting guidance intentionally recommends creating a new minimal PreStage to isolate failures.
  • Avoid creating a single “kitchen-sink” PreStage that tries to do everything for every site; split PreStages by persona (lab, remote worker, kiosk) or by site so you can iterate safely.

Orchestrate post-enrollment installs and the order that prevents breakages

Onboarding isn’t finished when the MDM profile is installed; it’s finished when the device has the required profiles, tokens, and applications in the correct state. The order of operations matters.

Recommended provisioning sequence (trusted, repeatable)

  1. ADE enrollment → MDM profile installs during Setup Assistant (automatic).
  2. Network and certificate profiles (Wi‑Fi, corporate proxy, root CAs) so subsequent connections succeed.
  3. Escrowed bootstrap token and FileVault configuration — ensure FileVault profile or policy runs early so disk encryption is enabled quickly and recovery keys are escrowed. Bootstrap/secure token flows require ADE + supervision.
  4. Identity and SSO agents (Jamf Connect or other SSO) installed/configured before the user reaches the login window if you need SSO-created local accounts. Jamf advises not skipping Setup Assistant steps if you rely on these pre-login installs.
  5. Endpoint protection and monitoring agents after the bootstrap token/CA certs are in place — AV installers and kernel-extension helpers often require user consent or additional MDM capabilities that are addressable only after the right tokens/profiles are present.
  6. Productivity apps and nonessential installs last.

How to execute this in Jamf

  • Use PreStage’s Enrollment Packages to stage packages that should run during OOBE; Jamf supports package priority rules so you can control sequence.
  • Use policy triggers (enrollmentComplete, custom triggers, recurring check‑ins) to chain post‑enrollment tasks when packages need to wait for the Jamf binary to be present. Community and Jamf content show common patterns where an OOB script signals when to run follow‑ups.

Example rationale from experience: shipping Jamf Connect before the user sees the login window avoids password-reset friction and reduces helpdesk tickets, but it requires not skipping the privacy or Apple ID screens in the Setup Assistant so the installer can run correctly. Jamf documentation and deployment guides highlight this trade-off.

How I test, validate, and troubleshoot an ADE workflow

Testing and a short validation loop catch the kinds of timing and network failures that break rollouts. Use small pilots, deterministic tests, and repeatable diagnostics.

A pragmatic test plan

  • Test devices: pick 10 devices that represent the broadest variance (model types, Apple silicon vs Intel, T2 vs non-T2). Use fresh devices or factory-reset devices for tests.
  • Network varieties: test on corporate Wi‑Fi, a guest VLAN (to simulate constrained policies), and a mobile hotspot — many enrollment failures trace back to captive portals, firewalls, or proxies. Jamf recommends hotspot testing to bypass network filtering during troubleshooting.
  • Minimal PreStage proof: create a new PreStage with a minimal payload (Wi‑Fi + MDM) and scope a single serial — confirm ADE works. If minimal PreStage succeeds, add the next payload and re-test. Jamf troubleshooting explicitly recommends this.

Fast commands and checks to run on a test Mac

  • Check enrollment activation from the device (macOS terminal): sudo profiles renew -type enrollment — this triggers the enrollment renewal flow for non-ADE re-enroll cases and helps validate server reachability.
  • Validate bootstrap token presence: sudo profiles status -type bootstraptoken and sudo profiles validate -type bootstraptoken (commands exist on macOS for token workflows; Apple docs describe bootstrapping and MDM escrow).
  • Check SecureToken status for a user: sysadminctl -secureTokenStatus <shortname> (useful when debugging FileVault behaviors).
  • Tail Jamf logs for live feedback: tail -f /var/log/jamf.log and inspect /var/log/install.log for package failures; these local logs will show package install errors and timing information. Community and tooling commonly use these logs to diagnose stuck policies.

A compact troubleshooting checklist (symptom → likely cause → action)

Symptom Likely cause Quick remediation
Device shows “assigned — pending sync” in Jamf PreStage Token sync or ABM assignment delay Reassign device in ABM, wait 5–10 min, then force a sync in Jamf; confirm server token is not expired.
Setup Assistant ends but policies didn’t run Setup Assistant skipped critical steps or network blocked Recreate a PreStage that does not skip TODO steps; test on hotspot.
Jamf commands don’t reach device / no inventory updates APNs certificate expired or outbound blocked Check APNs cert expiry in Jamf; verify network allows 17.0.0.0/8 on APNs ports.
FileVault not enabled / no SecureToken No bootstrap token escrowed Confirm ADE + supervision; check bootstrap escrow status and run profiles install -type bootstraptoken if necessary.

Jamf-specific troubleshooting references and validation steps are documented and include exactly these checks: APNs validity, ADE token state, PreStage scoping, and creating a minimal PreStage to isolate failing payloads. Follow the vendor checklist and capture the sequence that fails — that sequence is the root cause.

Zero-touch checklist, scripts, and Jamf API examples

A condensed operational checklist (use in runbooks)

  1. ABM: account validated, Administrator + Device Enrollment Manager roles assigned, organization verified.
  2. Jamf Pro: APNs certificate uploaded and valid, Automated Device Enrollment instance created and .p7m uploaded, PreStage(s) created and scoped.
  3. Profiles & packages: Wi‑Fi, proxy, CA certs, and critical profiles uploaded; Jamf Connect (or SSO agent) packaged and attached where required.
  4. Security: FileVault profile/policy configured, LAPS (or similar) in place for local admin, bootstrap token escrow validated on test devices.
  5. Networking: APNs ports and Apple ranges whitelisted or tested via hotspot; real-net tests completed.
  6. Pilot: onboard 10 representative devices, validate every step, capture logs, iterate.

Command snippets and examples

  • Trigger a manual enrollment renewal on macOS (helpful to force a device to fetch profiles in non-ADE re-enroll workflows): 
# Run on the Mac under an admin session
sudo profiles renew -type enrollment
Enter fullscreen mode Exit fullscreen mode

Reference: Intune/ADE workflows document this command for triggering enrollment renewal flows on macOS.

  • Check bootstrap token status (macOS supports profiles bootstraptoken verbs and Apple documents bootstrap behavior): 
sudo profiles status -type bootstraptoken
sudo profiles validate -type bootstraptoken
Enter fullscreen mode Exit fullscreen mode

Reference: Apple Platform Security and community guidance show how bootstrap tokens are generated and escrowed during ADE enrollment.

  • Jamf Pro API: obtain a bearer token, find computer ID by serial, and then take actions (example uses jq to parse JSON; adapt to your environment). This pattern is the canonical modern approach (Jamf Pro API v1 + token). 
#!/usr/bin/env bash
# Variables
JAMF_URL="https://your-jamf.example.com"
API_USER="api-account"
API_PASS="supersecret"
SERIAL="C02ABCDEF123"

# 1) Get Bearer Token
auth_resp=$(curl -s -u "${API_USER}:${API_PASS}" \
  -X POST "${JAMF_URL}/api/v1/auth/token" \
  -H "accept: application/json")

TOKEN=$(echo "$auth_resp" | jq -r '.access_token // .token // .accessToken')
if [[ -z "$TOKEN" || "$TOKEN" == "null" ]]; then
  echo "Failed to acquire token: $auth_resp"
  exit 1
fi

# 2) Lookup device by serial (Jamf Pro API filter approach)
device_json=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
  "${JAMF_URL}/api/v1/computers-inventory?filter=hardware.serialNumber==\"${SERIAL}\"" )

DEVICE_ID=$(echo "$device_json" | jq -r '.results.id // empty')
if [[ -z "$DEVICE_ID" ]]; then
  echo "Device not found for serial ${SERIAL}"
  exit 1
fi

echo "Found device ID: ${DEVICE_ID}"

# 3) Example action: call a Jamf API endpoint that requires device id (replace with desired endpoint)
# curl -s -H "Authorization: Bearer ${TOKEN}" -X POST "${JAMF_URL}/api/v1/devices/${DEVICE_ID}/some-action" -d '{}'
Enter fullscreen mode Exit fullscreen mode

Reference: Jamf docs and community posts describe using /api/v1/auth/token then querying /api/v1/computers-inventory with an RSQL filter to find a device by serial.

  • Sample profiles flow to escrow bootstrap token manually (use only during controlled recovery scenarios): 
# Create and install a bootstrap token (admin consent required)
sudo profiles install -type bootstraptoken
Enter fullscreen mode Exit fullscreen mode

Reference: Apple docs note that bootstrap tokens may be installed/escrowed by profiles when needed; ADE is the typical path.

A short, repeatable pilot plan

  • Stage 10 devices across different models and one remote/hotspot test. Run them through ADE with the minimal PreStage (Wi‑Fi + MDM), confirm enrollment and jamf.log events within 15 minutes, then add one additional payload and re-test. Use this fast fail/fast learn loop to detect timing race conditions before wide rollout.

Ship zero-touch onboarding as a pipeline: instrument token expirations, monitor APNs/MDM health, test network variants, and roll PreStage changes behind a staged pilot so you never break 100+ users at once. Adopt token renewal and log harvesting as routine operational tasks so the provisioning pipeline stays reliable and auditable.

Sources:
Use Automated Device Enrollment - Apple Support - Explanation of Automated Device Enrollment, eligibility, and ABM flow used to assign devices to MDM servers.

Creating a PreStage Enrollment - Jamf Pro technical papers - Details on PreStage payloads, enrollment customization, and Enrollment Packages.

Jamf Pro Device Enrollment Guide - Jamf’s requirements for APNs, ADE integration, and prerequisites for automated deployments.

Troubleshooting Automated Device Enrollment - Jamf Support - Practical diagnostic steps: check APNs, ADE token, PreStage scope, and the recommended minimal-PreStage isolation technique.

If your Apple devices aren't getting Apple push notifications - Apple Support - APNs network and port guidance, recommended IP ranges (17.0.0.0/8), and port list for reliable MDM.

Set up automated device enrollment (ADE) for macOS - Microsoft Intune documentation - Describes the server token creation/renewal flow, enrollment profile creation, and the note to track the Apple ID used for token renewal.

Managing FileVault in macOS - Apple Platform Security - SecureToken, Bootstrap Token behavior, and ADE/supervision requirements for bootstrap escrow and FileVault workflows.

Understanding Jamf Pro API roles and clients - Jamf blog / developer docs - Modern Jamf API authentication patterns (/api/v1/auth/token), bearer tokens, and API client guidance.

Top comments (0)