Sunday, March 10, 2019

Automated Device Enrollment - remediation for incorrectly scoped machines

Zero-touch Automated Device Enrollment is what all the cool Apple kids are doing now - Jamf have been promoting this with their “There is no step 3” campaign and in this post-imaging world it’s a great way to get devices into the hands of the end user.



I gave a presentation at JNUC 2018 about what goes on under the hood when a device is going through Automated Device Enrollment. Since then I have had lots of folks approach me to try and work out why they have been having issues getting this to work so I figured I would try and put things into a blog post, if only so I can refer back to it when my brain forgets the correct syntax of the commands to run.

So the Mac boots and instead of seeing the Remote Management screen, the user instead gets presented with the migrate data screen !???



What went wrong. Assuming that you are not trying to use Migration Assistant as part of your Device Enrollment, this is when folks start shouting that “DEP is down” or “DEP is flaky and doesn’t work” - both of which can have merit in certain circumstances, but I have found that there is generally a more straightforward explanation.

Most issues with Automated Enrollment are due to the Mac not being scoped correctly when it first hit the network. 
  • The serial may not have actually been allocated to your Apple School Manager, or Apple Business Manager account.
  • If it’s in there, it may not have been allocated to the MDM server. 
  • If it’s correctly allocated to the MDM server, it may not have been allocated to however your MDM decides how it is going to be managed (In Jamf Pro, this is called a ‘prestage enrollment’)



Another issue can be that if you have automatic assignment configured in ABM/ASM or in the Jamf prestage, it’s worth remembering that Jamf does not poll mdmclient.apple.com in real time looking for serials to allocate and upload an activation record. Jamf will use the “cloud API” to poll every couple of hours and make sure it has the current list of devices. If you know that a device may have only just been allocated to your MDM service in ABM/ASM, you will need to go into Jamf Pro and hit the “refresh” button to ensure that it is aware if this serial number and instructs Apple on what it should tell it to do when it checks in.

The number one cause of devices not picking up their enrollment correctly is human error!

So what do you do when you are in this situation - someone has started pop their Mac and it has ended up at the data migration screen despite being connected to the network and having all the required access? 

A full nuke-and-pave of the machine (via internet recovery, Installr or Mac Deploy Stick (after verifying that the machine is in fact configured in your MDM to be managed for Automated Device Enrollment) is always the best solution, but this can be a lengthy process and we may have an end user (or two or three or more) in front of us who need to get up and running ASAP.

The fist step is to have a poke about and try and work out why the device did not pick up that it is supposed to be enrolled. This little trick is what we can use to get access to terminal at the setup assistant, especially the knowing that performing this over the Language Chooser gives us a root shell is going to be your best friend. If you can’t get a Language Chooser screen up (the machine may have been wiped since it left the factory), Graham Pugh explains how we can boot to recovery and force the language screen at the next boot.

Once we have a terminal window up, we want to have a look in /var/db/ConfigurationProfiles/Settings/ as this contains what are known as “trigger files” that macOS used to determine it’s current state and how to respond. These files are SIP protected, so we can't just delete them (and even if we went into recovery and did delete them, I have found this to be extremely unreliable).




If the Mac was not scoped in ABM/ASM, you will see .cloudConfigNoActivationRecord. Essentially cloudconfigd went to the cupboard and the cupboard was bare.... 


This is exactly what you will see on a consumer device that is not allocated to a DEP account. It's also what you see if it hasn't been assigned to a prestage in Jamf (or your MDM of choice). Or if the device was booted before the activation record had time to propagate through Apple's CDN (this is pretty fast, but I have been a bit trigger happy once or twice and leaving it for at least a moment or two is a good idea).



Note that the delay you see after you change the scope or modify the prestage is Jamf using the cloud API to update the records of the corresponding devices so they know what to do when they check in.

Now that we are certain the activation record is correct, we need to get the Mac to refresh the details that it has onboard (remember that these were cached from when it first got onto a network, and we can't just delete them). We do this with the command (this is why we need a root shell - _mbsetupuser is not going to be able to run this command)

profiles renew -type enrollment 

If we run this command and then have a look at the trigger files, we should notice that they now read like this

we have .cloudConfigHasActivationRecord (which shows that the Mac was able to detect that there WAS an activation record for this device on profiles.apple.com) as well as .cloudConfigRecordFound which is the ACTUAL activation record. If we have look at this file (note that it has some content in it, unlike the others which are zero bytes) we can see the details that Jamf uploaded to Apple that were configured in the prestage.


Note that if you see .cloudConfigRecordNotFound, this is usually an indication of a network issue - the device knows there is a record for it, but it hasn't been able to download it. Look for clock skew on the machine (it may not be able to validate SSL certificates) or SSL inspection, firewalls or proxies preventing traffic from flowing freely. I'll go into some of these issues in a later post.

Now that you have the correct trigger files, there is one more thing we need to to. In order to trigger the cloudconfigd process that manages Automated Device Enrollment, we need to move from the Language Chooser screen into the Setup Assistant. You should be able to click back to the Language Chooser if you have already advanced, and then continue through again.

Now that everything is in order, you shouldn't see the dreaded "migrate user data" screen and instead see the "Remote Management" screen that shows that Automated Device Enrollment is underway.



To recap = the process is fairly simple
1. Establish that the serial is correctly scoped in Apple Business/School Manager, as well as your MDM.
2. Open a root terminal windows from the Language Chooser Screen
3. profiles renew -type enrollment
4. Move from Language Chooser back into Setup Assistant (or reboot)
5. There is no step 5!

actually, step 5 is to work out what part of your process led to the machine not being correctly scoped and to ensure that the process is modified to minimise this risk. As you can see, these steps are a right pain and are definitely NOT the sort of thing you want to be talking an end user through. If we can eliminate as many opportunities for this to happen, there will truly be "No step 3"!