Automated Device Enrollment (ADE)

This was formerly known as the Device Enrollment Program (DEP).

Apple's Automated Device Enrolment

What

From inception known as Device Enrolment Programme (DEP), Apple's Automated Device Enrolment (ADE) is a zero touch enrolment method for Apple devices.

This article aims to cover the generic processes.

When/Why

Typically this process is used with new devices or those erased.

Registration

The basics:

Enrolment Profile

Enrolment Profile has options, e.g which Setup Assistant items are shown.  When an Enrolment Profile is associated with one or more devices, the Enrolment Profile is sent to Apple; differing Enrolment Profiles may be configured and associated with different devices.

Working with Apple’s Device Enrollment Program (DEP)

How

Enrolment Stages

Enrolment Profile delivery

When the device is first connected to a network, the device will initially communicate with Apple.  Apple observe the identity of the device and if there is an associated Enrolment Profile with this device, the Profile is sent to the device.

Once the Enrolment Profile is delivered, it will remain on the device, even if rebooted.  Only a subsequent erase of the device will remove the Enrolment Profile and the process be re-triggered from scratch.

A key item in the Enrolment Profile is the MDM Server URL.

image.png

Check-in

The device reads the MDM Server URL and the enrolment process can then begin.

Authentication

The next requirement from check-in is authentication.  

On initial check-in, FileWave server returns a 401 due to no authentication and then informs the device how to authenticate.

Local Authentication FileWave is configured with a local username and password encrypted on the FileWave Server (Default)
No Authentication FileWave Server is configured to allow devices to enrol with no authentication required
LDAP An LDAP server, e.g. Active Directory, is configured, allowing directory users to authenticate enrolment
IdP Okta, Google or Entra users may authenticate enrolment

Local and No authentication are configured through the server command line,  LDAP may be configured through FileWave Central, whilst IdP is configured through FileWave Anywhere.

Basic Authentication

image.png

IdP Authentication

IdP requires a special mention here due to the additional steps involved.

FileWave server informs the device with a URL to direct the authentication; the IdP.  The IdP custom authentication screen should be presented to the user and on entering details, if successful, the IdP uses the configured redirect, to contact the FileWave server to inform of success.

image.png

Redirects provided to IdP for connection with FileWave Server may be viewed from FileWave Anywhere, for example:

image.png

FileWave Server informs the IDP where to respond to the FileWave Server once complete.  The FileWave returned URL to send on the code from the device will be through port 20443 and includes the auth code as a parameter within the URL.

Federated Authentication

An extension of IdP, Federated Authentication is an offering from Apple, which allows Apple IDs/passwords to be synchronised with an IdP.  This is configured within Apple's Management portal; FileWave is not involved with this configuration.

https://support.apple.com/en-gb/guide/apple-business-manager/axmb19317543/web

Working with Apple’s Device Enrollment Program (DEP)

This section is for FileWave version 9.1 and above only. DEP only works with devices purchased from Apple authorized sources. For information on approved devices in DEP, see the following reference:
https://help.apple.com/deployment/business/

The features of DEP include:

DEP Workflow Overview

  1. IT signs up for DEP account (or accounts)
  2. Institution purchases devices via an authorized seller
  3. IT doesn't see devices in the online DEP list until the shipping confirmation arrives from Apple (prior to that, Apple doesn't know what serial numbers are going to be shipped)
  4. IT assigns the devices from the online DEP list to the FileWave MDM server by serial number (You can also assign defaults in ASM & ABM)
  5. Wait for the DEP list and the FileWave MDM list to synchronize (24hr default sync, or triggered manually in the DEP UI
  6. IT assigns DEP profiles to the serial numbers of the devices prior to arrival (Automatically Assign DEP profiles)
  7. Devices arrive and, at first boot, are auto-enrolled and configured as managed devices (macOS computers will auto-enroll if connected to the Internet for push notification and the MDM server for enrollment.)

For more information see: https://support.apple.com/en-us/HT204142

Configuring DEP with FileWave

This process is covered in VPP and DEP preferences

FileWave Client for OS X DEP

The macOS computers that are being brought into FileWave through Apple's DEP require a custom FileWave client installer. To be installed via MDM, the FileWave Client .pkg needs to be signed. The supported way is to generate your package via our web site, so you can pre-configure it (https://custom.filewave.com/py/custom_client_mac.py). When you have filled in the web form, you will get an email with a download link to the custom client installer package (.pkg). Download that custom installer, then go to your FileWave Admin/Preferences/Mobile to add the custom package to the FileWave server for use by macOS Clients.

"Use for initial enrollment only" is highly recommended. This means that FileWave will only attempt to install the PKG the first time a devices enrolls. If it is unchecked, and you upload a new PKG, FileWave will send this out via an APN immediately. This could cause existing devices to loose their configuration (like boosters)

Understanding devices and profiles for DEP

Once you have registered your FileWave Server with the DEP system, you can begin setting up your devices for automatic enrollment and management. You will be able to view a list of your devices along with certain characteristics of those devices, such as model number, color of the device, asset tag information, and serial number.

You will also be able to apply a "profile" to the device.

The "profile" in DEP is not the same as a management profile. Instead of a property list (plist), the DEP profile is a set of data formatted in JSON (JavaScript Object Notation) format. The profile is applied through Apple when the device is initialized. It will contain settings that you configure including:

The process for setting up your devices is done through the /Assistants/DEP Association Management… pane:
 
The DEP Associations pane looks similar to other FileWave windows with three sections. In this case, they are:

Security prerequisites for DEP

DEP uses Basic and Digest Authentication. Basic is for iOS v7.1(+) devices, and we implemented Digest Authentication for iOS v7.0.x devices. In order to configure up your FileWave MDM server for Digest Authentication, you need to use a separate command, similar to the fwcontrol mdm adduser command used for your MDM server configuration. The command is:

sudo fwcontrol mdm adddepuser <user_name>

The adddepuser command requires you to provide a user name in the command, and respond to the prompt to add a password for that user, then to confirm the password. This user name and password will be requested by the device during DEP enrollment. These commands are issued on the FileWave MDM server either directly or remotely through terminal services.

Authentication with LDAP

If you are using LDAP and DEP, you will have to use iOS v7.1.x(+) devices. The mdm_auth.conf.example_ldap_auth file we provide is based on basic authentication, while the default is using digest. If you have not already edited the mdm_auth.conf, then review the information in LDAP Preferences

Configuring DEP profiles

You create DEP profiles within the DEP Associations pane by clicking on the + button in the profile section of the window.


Here is a view of the DEP Profile creation window:

Information

This information will be set in the MDM profile once installed on the MDM device.

Options

These settings are for the key behaviors of the registered device:

Setup Assistant

Account (requires client running OS X v10.11+)

A feature in DEP is the ability to create a local administrator account in advance of a user being guided through creating their own local account. If you configure this pane with a local administrator account, then the user will be allowed to create a local account of their own; but it will be a non-admin user. The local admin account can be somewhat hidden (the home directory will still be in /Users/ but it will not show up in the Users and Groups System Preference pane).
If this pane is configured with only the local account setup, the user setting up the device will be guided through setting up a local administrator account of their own.

Note: Disallowing "Local Account Setup" During DEP enrollment may prevent your machines from completing their enrollment steps unless the local administrator account logs in on the machine.

Anchor Certs & Supervising Certs

The "Certs" tabs are for adding the necessary certificates to the device to allow trusted connections and specialized pairing permissions. The FileWave MDM server certificate is automatically added to the Anchor Certs list.


Device Naming

The devices being enrolled can have a rule-based name applied. In a 1:1 deployment with users authenticating with LDAP credentials, the device name can reflect an institutionally-derived naming convention punctuated by the user's name. This function is limited to supervised iOS devices running iOS 9+ and macOS computers running 10.11+.

See: DEP Naming for more information

Activation Lock

Apple provides an anti-theft feature called Activation Lock. When wiped and activated again, the device is locked and will require an Apple ID credential to be unlocked. FileWave can ease the process by escrowing a bypass code which can be used to bypass iCloud credentials. The code can either be entered manually or automatically, typically just before refreshing the device.

Activation Lock can be against:

In both cases, FileWave can escrow the key and use it to unlock the device during refresh. You can configure Activation Lock:

For DEP devices:

Use iCloud

Use your AMS/ABM account

Associations

Associating a DEP profile to a device (or set of devices) is done using the same drag & drop functions used in the other FileWave associations panes. You can drag a profile on top of a device, or select a set of devices and drag them on top of a profile. The associations will appear in the lower section of the DEP Associations window. The device will have the associated profile applied upon activation.

To automate see: Automatically Assign DEP profiles

End Result of DEP associations

The end result of associating DEP profiles to devices is that upon activation, the device will automatically become a FileWave Client with specific setup settings. You can have device Placeholders prepositioned in your FileWave Clients view, assigned to Groups, with Filesets ready to activate as soon as the device checks in. 

Add or Renewing your ADE (DEP) Account Token

Description

DEP is the optimal way to enroll your Apple devices. DEP enrollment is required for countless features and management tools. Once added, you will need to renew your DEP token every year.

If you're renewing your token, it's not necessary to re-upload the server certificate (steps 1, 2, 5 & 6) each time unless the cert has changed or you are receiving a FORBIDDEN error when syncing DEP.

Step-by-step guide

  1.  Download the DEP Certificate from FileWave Admin
  2.  Save the certificate "FileWave DEP" to your desktop.

FileWave Anywhere

Sources > DEP Accounts > '+' > Download

WebAdminDEP

FileWave Central

Preferences > VPP & DEP

3. Go to the relevant Apple DEP site, 
school.apple.com or business.apple.com

4. Once signed in, go to Preferences under your account name in the bottom left of ASM/ABM

5. Select the MDM Server that needs to be renewed and click edit

6. Under MDM Server settings, 'Upload New' MDM certificate

DEPAccount1.gif

7. Once saved, download the token from ASM/ABM

DEPAccount2.gif

8. Go back to FileWave Central and upload the token

NOTE: At the end of this step, If any attributes have changed in the token, note that the dialog in FW may not reflect the new values for 10 - 30 minutes. (i.e. Server Name) and that is normal.

Renewing Token

FileWave Anywhere

In Sources, under DEP Accounts, select the ellipses next to the correct DEP account and choose ‘Edit’. Select Browse and upload the Apple Token downloaded in step 7 of this document. Click Save.

DEPAccount3.gif

FileWave Central

In Preferences > VPP & DEP, select Configure Accounts and enter your password. Select the correct DEP account and select ‘Upload new Access Token’. upload the Apple Token downloaded in step 7 of this document and click Open. Now you can close this window.

DEPAccount4.gif

Adding New Token

FileWave Anywhere

In Sources, under DEP Accounts, select the '+' to the right. Steps 1 & 2 were completed earlier, so skip down to Step 3 and upload the Apple Token downloaded in step 7 of this document. Click Save.

DEPAccount5.gif

FileWave Central

In Preferences > VPP & DEP, select Configure Accounts and enter your password. Select the '+' on the bottom left of the Configure Accounts window and select the token downloaded in step 7 of this document. Click Save and close the window.

DEPAccount6.gif

9. After the token is uploaded, run a full DEP sync.

Perform full DEP sync

FileWave Anywhere

In the Sources tab, select the Sync icon next to DEP Account and choose Full Sync.

DEPAccount7.gif

FileWave Central

Go to Preferences > VPP & DEP. While holding down the option/alt key, press ‘Synchronize (full sync)’.

DEPAccount8.gif

You’re all set! If you renewed your token, you should see a new expiration date. If you added a new token, you can learn more about managing your devices with DEP and FileWave here: Apple DEP Enrollment.

DEP Naming

This article is for individuals who want to customize naming of DEP devices. It will cover placeholders and their ability to accept name, as well as using custom and built-in strings in the DEP profile.

Placeholders are most useful for new incoming devices where the name is highly customized. And where you want to use additional attributes like custom fields.

Placeholders

Step-by-step guide

  1. Generate a text file, ideally of serial numbers as one column and the custom name as the other.
    See Importing Computer Clients from a file and Enrolling Computer Clients
  2. Import any custom field values if needed
    See Custom Fields: Importing CSV for more information

Variables in the DEP profile

Step-by-step guide

  1. Generate a DEP profile
    See Working with Apple's Device Enrollment Program (DEP)
  2. In the naming tab of the DEP profile you can use any: 
    Built-in inventory variables (for a list of variables see Using variables in Apple iOS/macOS Profiles )
    Custom inventory variables, using the %custom_field.INTERNAL_NAME% (see more at Custom Fields )
  3. It would also be recommended that you create an automatic DEP rule to only assign this profile to devices that have the variables set: see the example in Automatically Assign DEP profiles

FileWave Foundry Video

Sign into FileWave Foundry and watch a video here regarding DEP Naming.

Automatically Assign DEP profiles

Starting in FileWave version 13.1.0 you now have the ability to automatically assign DEP profiles to devices.

Step-by-step guide

Start by opening up the DEP Profiles UI (Assistant → DEP Association Management), and verify you have profiles created. It is recommended that you have a highly generic rule that will work with all iOS and macOS devices, and then profiles for your needed situations.

Assign Default Rule

  1. Open the "Edit Assignment Rules" UI
  2. Choose a Default DEP Profile (Figure 1.1)
  3. Hit OK to save it

You can then choose between creating rules on simple things or advanced things: 

Assign based on model/operating system (Simple)

  1. Open the "Edit Assignment Rules" UI
  2. Hit the [+] to create a new profile rule
  3. Select your default profile for an OS (iOS in this example)
  4. Drag the DEP Devices / Operating System component from the left into the Criteria
  5. Set to "Contains" : "iOS" (See figure 2.1)
  6. Save
  7. Repeat again for "OS X" and "tv" as needed

Assign based on custom fields (Advanced)

  1. Create Custom fields (in this example "usage" and "location") 

    See Custom Fields for more information

    1. Use: Provided: Admin, Type: string, Restricted: True, Values: None (DEFAULT), Faculty, Student, Administration (See Figure 3.1)
    2. Location: Provided: Admin, Type: string, Restricted: True, Values: None (Default), Site A, Site B... (Figure 3.2)
    3. Take note of the "Internal Name" from the custom fields
  2. Open the DEP UI
  3. Hit the [+] to create a new DEP profile
    1. Use the internal name in naming (see Figure 3.3)

      See DEP Naming for more information

    2. Open the "Edit Assignment Rules" UI
    3. Hit the [+] to create a new profile rule
  4. Select the profile you just created
    1. You will now see the Custom Fields component on the left Component list
    2. Open it and bring in location and use
    3. set them both to is not None (Figure 3.4)

Excluding serials from Auto Rules

You will notice a column named "Excluded from automatic assignment" with True or False (Figure 4.1)

Figure 4.1 - Exclude Column

true - Device will not be included in automatic rules. Note: "true" is NOT applicable when manually clicking the "Apply Assignment Rules" button...when that button is clicked all rules will be applied for any selected devices (after confirmation prompt).  Selecting no devices infers ALL devices as selected.

false - Devices will be included in automatic rules, both automatically and when "Apply Assignment Rules" is triggered

true is the default for devices that were in your DEP list before an upgrade to 13.1 to protect those devices from changing before you have built new rules

 

Figure 1.1 - Default Rule

Figure 2.1 - iOS Simple Rule

Figure 3.1 - Custom Use

Figure 3.2 - Custom Location

Figure 3.3 - Custom Naming

Figure 3.4 - Custom Name Rule

Apple TV Automatic Advance (DEP)

Description

This recipe will walk you through the steps of enrolling an Apple TV HD 4th gen into FileWave with DEP utilizing the Automatic Advance setting.

This setting is only available if you are using an Apple TV HD 4th gen and FileWave v12. Recommended to use wired connection for Automatic enrollment.

In the steps below please remember do not set up the Apple TV manually in anyway or the Automatic Advance feature will not work.
This includes pairing the remote.
Touching anything stops the process.

Ingredients

Direction

  1. Go to the Assistants menu -> DEP Association Management

This opens the DEP Associations window

  1. Fill out as much of the profile as you need in the Options, Setup Assistant, and the Device Naming tabs. 

At the very least you will need to have the Automatic Advance  option set.

Please Note: If you do not setup the Device Naming tab it will default as the serial number.

  1. Save the profile and assign it to your devices. 

    All you have to do is find your Apple TV(s) on the left pane, find your profile on the right, then click, drag, and drop. 

    You will see the association(s) in the bottom pane.

  1. Now you will need to plug your Apple TV(s) into power and ethernet. If you are going to attach it to a TV/Monitor at this point remember do no pair the remote or go through any of the prompts. The settings you setup will automatically advance through all those for you but will not if you do any setup at this point.

    When the Apple TV(s) is at the Pair your Remote prompt if will wait 19 secs or so then the device will auto advance through all prompts.

  1. After the Apple TV(s) completed the setup you can now bring it into FileWave as you would any other Mobile device through the Admin.

DEP Notify - How to provide progress visibility during DEP activation (macOS)

New to the Device Enrollment Program (DEP) process? Do you have a create full of macOS devices that need to be prepared and issued to end users? Did this need to happen yesterday?

The world of DEP device provisioning has been a great help and has improved the speed at which devices can be issued to end users. Gone are the days of monolithic imaging! Long live DEP! But what is happening when a macOS device is going through the Setup Assistant process? Want to get some visibility on what is being installed during the device activation? Traditionally, when a device goes through the DEP assistant, any number of applications can be deployed to the device. The problem with this approach is that there is not any indication given to the end user as to what is happening during this time interval. To an end user, it could appear that there is a problem with the device, and they may create support tickets to your Help Desk on the subject. 

In order to avoid that, we need to provide some visual indication of what is happening behind the scenes during this setup time. To do so, we will leverage two separate open source projects that are in use in the mac community, namely InstallApplications and DEPNotify. 

FileWave, by default, will provision a DEP device, enroll it into the MDM server, then deploy the custom macOS client to the device. The process looks something like this:

We need to instruct the FileWave server to deploy the open source package InstallApplications first so that we can set up the DEPNotify package and get feedback with all the great logging information that FileWave gives via its client log. The modified process looks something like this:

Step-by-step guide

Create, configure, and deploy the InstallApplications package

Create boostrap.json 

  1. Visit Erik Gomez's blog to get a practical example of configuring InstallApplications as well as some history and background on the project.
  2. Visit Erik Gomez's github site and download the latest code. For the purposes of this document, I have used version 1.1.
  3. Follow the instructions on the above site to configure your bootstrap.json file. Also, see the section below "Generating your bootstrap.json" for a simple example to get started with. To make troubleshooting easier, configure one or two packages defined in your bootstrap.json and ensure your packages are downloading correctly and your Install Application launch agent and launch daemon work successfully. If you have too many packages defined, it may be more difficult to determine where your configuration problem lies.
  4. Generate your bootstrap.json with the generatejson.py script on Erik's site, which automatically generates the SHA256 hashes for you.
  5. Once you have the bootstrap.json file generated (below is a sample boostrap.json), you will need to host it somewhere (like your filewave server) in order for the macOS client to download it during DEP activation. 

bootstrap.json

{
"preflight": [],
"setupassistant": [
{
"file": "/some_path/DEPNotify_installer.pkg",
"url": "https://<your_filewave_server>:20443/some_folder/DEPNotify_installer.pkg",
"packageid": "com.package.depnotify",
"version": "1.0",
"hash": "some_long_hash",
"name": "DEPNotify",
"type": "package"
},
{
"file": "/some_path/FileWave_installer.pkg",
"url": "https://<your_filewave_server>:20443/some_folder/filewave_installer.pkg",
"packageid": "com.package.filewaveinstaller",
"version": "1.0",
"hash": "some_long_hash",
"name": "FileWave Client",
"type": "package"
}
],
"userland": [
{
"file": "/some_path/EnergySaver.py",
"url": "https://<your_filewave_server>:20443/some_folder/EnergySaver.py",
"hash": "some_long_hash",
"name": "Energy Saver Profile",
"type": "rootscript"
}
]
}

Note: In the above bootstrap.json, the preflight stage is required, even if it is empty. If you don't have it defined, the script will error out (01/20/2018).

Hosting and Serving your packages via the FileWave Server (Linux)

To serve packages from FileWave, we will need to modify the httpd_custom.conf file for apache. To do this:

  1. On the FileWave server, open "/usr/local/filewave/apache/conf/httpd_custom.conf" and add the following:

    Alias /custompkg /usr/local/filewave/custompkg
<Directory "/usr/local/filewave/custompkg">
Options Indexes FollowSymLinks
AllowOverride All
Order allow,deny
Allow from all
</Directory>
     
  2. Restart apache with "fwcontrol apache restart"
  3. Create the folder "custompkg" within /usr/local/filewave/. This will be the storage location for all of the packages that you defined in your boostrap.json file.

Testing the InstallApplications workflow outside of the DEP activation process

  1. Testing the InstallApplications workflow outside of the DEP workflow will save you time. 
  2. To do this, execute the installapplications.py using the following command line on any macOS test device, such as a VM:

Launching installapplications.py manually

sudo python /Library/Application Support/installapplications/installapplications.py --jsonurl https://<your_filewave_server>:20443/bootstrap.json

There is also an option to skip the validation of the bootstrap.json file. Use this option to include the bootstrap.json in the installapplications package rather than download it via url.

sudo python /Library/Application\ Support/installapplications/installapplications.py --jsonurl https://<your_filewave_server>:20443/bootstrap.json --skip-validation

It turns out that the installapplications.py really doesn't like urls that have redirection. So, if you want to use some file hosting site like Dropbox, etc. think again. You may choose to host all the files on github, but then convert to raw links using rawgit.com; these links do not seem to redirect and worked fine to download installer packages via installapplications.py. Alternatively, you can choose to serve these files directly from your FileWave server.

Configure the InstallApplications LaunchDaemon and LaunchAgent

LaunchDaemon:

  1. Edit payload/Library/LaunchDaemons/com.erikng.installapplications.plist

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.erikng.installapplications</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/python</string>
<string>/Library/Application Support/installapplications/installapplications.py</string>
<string>--jsonurl</string>
<string>https://<your_filewave_server>:20443/custompkg/bootstrap.json</string>
<!-- <string>--iapath</string> -->
<!-- <string>/Library/Application Support/installapplications</string> -->
<!-- <string>--laidentifier</string> -->
<!-- <string>com.erikng.installapplications</string> -->
<!-- <string>--ldidentifier</string> -->
<!-- <string>com.erikng.installapplications</string> -->
<string>--depnotify</string>
<string>DEPNotifySkipStatus</string>
<string>Command: WindowTitle: Welcome to your Mac!</string>
<string>Command: NotificationOn:</string>
<string>Command: Quit: Thanks for your patience while we setup your new mac.</string>
<string>Command: WindowStyle: ActivateOnStep</string>
<string>DEPNotifyPath: /Applications/Utilities/DEPNotify.app</string>
<string>DEPNotifyArguments: -filewave</string>
<!-- <string>DEPNotifyArguments: -filewave -fullScreen</string> -->
<!-- <string>--reboot</string> -->
<string>--skip-validation</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StandardOutPath</key>
<string>/var/log/installapplications.log</string>
<key>StandardErrorPath</key>
<string>/var/log/installapplications.log</string>
</dict>
</plist>

In the above example, I left the reboot and fullscreen option disabled, but feel free to adjust this according to your needs.

LaunchAgent:

There was no need to adjust this, but if you wish to customize the install applications bundle ID, you will have to edit this file.

Signing your InstallApplications package

Prerequisite: Membership in Apple's Developer Program

  1. Use a package creation utility to generate the .pkg for installapplications. One type of tool to use is Apple's command line pkgbuild, for example:

    pkgbuild --identifier com.erikng.installapplications --root <path_to_root_of_installapplications_payload> InstallApplications.pkg

  1. Only distribution style packages are supported, so to convert from a flat package to a distribution package:

    productbuild --package InstallApplications.pkg InstallApplicationsDistr.pkg
  1. To sign the distribution package:

    /usr/bin/productsign --sign "Developer ID Installer: <yourID> (XXXXXXXX)" InstallAppplicationsDist.pkg FileWaveClientInstaller.pkg
  1. To check your signing, you can issue:

    pkgutil --check-signature FileWaveClientInstaller.pkg

The above command should return "Status: signed by a certificate trusted by Mac OS X".

Test the "InstallApplications.pkg" thoroughly on a test mac before attempting to deploy via the DEP Setup Assistant.

Steps for deploying your signed InstallApplications.pkg using FileWave

Instead of deploying the macOS custom pkg, you will be deploying the InstallApplications.pkg. If you are currently deploying the custom FileWave client in your DEP workflow as the starting point, I highly recommend testing this workflow out on a test server before deploying to production. The deployment scenario below considers that we are running FileWave on the linux appliance and have NEVER previously deployed the custom FileWave client before using the InstallApplication DEP workflow. 

  1.  Open an ssh connection to your FileWave server

    $ ssh root@<yourfilewaveserver.com>
  2. Run a complete backup of your filewave server. 
  3. Backup the current DEP macOS installer package

    $ cd /usr/local/filewave/fwcld
$ mv FileWaveClient.pkg FWClient_old.pkg

  4. Copy your signed InstallApplications.pkg on your mac to the /usr/local/filewave/fwcld folder on your FileWave server and change its name at the same time
    $ scp /InstallApplications.pkg root@yourfilewaveserver.com:/usr/local/filewave/fwcld/FileWaveClient.pkg

  5. Remove the MD5 hash of the old FileWave macOS custom pkg from the database. You should see that the above query should affect one row only.
    $ /usr/local/filewave/postgresql/bin/psql mdm django -c "DELETE from ios_preferences WHERE key = 'dep_osx_package_md5';"

  6. Set the MD5 checksum and version of the "FileWaveClient.pkg" (really now the InstallApplications package disguised as the FileWave client package).

macOS FileWave Server:

# sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc shell
from ios.fwcld_utility import get_package_sha256;
get_package_sha256(force=True)
from ios.preferences_manager import PreferencesManager; PreferencesManager.set_dep_osx_package_version("14.0.3")
exit()
fwcontrol server stop
fwcontrol server start

Linux FileWave Server:

# sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc shell
from ios.fwcld_utility import get_package_sha256;
get_package_sha256(force=True)
from ios.preferences_manager import PreferencesManager; PreferencesManager.set_dep_osx_package_version("14.0.3")
exit()
fwcontrol server stop
fwcontrol server start

Command to execute to generate the new MD5 for the "fake" Custom Client (InstallApplications.pkg):

from ios.fwcld_utility import get_package_md5; 
get_package_md5(force=True)

This will generate a result like:

['70c829ddd9bd2aeafbe07fdd35f91c03']

Command to set the new "version" of the package:

from ios.preferences_manager import PreferencesManager; PreferencesManager.set_dep_osx_package_version("12.7.1")
  1. Exit the psql shell with "\q"
  2. Restart the filewave server:

    fwcontrol server restart

Result

During setup assistant, you will no longer get the custom FileWave client delivered first. The FileWave client will be installed by the InstallApplications script, along with any other crucial application / setup file that is needed (such as the Energy Saver) during DEP provisioning. Once the FileWave client is on the device, all other associated filesets can be deployed according to the needs of the end user.

Minimum OS version for enrolling Apple devices via ADE

What

MDM servers have the ability to enforce a minimum operating system version on enrolling devices when using Automated Device Enrollment (ADE).  This feature was added in FileWave version 15.1.0 for macOS 14.0 Sonoma and iOS/iPadOS 17.0. Apple does not support this feature on older versions of macOS or iOS/iPadOS.

When/Why

Minimum OS version allows to ensure that devices are on the necessary OS version before being put into production. The MDM will send a JSON 403 response when the device requests the enrollment profile. If the minimum operating system version is needed, the user will be guided through a process of updating the device. Restarts will be performed automatically. Once completed, the device returns to Setup Assistant and the user can finish the enrollment and setup process.

How

With FileWave 15.1.0 support of minimum OS version was added. To specify minimum OS versions open DEP profile and go to Options → Requirements section. There are separate fields for macOS and iOS / iPadOS minimum OS versions.

image.png

The supplemental version identifiers can be specified in addition to standard MAJOR.MINOR.PATCH format (for example “17.1 (a)“).

What is displayed on the device?

When minimum OS version is requested by MDM server specific dialog appears on the device.

For macOS:

image.png

For iPadOS:

image.png

If macOS device cannot install requested OS version next dialog appears:

image.png

On iPadOS there is no specific dialog in this case, just “Next“ button is grey and no way to pass.

Related Content

Digging Deeper

MachineInfo from the device is parsed on server side during DEP profile handling. If it contains MDM_CAN_REQUEST_SOFTWARE_UPDATE flag and it’s True, the specified minimum OS version from DEP profile is compared with OS_VERSION from MachineInfo according to the device type (macOS or iOS/iPadOS). Software update request is sent to the device by MDM server in 2 cases:

  1. If current OS version is less than minimum OS version

  2. If current OS version equals minimum OS version but current supplemental version identifier is less than required supplemental version identifier.

The software update request from the server looks like 403 JSON response with next body:

{
    "code": "com.apple.softwareupdate.required",
    "details": {"OSVersion": <minimum OS version> }
}

In this case enrollment is interrupted by dialogs mentioned above.

Test macOS ADE (DEP) Enrolments with a Virtual Machine

Description

Testing macOS device enrolments can be very time consuming, since a device must be erased and OS reinstalled on each attempt.  A Virtual Machine (VM) may be used to substantially reduce the amount of testing time.  Although VMware has been used in this example, other Virtualisation software could be used, e.g Parallels.

Requirements

Obtain a serial number for a device that is registered in ABM or ASM.

Any one serial number of a device should only occur once in FileWave.  Therefore, if there is an old or broken device which is registered in ABM/ASM, consider using the serial number from this device otherwise a serial number from a usable, physical device will need to be taken, meaning that physical device cannot be used within FileWave otherwise.

Mactracker may be used to show the Model Identifier of devices, since ASM/ABM only provides the Model Name

Directions

  1. Use VMware Fusion to create a new image from disc and use the macOS installer app or choose to create an image from the recovery partition
  2. Once completed, do no hit play.  Instead, locate the virtual machine in Finder.  If the VM starts, shut it down before continuing.
  3. From Virtual Machine Library, right click and choose show in Finder.
  4. From Finder, right click the highlighted VM and choose 'Show Package Contents' or use Terminal to navigate inside this VM
  5. Locate the file with a .vmx extension and choose an editor to edit this .vmx file
  6. Two lines need to be added as below.  Replace Serial Number and Model Identifier as appropriate (remove brackets, but keep quotes):

    serialNumber = "[Serial Number]"
hw.model = "[Model Identifier]"
  1. Now Play the VM
  2. Select language and once the option to re-instal the operating system is shown, choose utilities and Terminal
  3. Type the following line to confirm that the VM has the appropriate serial number:

    ioreg -l | grep "IOPlatformSerialNumber"
  1. Quit Terminal and choose to re-instal the operating system
  2. Have a cup of tea!
  3. Disable network settings at the earliest, allowable moment, before the device comes back up and finalises the installation
  4. Snapshot the VM when the Choose Language prompt is shown

A device receives an associated DEP profile before the option to select the language appears after installing the operating system. Once in place, the device will maintain this profile across reboots.  If the network is not disabled before receiving the Enrolment profile, then changes to the Enrolment profile associated or assigning a new DEP profile subsequently, will have zero impact on a fresh Enrolment; the original Enrolment settings will continue to apply.

By disabling the network before the Enrolment profile is in place and then taking the snapshot, multiple Enrolment profiles or changes may be tested with each restore of the snapshot.  On each restore, the network should require enabling.

Tested on VMware Fusion 10, 11 and 12

 

DEP Troubleshooting

Apple Device Enrollment Program (DEP) is a service provided by Apple that allows organizations to easily deploy and manage iOS, iPadOS, macOS, and tvOS devices. It streamlines the initial setup and configuration process for large-scale device deployments, making it easier for businesses, educational institutions, and other organizations to integrate Apple devices into their workflows.

Correct DEP Workflow

Figure 1.1 - DEP Workflow
  1. Device activates to apple (see ports: Default TCP and UDP Port Usage)
    1. Devices is not in DEP - Apple responds with done - Setup Assistant skips enrollment
    2. Devices is in DEP - Apple responds with enrollment ownership info
  2. Apple sends the DEP profiles to the device (See: Working with Apple’s Device Enrollment Program (DEP))
  3. Devices installs the DEP profile which makes it reach out to FileWave MDM server
  4. Device MDM enrolls 
  5. (if macOS) Devices then installs the macOS PKG

Things to Test

Check the connectivity

You can download a FileWave port testing tool from https://supportresources.filewave.com/

You can get devices to join ethernet by creating an adapter using

Plug in the device and make sure you get a link light.

Check the profile

Because these profiles are stored with Apple for the devices, when new options become available in DEP profiles FileWave can't just auto-update existing ones. If you have upgraded your FileWave instance recently you might want to create a new one and change your auto assignment rules (Automatically Assign DEP profiles ). Do not duplicate an existing profile.

DEP Forbidden Error

Description

On creating a DEP Association or from any other DEP synchronisation action, the following error may be observed: DEP error: Forbidden

The most likely causes are:

Apple store the external IP of the FileWave Server from the last successful contact.  If this differs at the time of a synchronisation , the action will fail and the DEP Server Token will need to be replaced.

The stored IP may be observed from the relevant DEP account:

The Last Date and IP Connected may be seen from the Settings view; select the MDM Server and choose Edit.  

Requirements

Resolution

Forbidden error requires the token be replaced and not updated.

From FileWave Admin > Preferences > VPP & DEP:

  1. Choose 'Download certificate' (requires fwadmin password) to save the certificate

From the relevant Apple DEP account Apple Business Manager or Apple School Manager:

  1. Select 'Settings'
  2. Highlight the MDM server from the list and choose Edit
  3. Select 'Upload New...' and select the saved downloaded file from above
  4. When prompted, select to download the DEP Server Token

From FileWave Admin  > Preferences > VPP & DEP:

  1. Click 'Configure Accounts' (requires fwadmin password)
  2. Select the Forbidden token and use the '-' button to remove that token
  3. Select the '+' button to select the DEP Server Token downloaded from Apple
  4. Run a DEP Synchronisation Full Sync (Hold down ALT(macOS), Option(Windows)), then select to synchronise (the name of the button will change)

At this stage synchronisation should now be successful.

If the DEP Server Token is currently configured in the Education tab of Preferences, this association will need to be removed prior to removing the DEP token, but may be re-added again afterwards.