Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 18 Packages Projects Releases Wiki Activity
Files
600fbf461d35a013e1a23b01d2a31e9e895174c8
fleet/articles/apple-mdm-setup.md
T

17 KiB
Raw Blame History

Apple MDM setup

To turn on macOS, iOS, and iPadOS MDM features, follow the instructions on this page to connect Fleet to Apple Push Notification service (APNs).

To use automatic enrollment (aka zero-touch) features on macOS, iOS, and iPadOS, follow instructions to connect Fleet with Apple Business (AB).

To turn on Windows MDM features, head to this Windows MDM setup article.

Turn on Apple MDM

Apple uses Apple Push Notification service (APNs) APNs to authenticate and manage interactions between Fleet and hosts.

Apple requires that APNs certificates are renewed annually.

  • If your certificate expires, you must turn MDM off and back on for all Apple hosts. If this happens, configuration profile changes and other MDM commands will remain stuck in “Pending” until renewal.
  • When renewing, be sure to use the same Apple ID from year-to-year. If you don't, you will have to turn MDM off and back on for all Apple hosts. The recommended approach is to use a shared Apple Developer account to generate the APNs certificate to make sure it can be renewed regardless of an employee's availability.

How to connect Fleet to APNs:

  1. In Fleet, navigate to the Settings > Integrations > MDM page.
  2. Select Turn on for Apple (macOS, iOS, iPadOS) MDM.
  3. Select Download CSR to download a certificate signing request (CSR) for Apple Push Notification service (APNs).
  4. Sign in to Apple Push Certificates Portal. If you don't have an Apple Account, create one.
  5. In Apple Push Certificates Portal, select Create a Certificate, upload your CSR, and download your APNs certificate.
  6. Upload APNs certificate (.pem file) in Fleet.

Renew APNs

  1. In Fleet, navigate to the Settings > Integrations > MDM page.
  2. Select Edit next to Apple MDM turned on.
  3. Select Renew certificate and then select Download CSR to download a certificate signing request (CSR) for Apple Push Notification service (APNs).
  4. Sign in to Apple Push Certificates Portal.
  5. In Apple Push Certificates Portal, select Renew next to your certificate. Make sure that the certificate's Common Name (CN) matches the one presented in Fleet. If you choose a different certificate, you must turn MDM off and back on for all Apple hosts.
  6. Upload your CSR and download new APNs certificate.
  7. Upload APNs certificate (.pem file) in Fleet.

Apple Business (AB)

Available in Fleet Premium

Connect Fleet to your AB to allow automatic enrollment for company-owned and Account-driven User Enrollment for personal (BYOD) macOS, iOS, and iPadOS hosts.

Re-enrolling AB hosts

When an AB host re-enrolls in Fleet (e.g., after a wipe or OS reinstall), Fleet automatically:

  • Cancels pending MDM commands, script runs, and software installs
  • Clears completed commands, scripts, and software from the previous enrollment
  • Resets host labels

This means you do not need to delete an AB host from Fleet before re-enrolling it. Fleet handles clearing stale state automatically.

This automatic state clearing does not apply to hosts undergoing AB MDM migration. During migration, the host's existing state (labels, pending activity) is preserved to ensure a seamless transition from your previous MDM solution.

To connect Fleet to AB, you have to add an AB token to Fleet. To add an AB token:

How to connect Fleet to AB:

  1. In Fleet, navigate to the Settings > Integrations > MDM page.
  2. Under Apple Business (AB), select Add AB.
  3. Select Download public key to download a public key for AB.
  4. Sign in to Apple Business. If your organization doesn't have an account, create one.
  5. Select Devices > Management and select Add at the bottom of list.
  6. Enter a name for the server such as "Fleet" and upload the public key downloaded in step 3 and select Next.
  7. Download the service token and select Done.
  8. In the Default Device Assignment section, assign the newly created server as the default for your Macs, iPhones, and iPads. Then select Save.
  9. In Fleet, upload the service token (.p7m file) downloaded in step 8.

macOS, iOS, and iPadOS hosts listed in AB and assigned to a Fleet will sync to Fleet and appear in the Hosts view with the MDM status label set to "Pending".

When one of your uploaded AB tokens has expired or is within 30 days of expiring, you will see a warning banner at the top of page reminding you to renew your token.

Renew AB:

Token status is indicated in the Renew date column: tokens less than 30 days from expiring will have a yellow indicator, and expired tokens will have a red indicator.

  1. Sign in to Apple Business.
  2. Select Devices > Management and select your MDM server.
  3. Select the three dots and select Download Token.
  4. In Fleet, navigate to the Settings > Integrations > MDM page.
  5. Under Apple Business (AB) select Edit next to Company-owned (ADE) and personal (BYOD) enrollment..., and then find the token that you want to renew.
  6. Select the Actions > Renew for the token.
  7. Upload the token (.p7m file) downloaded in step 3.

Hosts that automatically enroll will be assigned to a default fleet. You can configure the default fleet for macOS, iOS, and iPadOS hosts:

  1. Create a fleet, if you have not already, following this guide.
  2. Navigate to the Settings > Integrations > MDM page and select Edit under Apple Business (AB).
  3. Select the Actions dropdown for the AB token you want to update, and then select Edit fleets.
  4. Select the default fleet for each platform, and select Save to save your selections.

If no default fleet is set for a host platform (macOS, iOS, or iPadOS), then newly enrolled hosts of that platform will be placed in "Unassigned".

A host can be transferred to a new (not default) fleet before it enrolls. In the Fleet UI, you can do this under Settings > Fleets.

Default automatic enrollment profile

When macOS, iOS, or iPadOS hosts automatically enroll through Apple Business, Fleet sends an automatic enrollment (ADE) profile to Apple that controls how the Setup Assistant behaves. If no custom profile is uploaded for a fleet, Fleet uses a built-in default profile.

The default profile sets options such as whether enrollment is mandatory, which Setup Assistant panes are skipped, and whether the MDM profile is removable. See the Setup Assistant pane options.

Where to view the default profile

  • Fleet UI: Navigate to Controls > Setup experience > Setup Assistant. When no custom profile is uploaded, you can select Download to download the default profile JSON that your Fleet instance is currently using.
  • API: GET /api/v1/fleet/enrollment_profiles/automatic/default

Stored once, never auto-refreshed

The default profile is stored once per Fleet instance — at the time of your first automatic enrollment registration with Apple — and is not refreshed by Fleet upgrades, by adding or removing AB tokens, or by any other normal operation. This means that even if a newer version of Fleet ships updated default values, existing Fleet instances will continue using the default profile that was originally stored.

Updating to Fleet's latest defaults

There is no in-product "reset to latest default" action today. If you want your Fleet instance to use newer default values introduced in a later Fleet release:

  1. Check the latest defaults by reviewing the REST API documentation or by checking a freshly created Fleet instance.
  2. Create a custom enrollment profile JSON containing the desired values. See the Setup Assistant section of the setup experience guide for instructions on creating and uploading a custom profile.
  3. Upload it via the Fleet UI (Controls > Setup experience > Setup Assistant > Add profile) or the API.

Turn on MDM on a host

Fleet supports manually turning on MDM for macOS hosts that are already enrolled in Fleet.

End users can turn on MDM from their Fleet Desktop > My device page.

Host is in Apple Business (AB)

If a macOS host is listed in AB:

  1. The end user will see a Turn on MDM banner at the top of their My device page.

  2. Clicking Turn on MDM opens a modal with a step-by-step instruction on how to turn on MDM on their host.

  3. After completing the steps, the host has MDM features turned on.

Host isn't in AB

If the host isn’t in AB, users can still turn on MDM:

  1. On the My device page, the end user sees the same Turn on MDM banner.

  2. Clicking Turn on MDM opens a new tab.

    • If IdP authentication is enabled, the end user is prompted to sign in with your organization’s identity provider (IdP).
    • If authentication is successful, or if IdP authentication is disabled, the end user is taken to a page with instructions to download the manual enrollment profile and install it on their macOS host.

Volume Purchasing Program (VPP)

Available in Fleet Premium

Connect Fleet to VPP to deploy Apple App Store apps to your hosts.

  1. In Fleet, select your avatar on the far right of the main navigation menu, and then Settings > Integrations > MDM.
  2. Under Apple Business (AB), select Add VPP next to Volume Purchasing Program (VPP).
  3. Sign in to Apple Business. If your organization doesn't have an account, select Sign up now.
  4. Head to Settings > Payments & Billing > Apps & Books and download the content token for the organization unit you want to use. Each token is based on an organization unit in Apple Business.
  5. Upload the content token (.vpptoken file) to Fleet.
  6. To assign the VPP token to a specific fleet, find the token in the table of VPP tokens. Select the Actions dropdown, and then select Edit fleets. Use the picker to select which fleet(s) this VPP token should be assigned to.

Renew VPP:

Token status is indicated in the Renew date column: tokens less than 30 days from expiring will have a yellow indicator, and expired tokens will have a red indicator.

  1. Navigate to the Settings > Integrations > MDM page
  2. Under Apple Business (AB), select Edit next to Volume Purchasing Program (VPP) and then find the token that you want to renew.
  3. Select the Actions > Renew for the token.
  4. Sign in to Apple Business.
  5. Head to Settings > Payments & Billing > Apps & Books and download your content token.
  6. Upload the content token (.vpptoken file) to Fleet.

Best practice

Most organizations only need one AB token and one VPP token to manage their macOS, iOS, and iPadOS hosts.

These organizations may need multiple AB and VPP tokens:

MSPs

For MSPs, the best practice is to have one AB and VPP connection per client.

The default fleets for each client's AB token will look like this:

  • macOS: 💻 Client A - Workstations
  • iOS: 📱🏢 Client A - Company-owned iPhones
  • iPadOS:🔳🏢 Client A - Company-owned iPads

Client A's VPP token will be assigned to the above fleets.

Enterprises that acquire

For enterprises that acquire, the best practice is to add a new AB and VPP connection for each acquisition.

These will be the default fleets:

Enterprise AB token:

  • macOS: 💻 Enterprise - Workstations
  • iOS: 📱🏢 Enterprise - Company-owned iPhones
  • iPadOS:🔳🏢 Enterprise - Company-owned iPads

The enterprises's VPP token will be assigned to the above fleets.

Acquisition AB token:

  • macOS: 💻 Acquisition - Workstations
  • iOS: 📱🏢 Acquisition - Company-owned iPhones
  • iPadOS:🔳🏢 Acquisition - Company-owned iPads

The acquisitions's VPP token will be assigned to the above fleets.

Umbrella organizations

For umbrella organizations (e.g., a hospital system or university) where each entity has its own purchasing authority, the best practice is to have one AB and VPP connection per entity.

The default fleets for each entity's AB token will look like this:

  • macOS: 💻 Entity A - Workstations
  • iOS: 📱🏢 Entity A - Company-owned iPhones
  • iPadOS: 🔳🏢 Entity A - Company-owned iPads

Entity A's VPP token will be assigned to the above fleets.

International organizations

For international organizations that manage hosts across multiple countries, the best practice is to have one AB and VPP connection per country. Apple Business and VPP tokens are tied to a specific country or region.

The default fleets for each country's AB token will look like this:

  • macOS: 💻 Country A - Workstations
  • iOS: 📱🏢 Country A - Company-owned iPhones
  • iPadOS: 🔳🏢 Country A - Company-owned iPads

Each country's VPP token will be assigned to the above fleets.

Simple Certificate Enrollment Protocol (SCEP)

Fleet uses SCEP certificates (1 year expiry) to authenticate the requests hosts make to Fleet. Fleet renews each host's SCEP certificates automatically every 180 days.

For manually enrolled devices, if SCEP certificate renewal fails, MDM will be turned off on the host. The user will need to re-enroll the device to restore MDM management.

Troubleshooting

Failed enrollments

If a host is restarted/shut down during macOS Setup Assistant, it will fail to enroll to Fleet. Failed enrollments also happen if Fleet instance is down for an upgrade. When this happens, sometimes hosts automatically restart setup. If that doesn't happen, the best practice is to remotely wipe the host if the host is connected to Wi-Fi. If it's not, you'll need physical access to reinstall macOS from Recovery.

Failed enrollments also happen when the automatic enrollment profile isn't assigned in AB. Fleet surfaces failed automatic enrollment profile assignments on each host's Host details page:

  1. If there is an active issue assigning a profile, a vital called AB issue will be on the Dashboard page. This will take you to a filtered list of hosts with AB issues.

  2. Select a host and click on the MDM status to view details.

If a host shows an assignment time but no push time, the push didn't happen. To resolve, restart the host or run sudo profiles renew -type enrollment for remediation. If that doesn't work, contact Fleet support. Customers may need to contact Apple support if an online host never has a push time.

How automatic enrollment profiles are assigned:

Fleet-AB-workflow

Re-enrolling AB hosts

When an AB host re-enrolls in Fleet (e.g., after a wipe or OS reinstall), Fleet automatically:

  • Cancels pending MDM commands, script runs, and software installs
  • Clears completed commands, scripts, and software from the previous enrollment
  • Resets host labels

This means you do not need to delete an AB host from Fleet before re-enrolling it. Fleet handles clearing stale state automatically.

This automatic state clearing does not apply to hosts undergoing AB MDM migration. During migration, the host's existing state (labels, pending activity) is preserved to ensure a seamless transition from your previous MDM solution.

For AB hosts, you do not need to delete the host from Fleet before re-enrolling. Fleet automatically clears pending and completed commands, scripts, software installs, and labels when the host re-enrolls. See Re-enrolling AB hosts.

Reference in New Issue View Git Blame Copy Permalink