Macos Mdm Deployment

---
name: macos-mdm-deployment
description: "macOS MDM deployment: Declarative Device Management (DDM), Apple Business Manager (ABM), Automated Device Enrollment (ADE), configuration profiles, restrictions, supervised mode, MDM migration, and Recovery Lock. Covers macOS 14 Sonoma through macOS 26 Tahoe. Use when: \"MDM\", \"Apple Business Manager\", \"ABM\", \"DEP\", \"ADE\", \"Automated Device Enrollment\", \"configuration profile\", \"mobileconfig\", \"DDM\", \"Declarative Device Management\", \"MDM migration\", \"Jamf\", \"Intune\", \"Kandji\", \"supervised\", \"Recovery Lock\". Do NOT use for Platform SSO/IdP authentication flows — use the `macos-platform-sso` skill. Do NOT use for general macOS administration — use the `macos` skill."
license: MIT
---

# MDM Deployment (macOS)

This skill covers macOS Mobile Device Management across macOS 14 Sonoma, macOS 15 Sequoia, and macOS 26 Tahoe. It provides deep knowledge of:

- MDM protocol stack: HTTP/2 command-response protocol, APNs push, check-in protocol, command channel
- Declarative Device Management (DDM): declarations, activations, assets, management objects, status channel
- Apple Business Manager (ABM): device enrollment, VPP/Apps & Books, Managed Apple IDs, IdP federation
- Automated Device Enrollment (ADE, formerly DEP): zero-touch provisioning, Setup Assistant customization
- Configuration profiles (.mobileconfig): payload types, signed profiles, installation and removal
- MDM restrictions (com.apple.applicationaccess): supervised-only restrictions, Tahoe DDM migration
- Supervised mode vs User Approved MDM (UAMDM): capability matrix, Apple Configurator workflows
- Bootstrap Token escrow: secure token grant, FileVault recovery key rotation, firmware actions
- MDM migration (macOS 26 Tahoe): vendor-to-vendor migration without wipe, ABM reassignment
- Recovery Lock: Apple Silicon recovery protection, MDM commands, verification
- Certificate-based device identity: SCEP enrollment, Secure Enclave-backed keys, mutual TLS
- MDM vendor integration: Jamf Pro, Microsoft Intune, Kandji, Mosyle

When a question is version-specific, note the relevant differences. When the version is unknown, provide general guidance and flag where behavior varies. For general macOS administration, see the `macos` skill. For SSO-specific enrollment, see the `macos-platform-sso` skill.

## How to Approach Tasks

Route by request type: **troubleshooting** → `references/diagnostics.md`; **architecture** → `references/architecture.md`; **best practices/config** → `references/best-practices.md`; **health check** → the diagnostic scripts; **migration planning** → `references/best-practices.md`.

**Identify the macOS version first** — DDM support level, available restrictions, PSSO integration, and migration capability all shift by version. Reason from the enrollment type (ADE vs UAMDM), supervision state, profile delivery method (legacy vs DDM), and certificate chain to isolate whether the fix is a profile change, DDM declaration update, ABM configuration, or enrollment remediation. Prefer the least-disruptive fix: profile update > re-enrollment > device wipe. Validate with `profiles status`, `log stream`, `app-sso` checks, and bootstrap token verification.

## Core Expertise

### MDM Protocol Stack

macOS MDM is built on an Apple-defined HTTP/2-based command-response protocol. The MDM server sends commands; the device executes and returns results. All communication is authenticated via client certificates.

Key protocol elements:
- **MDM Profile** -- Configuration profile with `com.apple.mdm` payload delivered at enrollment. Contains server URL, check-in URL, APNs topic, identity certificate, and server capabilities.
- **APNs Push** -- Server sends lightweight push notification via Apple Push Notification Service to wake the device. Device then polls the MDM server for pending commands.
- **Check-in Protocol** -- Device authenticates to `/checkin` endpoint (Authenticate, TokenUpdate, CheckOut messages).
- **Command Channel** -- Device polls `/mdm` endpoint, receives XML plist commands, executes, responds.

All MDM traffic is HTTPS (TLS 1.2 minimum, TLS 1.3 preferred). Device presents its MDM identity certificate for mutual TLS authentication. On Apple Silicon, the Secure Enclave backs the private key (non-exportable).

### Declarative Device Management (DDM)

DDM is a device-initiated, declarative protocol that replaces the server-push model with device-managed desired state.

| Dimension | Legacy MDM | DDM |
|---|---|---|
| Initiation | Server-initiated (push then poll) | Device-initiated (self-checks) |
| Model | Imperative commands | Declarative desired state |
| Status | Server must query device | Device reports proactively |
| Efficiency | High APNs/command volume | Event-driven, low overhead |
| Scalability | O(n) polls | Self-regulating |

DDM building blocks:
1. **Declarations** -- JSON documents with four subtypes: `configuration` (desired state), `activation` (binding to predicate), `asset` (data blobs), `management` (org metadata).
2. **Status Channel** -- Device sends structured JSON status reports proactively.
3. **Declaration Delivery** -- Server sends `DeclarativeManagement` MDM command to bootstrap DDM; device fetches manifest and individual declarations by token.
4. **Predicates** -- Activations can be conditional on status items (e.g., OS version).

**When to use which:**
- DDM preferred for: software update enforcement, configuration desired state, status monitoring.
- Legacy MDM still required for: app installation (VPP), certificate deployment (non-DDM), wipe, lock, profile removal.

#### macOS DDM Timeline
| macOS | DDM Support |
|---|---|
| 13 Ventura | Introduced for macOS (subset of declarations) |
| 14 Sonoma | Expanded declaration support, software update declarations GA |
| 15 Sequoia | Authentication policy declarations, PSSO declarations |
| 26 Tahoe | MDM migration, PSSO at Setup Assistant, DDM restrictions |

### Automated Device Enrollment (ADE)

ADE links devices purchased from Apple or authorized resellers to an organization's ABM account. At first boot (or after wipe), the device contacts `iprofiles.apple.com` and receives an MDM enrollment profile automatically.

**Zero-touch enrollment flow:**
```
Device powers on
  -> contacts albert.apple.com (activation)
  -> contacts iprofiles.apple.com (ADE profile lookup by serial)
  -> receives MDM enrollment profile
  -> contacts MDM server check-in endpoint
  -> MDM delivers configuration profiles and DDM declarations
  -> Setup Assistant completes (customized steps skipped)
```

ADE-enrolled devices are **supervised** by default, unlocking the full MDM restriction surface: silent app install, content filtering, always-on VPN, Activation Lock bypass, and more.

### Apple Business Manager (ABM)

ABM (business.apple.com) is Apple's web portal for enterprise device and content management:

- **Device Enrollment** -- Devices from Apple/resellers auto-appear linked to the organization's ACN. Manual add via Apple Configurator 2. Each device assigned to an MDM server.
- **Apps & Books (VPP)** -- Bulk app licensing. Device-assigned (no Apple ID needed) or user-assigned via Managed Apple IDs.
- **Managed Apple IDs** -- Org-controlled Apple IDs federated from IdP (Okta, Entra ID). Format: `user@appleid.org-domain.com`. Provisioned via SCIM.
- **IdP Federation** -- ABM delegates authentication to Microsoft Entra ID, Okta, or Google Workspace. Users authenticate with corporate credentials.

### Configuration Profiles

Configuration profiles (`.mobileconfig`) are XML plist files delivering settings to macOS. Installed by MDM or manually (with user approval for non-MDM).

Key payload types:
| Payload | Purpose |
|---|---|
| `com.apple.wifi.managed` | Wi-Fi network configuration |
| `com.apple.vpn.managed` | VPN (IKEv2, L2TP, per-app) |
| `com.apple.security.pkcs1` | Certificate installation |
| `com.apple.security.scep` | SCEP certificate enrollment |
| `com.apple.applicationaccess` | App and feature restrictions |
| `com.apple.mobiledevice.passwordpolicy` | Password policy |
| `com.apple.extensiblesso` | Platform SSO configuration |
| `com.apple.FDE` | FileVault 2 enablement |
| `com.apple.dnsSettings.managed` | Encrypted DNS (DoH/DoT) |
| `com.apple.security.firewall` | ALF firewall settings |

MDM-delivered profiles are signed and only removable by MDM command (or device wipe). User-installed profiles may be removable by the user.

### MDM Restrictions

The `com.apple.applicationaccess` payload controls feature availability:

| Key | Effect |
|---|---|
| `allowAppInstallation` | Block App Store installs (supervised) |
| `allowCamera` | Disable FaceTime camera |
| `allowAirDrop` | Disable AirDrop |
| `allowiCloudDocumentSync` | Block iCloud Drive sync |
| `allowScreenShot` | Block screenshots and screen recording |
| `allowBluetoothModification` | Prevent Bluetooth changes |
| `forceEncryptedBackup` | Force encrypted local backups |
| `allowEraseContentAndSettings` | Block erase in System Settings |

Many restrictions only take effect on supervised (ADE-enrolled) devices. In macOS 26 Tahoe, Apple deprecated several keys in favor of DDM `com.apple.configuration.restrictions.*` declarations.

### Supervised Mode

| Feature | UAMDM | Supervised (ADE) |
|---|---|---|
| Enrollment | OTA profile, manual | ADE/DEP, Apple Configurator |
| User consent | Required | Optional (skipped) |
| MDM profile removal | User can remove | Cannot remove without MDM |
| Supervision restrictions | Not available | Available |
| Activation Lock bypass | No | Yes (with ABM) |
| Silent app install (VPP) | User prompted | Silent |

Devices not purchased through Apple can be supervised using Apple Configurator 2 (requires USB, triggers wipe). Alternatively, Apple Configurator can add devices to ABM without wiping.

### Bootstrap Token

During ADE enrollment, the device generates a Bootstrap Token and escrows it to the MDM server:
- Allows MDM to authorize secure token grant for new users (critical for FileVault unlock)
- Enables MDM-initiated FileVault recovery key rotation
- Required for Apple Silicon firmware password management
- Required for authenticated software update downloads

Verify escrow:
```bash
sudo profiles status -type bootstraptoken
# Expected: "Bootstrap Token supported on server: YES"
#           "Bootstrap Token escrowed to server: YES"
```

### MDM Migration (macOS 26 Tahoe)

Tahoe introduces native vendor-to-vendor MDM migration without device wipe:
1. New MDM server sends migration command via ABM reassignment
2. Device contacts the new MDM server and re-enrolls
3. New identity cert, push cert topic, and profile set installed
4. Old MDM profiles removed; user data, apps, and FileVault intact
5. Bootstrap Token re-escrowed to new MDM server

Considerations: VPP apps may be orphaned unless reassigned. PSSO registration may need re-triggering. All DDM declarations from old MDM are removed.

### Recovery Lock (Apple Silicon)

MDM can set a Recovery Lock password preventing unauthorized access to macOS Recovery on Apple Silicon Macs:
- `SetRecoveryLock` -- Sets the password (supervised devices only)
- `VerifyRecoveryLock` -- Checks if correct password is set
- `ClearRecoveryLock` -- Removes the lock (requires current password)

Lost Recovery Lock password without MDM access requires DFU restore via Apple Configurator (destructive). Best practice: store password in MDM device record and rotate periodically.

## Troubleshooting Decision Tree

```
1. Identify the issue category
   +-- Enrollment failure
   |   +-- ADE not triggering --> Check ABM device assignment, iprofiles.apple.com reachability
   |   +-- SCEP failure --> Check CA template, SCEP server logs, clock skew
   |   +-- APNs push cert expired --> Renew via ABM/Apple Developer account
   |
   +-- Profile not applying
   |   +-- Check supervision state --> profiles status -type enrollment
   |   +-- Validate profile --> profiles validate -path /path/to/profile.mobileconfig
   |   +-- Check payload compatibility --> OS version vs payload requirements
   |
   +-- DDM declarations not activating
   |   +-- Verify MDM server DDM capability
   |   +-- Check log: subsystem == "com.apple.ManagedClient" AND message CONTAINS "declaration"
   |   +-- Confirm macOS version supports the declaration type
   |
   +-- Bootstrap Token not escrowed
       +-- profiles status -type bootstraptoken
       +-- Re-enroll if non-ADE; verify MDM server token support
```

## Common Pitfalls

**1. APNs push certificate expiry**
Device never wakes to poll MDM. Check expiry in MDM console; renew annually via ABM or Apple Developer account. Set calendar reminders.

**2. Clock skew causing enrollment failures**
MDM authentication uses certificates with validity windows. Clock skew exceeding 5 minutes causes TLS errors. Ensure NTP is configured before enrollment.

**3. Non-supervised device expecting supervised restrictions**
Many powerful restrictions only work on supervised (ADE) devices. UAMDM devices silently ignore supervised-only keys. Verify supervision state before deploying restriction profiles.

**4. Bootstrap Token not escrowed on non-ADE enrollment**
Profile-enrolled (non-ADE) devices may fail to escrow the Bootstrap Token if the MDM server is not trusted for secure token grant. This breaks FileVault recovery key rotation and new-user secure token provisioning.

**5. Using legacy MDM commands for DDM-migrated payloads on Tahoe**
macOS 26 Tahoe deprecates several `com.apple.applicationaccess` keys in favor of DDM declarations. MDM vendors must update payload delivery or restrictions silently fail.

## Reference Files

Load these when you need deep knowledge for a specific area:

- `references/architecture.md` -- MDM protocol, DDM building blocks, ABM, ADE, certificate identity. Read for "how does X work" questions.
- `references/best-practices.md` -- Zero-touch deployment, profiles, restrictions, MDM migration. Read for configuration and deployment planning.
- `references/diagnostics.md` -- Enrollment debugging, profile troubleshooting, log predicates. Read when troubleshooting.

## Diagnostic Scripts

Run these for rapid MDM assessment:

| Script | Purpose |
|---|---|
| `scripts/01-mdm-enrollment.sh` | Enrollment status, ADE, Bootstrap Token, push certificate |
| `scripts/02-profile-inventory.sh` | Installed profiles, payloads, restrictions, FileVault |
| `scripts/03-certificate-audit.sh` | System Keychain certs, MDM identity, expiring certs |
| `scripts/04-ddm-status.sh` | DDM declarations, activation, status reports, legacy vs DDM |

## Key Paths and Files

| Path | Purpose |
|---|---|
| `/var/db/ConfigurationProfiles/` | Installed profiles database |
| `/var/db/ConfigurationProfiles/Store/Principals/` | Per-profile data |
| `/Library/Managed Preferences/` | MDM-enforced preference files |
| `/private/var/db/MDMClientEnrollment.plist` | Enrollment record |
| `/Library/Application Support/com.apple.ManagedClient/` | MDM client support files |
| `/Library/Keychains/System.keychain` | System certificates and MDM identity |

## macOS MDM Feature Timeline

| Feature | macOS Version | Notes |
|---|---|---|
| DDM (macOS) | 13 Ventura | Subset of declarations introduced |
| DDM expanded | 14 Sonoma | Software update declarations, expanded configs |
| Platform SSO integration | 13 Ventura | PSSO profile delivered via MDM |
| PSSO Auth Policies | 15 Sequoia | FileVault/Login/Unlock policy declarations |
| DDM Restrictions | 26 Tahoe | Replaces some applicationaccess keys |
| MDM Migration | 26 Tahoe | Vendor-to-vendor without wipe |
| PSSO at Setup Assistant | 26 Tahoe | ADE + PSSO in one step |

## MDM Vendor Integration Notes

### Jamf Pro
- Full ADE, VPP, DDM support
- Extension Attributes for custom inventory
- Smart Groups for dynamic scoping
- Self Service app catalog

### Microsoft Intune
- ADE support via Apple MDM Push Certificate
- Compliance policies with Conditional Access
- DDM support expanding per release
- Company Portal for self-service

### Kandji
- Blueprint-based configuration
- Auto Apps for common app deployment
- Liftoff onboarding experience
- DDM-first approach for supported payloads

### Mosyle
- ADE and profile management
- Mosyle Manager and Mosyle Business tiers
- App deployment and patch management
- DDM support expanding

## Key Commands Quick Reference

```bash
# Enrollment status
sudo profiles status -type enrollment
sudo profiles show -type enrollment

# Bootstrap token
sudo profiles status -type bootstraptoken

# Profile management
sudo profiles show -all
sudo profiles show -type configuration
sudo profiles validate -path /path/to/profile.mobileconfig

# Managed preferences
sudo defaults read "/Library/Managed Preferences/com.apple.applicationaccess"

# MDM logs (real-time)
log stream --predicate 'subsystem == "com.apple.ManagedClient"' --level debug

# MDM logs (historical)
log show --predicate 'subsystem == "com.apple.ManagedClient"' --last 1h --level debug

# DDM declaration logs
log show --predicate 'subsystem == "com.apple.ManagedClient" AND message CONTAINS "declaration"' --last 2h

# FileVault status
fdesetup status

# Device information
system_profiler SPHardwareDataType
sw_vers -productVersion

# Certificate inspection
security find-certificate -a /Library/Keychains/System.keychain

# Software update status
softwareupdate --list
```