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: Devices, purchased from a supplier signed up to Apple's programme, are registered with Apple FileWave MDM server is registered with Apple Devices are assigned to the FileWave MDM server within the Apple Business or School account: ABM or ASM 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. 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 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. Redirects provided to IdP for connection with FileWave Server may be viewed from FileWave Anywhere, for example: 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 Automated Device Enrollment (ADE) ADE only works with devices purchased from Apple authorized sources or added via Configurator to ABM/ASM. For information on approved devices in ADE, see the following reference: https://help.apple.com/deployment/business/ The features of ADE include: Zero-touch configuration - supported Apple devices, including iPhone, iPad, Apple Vision Pro, and Mac, can receive preassigned applications, profiles, and settings during activation. Automatic enrollment and management - devices can automatically enroll with the FileWave MDM server and receive management profiles without hands-on work by IT. Supervision and enforced management - ADE can provide additional management control and prevent removal of management when Apple supports those capabilities for the platform and enrollment. Streamlined Setup Assistant - devices can skip supported setup steps and receive their assigned configuration during activation. ADE Workflow Overview IT signs up for ADE account (or accounts) Institution purchases devices via an authorized seller IT doesn't see devices in the online ADE list until the shipping confirmation arrives from Apple (prior to that, Apple doesn't know what serial numbers are going to be shipped) IT assigns the devices from the online ADE list to the FileWave MDM server by serial number (You can also assign defaults in ASM & ABM) Wait for the ADE list and the FileWave MDM list to synchronize (24hr default sync, or triggered manually in the DEP UI IT assigns ADE profiles to the serial numbers of the devices prior to arrival (Automatically Assign ADE profiles) 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 ADE with FileWave This process is covered in VPP and ADE preferences FileWave Client for macOS ADE FileWave Server 16.4.0 and later: Build the signed macOS enrollment package in FileWave Central > Preferences > Mobile > macOS. Select Show settings, configure the package, and use Build macOS client package. Earlier supported FileWave Server versions continue to use custom.filewave.com until the Server is upgraded to 16.4. "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 ADE Once you have registered your FileWave Server with the ADE 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 ADE is not the same as a management profile. Instead of a property list (plist), the ADE 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 MDM server URL MDM options, such as supervision and management profiles MDM server certificate(s) Pairing certificates Device setup assistant options The process for setting up your devices is done through the /Assistants/ADE Association Management… pane:   The ADE Associations pane looks similar to other FileWave windows with three sections. In this case, they are: The Device list in the upper left, which you can filter by the different accounts devices are purchased under; The Profiles list in the upper right, which lists all of the profiles available to associate to devices with the number of devices each is assigned to; and, The Associations list on the bottom, which displays the device by serial number, the name of the profile it is associated with, and various date-time Groups showing assignment dates and times. Security prerequisites for ADE ADE 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 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 ADE 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 ADE, 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 ADE profiles FileWave 16.4 and later: macOS ADE profiles include Managed Migration Assistant controls for Mac-to-Mac migration during Setup Assistant. See ADE Profiles for the supported control areas, validation boundary, and related DDM workflow. You create ADE profiles within the ADE Associations pane by clicking on the + button in the profile section of the window. Here is a view of the ADE 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: Do not allow user to skip enrollment step - the device must become enrolled in order to complete setup Supervise (iOS only) - the device will have supervision enabled Is MDM removable - if unchecked, the MDM profile is locked to the device and cannot be removed by the user through the UI Allow pairing - if checked, the user can pair the device with their own iTunes account to synchronize personal content Automatic Advance - if checked, the Apple TV will automatically advance through setup assistant (If you use the remote on the Apple TV this option will be canceled) Enable Shared iPad - Device will be configured as a Shared iPad. Devices that do not meet requirements ignore the option. Maximum number of users - Sets the maximum number of users that can use a shared iPad, based on the storage capacity. If greater than the maximum possible number of users supported on the device, the device will be configured with the maximum possible number of users instead. Setup Assistant Skip setup items - this allows the FileWave administrator the ability to configure which portions of the setup assistant are made available to the end user when they configure the device. If none of the items are allowed, then the device must be pre-configured using MDM profiles with all of the appropriate settings to ensure functionality. Account (requires client running macOS v10.11+) A feature in ADE 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 ADE 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: ADE 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: a normal Apple ID - end user has to log in with iCloud on the device and enable Find My Phone a ADE (ASM or ABM) account ; in this case, the corresponding Apple ID is the Apple ID managing the ADE server. In both cases, FileWave can escrow the key and use it to unlock the device during refresh. You can configure Activation Lock: for each ADE device, at the ADE profile level globally, for all non ADE devices For ADE devices: No lock AKA Disabled Use iCloud Use your AMS/ABM account Associations Associating a ADE 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 ADE Associations window. The device will have the associated profile applied upon activation. To automate see: Automatically Assign ADE profiles End Result of ADE associations The end result of associating ADE 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 ADE is the optimal way to enroll your Apple devices. ADE enrollment is required for countless features and management tools. Once added, you will need to renew your ADE 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 ADE. Step-by-step guide  Download the ADE Certificate from FileWave Admin  Save the certificate "FileWave ADE" to your desktop. FileWave Anywhere Sources > ADE Accounts > '+' > Download FileWave Central Preferences > VPP & ADE 3. Go to the relevant Apple ADE 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 7. Once saved, download the token from ASM/ABM 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 ADE Accounts, select the ellipses next to the correct ADE account and choose ‘Edit’. Select Browse and upload the Apple Token downloaded in step 7 of this document. Click Save. FileWave Central In Preferences > VPP & ADE, select Configure Accounts and enter your password. Select the correct ADE 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. Adding New Token FileWave Anywhere In Sources, under ADE 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. FileWave Central In Preferences > VPP & ADE, 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. 9. After the token is uploaded, run a full ADE sync. Perform full ADE sync FileWave Anywhere In the Sources tab, select the Sync icon next to ADE Account and choose Full Sync. FileWave Central Go to Preferences > VPP & ADE. While holding down the option/alt key, press ‘Synchronize (full sync)’. 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 ADE and FileWave here: Apple ADE Enrollment. ADE Naming This article is for individuals who want to customize naming of ADE (formerly known as DEP) devices. It will cover placeholders and their ability to accept name, as well as using custom and built-in strings in the ADE 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 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 Import any custom field values if needed See Custom Fields: Importing CSV for more information Variables in the ADE profile Step-by-step guide Generate a ADE profile See Working with Apple's Device Enrollment Program (ADE) In the naming tab of the ADE 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 ) It would also be recommended that you create an automatic ADE rule to only assign this profile to devices that have the variables set: see the example in Automatically Assign ADE profiles FileWave Foundry Video Sign into FileWave Foundry and watch a video here regarding ADE Naming. Apple ADE - MDM Certificate vs. MDM Trust Chain What For ADE/DEP enrollments there are certificates that go in the enrollment profile. In FileWave 16.2.0 we have made a change to what is included in that profile by default. When/Why We've had some support issues where customers would see ADE/DEP profiles duplicate. Investigation has found that because of the way we would include the certificates we would sometimes have to update the profiles when certain things like renewing your SSL certificate would happen. After investigation with Apple we had found that our method was very secure, but created complexity that could be avoided. The root cause of DEP profile duplication is that we add MDM server in ADE profile, which is the most secure (device checks if MDM server has the same certificate as the one in ADE profile), but it requires us to recreate profiles when certificate is renewed. How In FileWave 16.2 we are changing what we are including in the ADE/DEP enrollment profiles by default. We have new setting to only add trust chain (parent certificates), so enrolment will work, but the device will not verify the cert (cert must still be valid, but device won't verify it's the same cert). It's a bit less secure, but still secure (unless someone has a way to create his own cert with your fqdn). But this allows us to not recreate ADE profiles each time we renew certificates, because it's not required anymore. You'll find the setting in Central's Preferences as shown in the below image. It is in the VPP & ADE tab there. We recommend leaving it on MDM Trust Chain to avoid duplication of ADE/DEP enrollment profiles. We have left the option there to pick MDM Certificate in case there was a customer who had the security requirement to do that, but know that it can result in profiles being duplicated when you update your SSL certificates if you change it to MDM Certificate. Related Content Automated Device Enrollment (ADE) Automatically Assign ADE profiles Starting in FileWave version 13.1.0 you now have the ability to automatically assign ADE (formerly known as DEP) profiles to devices. Step-by-step guide Start by opening up the ADE Profiles UI (Assistant → ADE 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 Open the "Edit Assignment Rules" UI Choose a Default ADE Profile (Figure 1.1) 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) Open the "Edit Assignment Rules" UI Hit the [+] to create a new profile rule Select your default profile for an OS (iOS in this example) Drag the ADE Devices / Operating System component from the left into the Criteria Set to "Contains" : "iOS" (See figure 2.1) Save Repeat again for "OS X" and "tv" as needed Assign based on custom fields (Advanced) Create Custom fields (in this example "usage" and "location")  See Custom Fields for more information Use: Provided: Admin, Type: string, Restricted: True, Values: None (DEFAULT), Faculty, Student, Administration (See Figure 3.1) Location: Provided: Admin, Type: string, Restricted: True, Values: None (Default), Site A, Site B... (Figure 3.2) Take note of the "Internal Name" from the custom fields Open the ADE UI Hit the [+] to create a new ADE profile Use the internal name in naming (see Figure 3.3) See ADE Naming for more information Open the "Edit Assignment Rules" UI Hit the [+] to create a new profile rule Select the profile you just created You will now see the Custom Fields component on the left Component list Open it and bring in location and use 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 ADE 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 Control Await Configuration state (ADE enrolled devices) What When Apple devices are enrolled via the Device Enrollment Program (DEP)—now known as Automated Device Enrollment (ADE)—they enter an “Await Configuration” state during the initial setup. In this mode, the user cannot interact with the device until the configuration process is complete, ensuring that devices are properly set up according to organizational policies before they are handed over to end-users. Starting with FileWave 15.5.0, administrators have enhanced control over this process. You can now specify when a device is released from the “Await Configuration” state, rather than having FileWave automatically release it as soon as possible. This provides greater flexibility and control over the deployment and configuration of devices. Supported Devices and OS Versions: iOS Devices: iPhone and iPod touch running iOS 11 or later. iPad running iOS 11 or later (before the introduction of iPadOS). iPadOS Devices: iPad running iPadOS 13 or later. macOS Devices: Mac computers running macOS 10.13 High Sierra or later. tvOS Devices: Apple TV running tvOS 11 or later. This feature is applicable to all the above device types enrolled via DEP/ADE and managed through FileWave 15.5.0 or later. When/Why Use this feature when you need devices to remain in the “Await Configuration” state until all necessary configurations, apps, and policies are fully deployed. This is particularly beneficial in scenarios where: Security Compliance: Ensuring that all security measures are in place before the device becomes operational. Standardization: Guaranteeing a consistent user experience by applying all organizational settings prior to device use. Controlled Deployment: Managing the timing of device readiness, especially in large-scale rollouts or staged deployments. By controlling the release of the device, you enhance security, ensure compliance with organizational policies, and provide users with a fully configured device from the moment they begin using it. How When enrolled via ADE, devices are in a specific mode where the user is not allowed to interact with the device, which will stay in this state until configuration is over. By default, FileWave releases the device as soon as possible to shorten initial setup times. FileWave 15.5 now allows controlling when the device is released: You can edit the ADE Profile used for enrolling your devices and go to the Options tab where you can check the "Do not allow devices to complete Setup Assistant without FileWave approval" which will make it so that devices will not finish setup until they are released. When creating a Profile to release devices you can see in the image below that there is a checkbox in Command Policy -> Security -> "Allow devices waiting for configuration to complete the Setup Assistant" and if a profile with this set is sent it will release the devices from setup to be able to be used.  It is also possible to send the Device Configured command either manually (context menu) by right clicking one or more devices in FileWave Central and picking MDM -> Send Device Configured Command. Devices will report their "Awaiting Configuration" state so that you can check on a device or make a Query to report on many devices to track if they are still in the setup process. Note: In FileWave Central, devices that remain in the Waiting for Device Configured / Awaiting Configuration state may appear highlighted in light yellow in the Clients list. This color is informational: the device is still waiting for the Device Configured command. You can send the command manually from the device context menu under MDM -> Send Device Configured Command, or automate release using a Command Policy Fileset that allows devices waiting for configuration to complete Setup Assistant. Related Content Automated Device Enrollment (ADE) Apple ADE Enrollment Digging Deeper The introduction of this feature in FileWave 15.5.0 provides administrators with enhanced control over the device enrollment and configuration process. By keeping devices in the “Await Configuration” state, you can ensure that: All Required Configurations are Applied: Devices won’t be accessible to users until every necessary app, profile, and setting is installed. Improved Security: Prevents users from accessing the device with incomplete security policies, reducing potential vulnerabilities. Customized Deployment Workflow: Aligns device readiness with organizational schedules, training sessions, or specific events. Automating the Release Process Using Command Policy Filesets to send the Device Configured command allows for automation based on specific triggers or conditions, such as: Time-Based Triggers: Release devices at a specific time as set in the Association or Deployment properties. Configuration Completion: Automatically release once all deployments are confirmed as installed. Event-Based Triggers: Release devices in batches aligned with department needs or project phases. Considerations User Experience: Communicate with end-users about the deployment timeline to manage expectations. Testing: Before wide-scale implementation, test the process with a small group to ensure configurations apply as intended. Monitoring: Utilize FileWave’s monitoring tools to track the status of devices in the “Await Configuration” state. By leveraging this feature, organizations can enhance their deployment strategy, ensuring devices are secure, compliant, and fully configured right out of the box. Apple TV Automatic Advance (ADE/DEP) Description This recipe will walk you through the steps of enrolling an Apple TV HD 4th gen into FileWave with ADE (formerly known as 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 ADE setup Ethernet Cable USB 3 Cable Direction Go to the Assistants menu -> ADE Association Management This opens the ADE Associations window 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. 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. 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. 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 ADE activation (macOS) New to Automated Device Enrollment (ADE) 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 ADE 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 ADE! 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 ADE 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 ADE 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  Visit Erik Gomez's blog to get a practical example of configuring InstallApplications as well as some history and background on the project. Visit Erik Gomez's github site and download the latest code. For the purposes of this document, I have used version 1.1. 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. Generate your bootstrap.json with the generatejson.py script on Erik's site, which automatically generates the SHA256 hashes for you. 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://: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://: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://: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: On the FileWave server, open "/usr/local/filewave/apache/conf/httpd_custom.conf" and add the following: Alias /custompkg /usr/local/filewave/custompkg Options Indexes FollowSymLinks AllowOverride All Order allow,deny Allow from all   Restart apache with "fwcontrol apache restart" 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 ADE activation process Testing the InstallApplications workflow outside of the ADE workflow will save you time.  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://: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://: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: Edit payload/Library/LaunchDaemons/com.erikng.installapplications.plist Label com.erikng.installapplications ProgramArguments /usr/bin/python /Library/Application Support/installapplications/installapplications.py --jsonurl https://:20443/custompkg/bootstrap.json --depnotify DEPNotifySkipStatus Command: WindowTitle: Welcome to your Mac! Command: NotificationOn: Command: Quit: Thanks for your patience while we setup your new mac. Command: WindowStyle: ActivateOnStep DEPNotifyPath: /Applications/Utilities/DEPNotify.app DEPNotifyArguments: -filewave --skip-validation RunAtLoad StandardOutPath /var/log/installapplications.log StandardErrorPath /var/log/installapplications.log 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 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 InstallApplications.pkg Only distribution style packages are supported, so to convert from a flat package to a distribution package: productbuild --package InstallApplications.pkg InstallApplicationsDistr.pkg To sign the distribution package: /usr/bin/productsign --sign "Developer ID Installer: (XXXXXXXX)" InstallAppplicationsDist.pkg FileWaveClientInstaller.pkg 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 ADE 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 ADE 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 ADE workflow.   Open an ssh connection to your FileWave server $ ssh root@ Run a complete backup of your filewave server.  Backup the current ADE macOS installer package $ cd /usr/local/filewave/fwcld $ mv FileWaveClient.pkg FWClient_old.pkg 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 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';" 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") Exit the psql shell with "\q" 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 ADE 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 FileWave can require a minimum operating system version during Automated Device Enrollment (ADE). During enrollment, the MDM server can return Apple's required software update response when the device is below the configured minimum version. The device then guides the user through the required update before Setup Assistant can continue. Apple supports this minimum-version ADE workflow on devices running iOS 17, iPadOS 17, macOS 14, visionOS 26, or later. Older operating systems cannot use this ADE enforcement behavior. When/Why Use a minimum OS version when organization-owned devices must be updated before they enter production. If the device is below the required version, enrollment pauses, the update runs, and the device returns to Setup Assistant after the update so the user can finish enrollment. How In FileWave Central, open the DEP profile and go to Options > Requirements. Enter the minimum version for macOS and/or iOS/iPadOS. Use Apple's version format for the target operating system, and choose a version that is actually available for the device. You can also specify supplemental version identifiers in addition to the standard MAJOR.MINOR.PATCH format. For example: 17.1 (a). What is displayed on the device? When the MDM server requires a minimum OS version, the device displays Apple's software update or Remote Management flow before enrollment can continue. For macOS: For iPadOS: If a macOS device cannot install the required version, macOS displays an error dialog: On iPadOS, there is no separate error dialog for this case. The Next button remains disabled, so the user cannot continue until the requirement can be met. Related Content Automated Device Enrollment (ADE) Managing Apple Vision Pro and visionOS Apple: Install and enforce software updates for Apple devices Digging Deeper During DEP profile handling, FileWave evaluates MachineInfo from the device. If MachineInfo includes MDM_CAN_REQUEST_SOFTWARE_UPDATE set to true, FileWave compares the DEP profile's minimum OS version with the device's OS_VERSION for the relevant platform. FileWave requests an update when: The current OS version is lower than the minimum OS version. The current OS version equals the minimum OS version, but the current supplemental version identifier is lower than the required supplemental identifier. The software update request is a JSON 403 response like this: { "code": "com.apple.softwareupdate.required", "details": {"OSVersion": } } Enrollment is interrupted by the Apple dialogs shown above until the device meets the requirement. 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 Copy of VMware Fusion macOS installer, e.g. Install macOS High Sierra.app or a VMware Fusion installed on a relevant macOS device A registered macOS device serial number and optionally a Model Identifier, e.g. MacBookPro15,1 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 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 Once completed, do no hit play.  Instead, locate the virtual machine in Finder.  If the VM starts, shut it down before continuing. From Virtual Machine Library, right click and choose show in Finder. From Finder, right click the highlighted VM and choose 'Show Package Contents' or use Terminal to navigate inside this VM Locate the file with a .vmx extension and choose an editor to edit this .vmx file 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]" Now Play the VM Select language and once the option to re-instal the operating system is shown, choose utilities and Terminal Type the following line to confirm that the VM has the appropriate serial number: ioreg -l | grep "IOPlatformSerialNumber" Quit Terminal and choose to re-instal the operating system Have a cup of tea! Disable network settings at the earliest, allowable moment, before the device comes back up and finalises the installation Snapshot the VM when the Choose Language prompt is shown A device receives an associated ADE 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 ADE 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 ADE Troubleshooting Apple Automated Device Enrollment (ADE), formerly known as DEP, lets organizations assign iPhone, iPad, Mac, and Apple TV devices to an MDM server before users start Setup Assistant. Use this page to confirm the expected ADE path and isolate common enrollment failures. Correct ADE Workflow Figure 1.1 - ADE Workflow Device activates with Apple (see ports: Default TCP and UDP Port Usage) Device is not in ADE - Apple responds with done - Setup Assistant skips enrollment Device is in ADE - Apple responds with enrollment ownership info Apple sends the ADE profiles to the device (See: Working with Apple’s Automated Device Enrollment (ADE)) Device installs the ADE profile, then contacts the FileWave MDM server Device completes MDM enrollment For macOS, the device then installs the FileWave client package Things to test Check the connectivity Check the Default TCP and UDP Port Usage KB article for the needed ports. You can download a FileWave port testing tool from https://supportresources.filewave.com/ Put a test device, such as a laptop, on the same Wi-Fi network used for enrollment. Try enrolling iOS/iPadOS devices over Ethernet or a mobile hotspot to see whether the normal network is blocking required traffic. You can connect supported iPhone or iPad devices to Ethernet with: Apple's "Lightning to USB 3 Camera Adapter" (the one with a female USB and another lightning port) Apple's "Apple USB Ethernet Adapter" A USB charger supplying 2+ amps of power Plug in the device and make sure you get a link light. Check the profile Because ADE profiles are stored with Apple for assigned devices, FileWave cannot automatically add newly available options to profiles that already exist. If you recently upgraded FileWave, create a new ADE profile and update your automatic assignment rules (Automatically Assign ADE profiles). Do not duplicate an existing profile. DEP/ADE Forbidden Error Description When creating an ADE (formerly DEP) association or running another ADE synchronization action, FileWave may show this error: DEP error: Forbidden. The most likely causes are: The FileWave Server SSL certificate changed. Check Preferences > Mobile to confirm that the server SSL certificate is not revoked or expired. The external IP address of the FileWave Server changed. Apple stores the external IP address of the FileWave Server from the last successful contact. If that IP address differs during synchronization, the action can fail and the ADE Server Token must be replaced. You can check the stored IP address in the relevant ADE account: Apple Business Manager Apple School Manager In the Apple portal, open Settings, select the MDM server, and choose Edit. The Last Date Connected and Last IP Connected values appear in the MDM Server Information view. Requirements FileWave MDM ADE certificate Resolution A Forbidden error requires replacing the ADE Server Token, not updating it in place. In FileWave Central, go to Preferences > VPP & ADE: Choose Download certificate (requires the fwadmin password) and save the certificate. In the relevant Apple ADE account, Apple Business Manager or Apple School Manager: Select Settings. Highlight the MDM server from the list and choose Edit. Select Upload New... and select the certificate downloaded from FileWave. When prompted, download the ADE Server Token. Back in FileWave Central, go to Preferences > VPP & ADE: Click Configure Accounts (requires the fwadmin password). Select the Forbidden token and use the - button to remove it. Select the + button and choose the ADE Server Token downloaded from Apple. Run an ADE Full Sync. Hold Alt/Option while choosing the synchronization action; the button name changes to indicate a full sync. After the token is replaced and the full sync completes, synchronization should succeed. If the ADE Server Token is currently configured in the Education tab of Preferences, remove that association before removing the ADE token. You can add it again afterward.