Migrate your Macs to Hexnode with Hexnode Gateway

The Hexnode Gateway application remotely migrates macOS devices from another UEM to Hexnode UEM without performing a device wipe. This document will guide you through the steps to seamlessly migrate your macOS devices to Hexnode UEM.

Migrate Mac to Hexnode UEM

The Hexnode Gateway app can be installed by creating a configuration file from the Hexnode console and then deploying the PKG file to the devices. Follow these steps to migrate your Mac from another UEM to Hexnode.

1. Navigate to Enroll > Platform-Specific > macOS > Migrate to Hexnode.
2. If you have already generated the configuration file, skip to step 20. If not, click on Generate a new Configuration File.
3. Provide a suitable name for the configuration file under the Configuration Name field.

Configure Gateway app settings

4. Enable the option Enforce Hexnode Gateway app in full screen to open the app in full screen.
5. Allow users to leave the full screen during migration enforced by the Gateway app by enabling the option Allow user to exit full screen.
6. Enable the option Allow user to defer migration for a later time to allow the user to defer the migration once for 30 min, 1 hour, 2 hour or tomorrow. In case the user selects ‘tomorrow’ under the Allow user to defer migration for a later time option, the migration will be attempted after 24 hours.

Remove device from existing UEM automatically

If the UEM profile on the device is non-removable, follow the steps below to automatically initiate disenrollment from the current MDM, or manually disenroll the device from the current MDM.

7. Click on Remove device from existing UEM automatically to remove the device from an existing UEM automatically. Upon selecting the option, additional fields will appear to specify the current MDM, UEM portal URL, and UEM API key.
8. Select the current UEM you are enrolled in using the Specify the Current MDM option. A dropdown will display a list of MDMs from which migration can be initiated, such as Jamf, VMWare Workspace One, Kandji, Addigy and Jumpcloud.
9. Specify the portal URL of your current UEM instance in the portal URL field.
10. Specify the API key of your current UEM instance in the API key field.

Configure the selected UEM

If Jamf is selected, in the portal fields:

1. Specify the portal URL of your Jamf instance in the Portal URL field.
2. Specify the “Client ID” and “Client Secret” of your Jamf instance in the required fields.

To obtain the Client ID and Client Secret, complete the following steps in the Jamf portal:

Create an API role

1. Navigate to Settings > API Roles and Clients > API Roles tab.
2. Click New and enter a display name.
3. Assign privileges: Read Computers and Send Computer Unmanage Command.
4. Save the role.

Create an API client

1. Navigate to Settings > API Roles and Clients > API Clients tab.
2. Click New and enter a display name.
3. Assign one or more API roles (client inherits all privileges).
4. Set Access Token Lifetime (in seconds).
5. Check Enable API Client option.
6. Save the client.

Generate a Client Secret and Client ID

1. Open the created API client.
2. Click Generate Client Secret > Create Secret.
3. Copy and securely store the secret (it will only be shown once).
4. Copy the Client ID from the same page for later use in the Hexnode portal.

If VMWare Workspace One, Kandji, Addigy, or Jumpcloud is selected:

1. Specify the portal URL of your current UEM instance in the Portal URL field.
2. Specify the API key of your current UEM instance in the API key field.

Configure network settings

11. Wi-Fi configuration – Enable the option Add Wi-Fi settings to configuration file to configure the Wi-Fi settings.
12. VPN configuration – Enable the option Add VPN settings to configuration file to configure the VPN settings.
Warning:


Once the PKG file is deployed, there may be chances that the network configurations be exposed to the users at the device end. Thus, while configuring the network settings, we advise using temporary network configurations and refrain from using Enterprise network configurations.


Elevate standard account

13. Select Elevate standard account to Admin option to elevate the current user’s privileges from standard to administrator account during the migration process. On completing the migration, the account privileges revert to standard.
Note:


To prevent the user from using administrator privileges for actions unrelated to migration, enforce the Hexnode Gateway app in full screen mode. It can be done by selecting Enforce Hexnode Gateway app in full screen under Configure Gateway settings in the Hexnode UEM portal.


Renew FileVault Recovery key

14. To renew and escrow the FileVault Recovery key during the migration process, select the Renew and escrow FileVault recovery key option.

Set up the device configurations to be applied

15. Customize the device name in the Enrolled device name field. The use of wildcards such as %wifimacaddress%, %serialnumber%, %model%, %name%, %domain%, %userprincipalname%, %email% are supported from the dropdown.
16. To add the device to Hexnode’s custom device groups, select the Add to device groups option and choose the required device groups from the dropdown.
17. To add the device to an organizational unit, choose one from the available dropdown under Add to Organizational Unit.

Customize the Gateway app

18. Customize the Gateway app by adding an image of the company logo using the Add company logo option.

Generate the configuration file

19. Check the I agree to the Terms of Use checkbox to generate the configuration file. Since the migration is processed silently, the admin must accept the Terms and Privacy Policy on behalf of the end user.
20. Click on Generate a custom PKG file to generate the configuration file in downloadable format.
21. Download the PKG file onto your device.
22. Deploy the configuration file to target macOS devices. You can even use your existing UEM to deploy the file.

Complete device migration

The deployed PKG file installs the Hexnode Gateway app on the device and associates the configurations. The Hexnode Gateway app automatically opens up after installing the PKG file on the device.

Choose any of the following cases depending on your device scenarios and follow the steps accordingly to complete the migration.

Case 1: Device Enrolled via Automated Device Enrollment

1. When a device is enrolled via Automated Device Enrollment (ADE), it can be reassigned to another UEM server through the ABM/ASM portal as a part of the migration process. You can reassign the device in the ABM/ASM portal to an UEM server associated with the Hexnode UEM console.
2. Download and deploy the generated PKG file to the targeted devices using the currently enrolled MDM. Once the PKG file is installed, the Hexnode Gateway app opens on the device and initiates the migration.
3. Disenrollment of the device from the current UEM will be automatically initiated based on the configured settings under the Remove device from existing UEM automatically option in the Hexnode portal. If the UEM profile on the device is removable, the existing profile will be automatically removed.
4. On macOS 14+, user approval is required to initiate UEM migration, and the UEM profile needs to be approved by the user before installation.
5. If the Renew and escrow FileVault recovery key is enabled under the Renew FileVault recovery key option in the Hexnode UEM portal, the user will be prompted to enter the local account password.
6. Once done, the device will get enrolled in Hexnode without getting wiped. Update the ADE Enrollment profile associated with the ABM/ASM portal if needed, after the device is enrolled in Hexnode.

Case 2: Device enrolled manually

1. Download and deploy the generated PKG file to the targeted devices using the currently enrolled MDM. Once the PKG file is installed, the Hexnode Gateway app opens on the device and initiates the migration.
2. The new UEM profile needs to be approved by the user before installation.
3. If the Renew and escrow FileVault recover key under the Renew FileVault recovery key option in the Hexnode UEM portal is enabled, the user will be prompted to enter the local account password.
4. Once done, the device will get enrolled in Hexnode without getting wiped.