03. Preparation of the migration

Before you can use the EBF Onboarder, you first need to make some preparations:

• You have to create a Service Account dedicated to the EBF Onboarder which has the roles for API commands required on the source and target UEM server (see chapter 03.1).
• You also need to prepare your network and your UEM servers to allow the EBF network/servers to communicate with your environment (see chapter 03.2).
• You can change several settings which have an impact on various aspects of the device migration – including settings for the sending of emails (see chapter 03.3).
• You can create several admin accounts with customized rights so that the migration can be done by several admins (see chapter 03.4).
• Please be aware that only devices that are assigned to a user (email) can be migrated. Userless devices will not be found.

03.1. Service Account for API commands

EBF Onboarder requires a Service Account which has the roles for API commands on each source and target UEM system to allow the software to find the devices and migrate them from one system to another. You should login to the source system with this user and confirm that the account is able to fetch the devices.

EBF Onboarder can take advantage of your LDAP if you are using one. The EBF Onboarder will use the users’ email addresses to trace their devices and by default, registers the devices with the same email addresses on the target system.

NOTE: LDAP is not connected to the EBF Onboarder. The EBF Onboarder is only using the user attributes from the source system (which can be connected to LDAP).

EBF Onboarder will not create any device user on the target system but expects the device user to be already existing with the same email address. If the email address is different, you can customize the target email address with the ‘Transformation Tool’ (see chapter 06).

03.1.1. Prerequisites for the source system

Depending on your source system there are specific prerequisites for the Service Account who sets up the migration project that needs to be fulfilled before:

Source system	Service Account Requirements
BlackBerry UEM	The user must be a BAS user with the right to read groups and devices. The port is normally 18084 (e.g. uem.acme.org:18084).
BlackBerry UEM Cloud	ATTENTION for BlackBerry UEM Cloud as a source system: Please read the separate documentation in addition to this one to learn more about the prerequisites. You can find it here.
BlackBerry UEM v12	The host must be the internal host name. The Proxy URL needs to be: <region>.bbsecure.com (e.g. de.bbsecure.com for Germany). The tenant ID must have the format ‘SNUMBER’ instead of ‘SRPNUMBER’, for example, S00000. This user needs to be ‘Enterprise Admin’. The username must not contain underscores (this is not supported by the Blackberry NOC). ‘BlackBerry Web Services access’ must be enabled in the BlackBerry UEM portal.
Cisco Meraki	You need to provide: the server n.meraki.com without https:// the API-Key (created in Meraki > My Profile) Select this source type for the current Meraki version.
Cisco Meraki (before api v0.11.0)	You need to enter host, API Key, username and password. This source type supports older versions of Meraki.
Good for Enterprise	The user must have the Administrator role and must know the Domain Key.
Google G-Suite	A Service Account and json file need to be created to work with the EBF Onboarder.
Ivanti (MobileIron)	ATTENTION for Ivanti (MobileIron) as a source system: Please read the separate documentation in addition to this one to learn more about the prerequisites. You can find it here.
Jamf Pro / Jamf School	The user must have the Administrator role. Please read the separate documentation in addition to this one to learn more about the prerequisites. You can find it here. NOTE: Jamf Now is not supported.
MaaS360	The user must have the Administrator role. For API access, billingId, platformId, appId, appVersion and appAccessKey as well as host name and user/password are required. Further information can be found here
Microsoft Intune	In addition to the default Global Microsoft Cloud & GCC (endpoint.microsoft.com) we support the following additional Microsoft National Clouds as well: US Government L4 (GCC High) US Government L5 (DoD) China operated by 21Vianet German Cloud ATTENTION for Microsoft Intune as a source system: Please read the separate documentation in addition to this one to learn more about the prerequisites. You can find it here.
SAP Afaria	The user must be a Customer Admin on a T-Systems hosted Afaria instance.
Sophos Mobile Control	The user must have the Administrator role and known Customer. NOTE: For Sophos Mobile OnPremise: Please make sure to allow the IP 62.138.245.79 to contact the Admin Portal of your UEM system. We require this access for device management actions. For Sophos Cloud: Sophos Cloud does not provide an official API to manage devices. Therefore, we need to login to the Admin Portal to retire devices. The Sophos Central Admin Portal requires an MFA token to access the portal that cannot be turned off. Read more about it here. Therefore, we cannot support Sophos Cloud unless you convince the Sophos support to disable MFA for your API user.
SOTI	You need to enter host, admin username and password.
VMware Workspace ONE /AirWatch	The user must have API access and must know his API Key and optional PIN. ATTENTION for VMware Workspace ONE/AirWatch as a source system: Please read the separate documentation in addition to this one to learn how to locate the API Key and to learn more about the prerequisites. You can find it here.
XenMobile	The user must have the Administrator role.
Xinca	You need to enter host, network ID and API Key.

03.1.2. Prerequisites for the target system

ATTENTION for Ivanti (MobileIron), Jamf Pro/School, MaaS360, Microsoft Intune and VMware Workspace ONE as a target system: Please read the separate documentation in addition to this one to learn more about the prerequisites. You can find them here.

If you want to keep the installed apps on the devices, you need to configure this in the source system. Please refer to the documentation of your UEM system for this. In most cases it can be configured in the app settings of the UEM system for mobile devices. Desktops might have a different approach.

There are at least two cases where we recommend keeping one or more apps to save download time:

• You can already push the client app of the target UEM system (e.g. Intune Comp Portal, Ivanti Mobile@Work™ Client or Workspace ONE Intelligent Hub) to the devices using the source UEM system. If you have done that, it is not necessary to download it again during the migration.
• Apps that will also be used on the target UEM system do not need to be downloaded again. They will be reconfigured by the new UEM system.

03.1.3. Prerequisites for the Apple Volume Purchase Program (VPP)

The EBF Onboarder is able to migrate Windows, Android, iOS and macOS devices. But it does not migrate your VPP licenses. This needs to be done with the Apple Business Manager or Apple School Manager. You must configure the VPP connection on the target UEM system prior to the migration process with the EBF Onboarder. The licenses will be detected as released on the source UEM system and will be available to use on the target UEM system (please see the Apple documentation as this can request time for the synchronization).

03.2. Network configurations

This section will describe how you must prepare your network configurations to use the EBF Onboarder.

03.2.1. UEM server configuration settings

Your firewall rules or any network control appliance settings should allow your EBF Onboarder server to access your UEM servers through APIs (REST or SOAP, depending on the MDM), typically port 443.

Please add the following addresses to your network appliances/firewall/proxies for port 443 to authorize the communication with the EBF Onboarder server:

Hostname	TCP IP Address	Ports
app-out.ebf.com	62.138.245.79	443

ATTENTION:

• Every communication (API requests and SMTP) comes from 62.138.245.79. Please update your network appliances accordingly.
• If you are using other redirections to protect your server and are using specific ports (different from 443), please verify that the EBF Onboarder servers are allowed to reach the specific port of your MDM system as well.
• For Ivanti (MobileIron) as a source or target system: Please read the separate documentation in addition to this one to learn more about the server communication settings. You can find it here.
• For the UK Onboarder (https://onboarder.ebf.co.uk/): You need to allow the following IP address to your network for API and SMTP incoming communication: 185.210.197.66.

03.2.2. SMTP server communication settings

If you want to customize the sender email address and adapt it to your enterprise email address, you can do that either using the EBF SMTP server or your own SMTP server. Please read chapter 03.3.6.1.3 if you want to use the EBF SMTP server and chapter 03.3.6.2 if you want to use your own SMTP server to learn more about the necessary adjustments.

03.2.3. Device network configurations

Devices need to connect to HTTPS port 443 to your EBF Onboarder server (see chapter 03.2.1). Moreover, please make sure that all relevant ports for your UEM system are accessible for your devices.

03.3. Tenant settings

You can change several settings which refer to all migration projects and have an impact on various aspects of the device migration – including settings for the sending of emails.

To do that go to ‘Settings’ > ‘Tenant Settings’:

03.3.1. Password request customization

During the migration process the user might need to enter a password that is linked to his account on the target system. The password can belong to one of the following:

• LDAP account
• Active Directory account
• Specific UserID
• User’s email address

To give users an indication of the password they need to enter, you have the possibility to customize the text which is displayed to your users and helps them choose the correct password.

To do that go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, enter a text which indicates which password the user needs to enter in the field ‘Migration: Password Field Caption’ and save your changes:

03.3.2. Language enforcement

You can define the language of the EBF Onboarder portal.

To do that go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, select a language in the dropdown for ‘Enforce Language’ and save your changes:

NOTE: If you select English or German, the Portal language and steps on the device will be displayed in the selected language. If you select French, only the steps on the device are displayed in French, the portal language will be English.

03.3.3. Timeout after unenrollment customization

At one point of the migration process the devices will be retired from the source system. The time that a device is allowed to take for retiring from the source system is limited by default to 30 seconds.

The duration of the retiring process depends, for example, on the network capacities. Also mailboxes which contain many emails can increase this process as the removal of the profile from the device can take more time. If one or several test users receive an error in the test phase, this indicates that it takes too long to get the retiring acknowledgement from the source system.

As long as the retiring acknowledgement is not confirmed by the source system, the EBF Onboarder will not proceed to the next step which is the registration at the target system. Thus, you need to increase the timeout parameter in order to allow the communication between the source system and the device to take place.

EXAMPLES:

• For Apple DEP (Supervised) the value should be: 0.
• For Apple Supervised (no DEP) the value should be: Value for unenrollment + 60 seconds.

The value requires proper testing as this value is used for the whole EBF Onboarder tenant.

To do that go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, increase the number for ‘Timeout (seconds) after unenrollment’ and save your changes:

03.3.4. Activate Debug console

It can happen that the retiring process takes too long or fails. This is usually the case if a user has insufficient rights or if he has lost network connection (e.g. because the Wi-Fi configuration was removed during the retiring process).

You are able to read the messages that have been exchanged between the device and the source UEM system during the migration process in order to analyze why the migration has failed. It might be useful to share these messages with the EBF support team.

To read those messages go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, select ‘Show debug console while migration’ and save your changes:

03.3.5. Multifactor authentication

If you want to increase the security for the EBF Onboarder login, you can enable Multifactor authentication for your tenant.

To enable this feature go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, select ‘Enable Multifactor authentication’ and save your changes:

When you login to the EBF Onboarder the next time you will see a pop-up asking to confirm a TAN. An email will be sent to your mailbox with the TAN that needs to be entered. Click OK to access the EBF Onboarder.

03.3.6. Hide phone numbers

If the devices’ phone numbers should not be displayed in the EBF Onboarder UI, you can display only the last 4 digits.

To enable this feature go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, enable ‘Hide Phone numbers’ and save your changes. Once you enable this option, phone numbers will be displayed with only the last 4 digits, if you create a new project or refresh a migration (if available for your source system).

NOTE: Existing projects are not modified if the refresh feature was not used. Information mails, invitations, reminders and welcome emails will still show the phone number, if the placeholder {phone} was used.

03.3.7. Email settings

By default, invitations are sent from the EBF SMTP server – with several options for customization (see chapter 03.3.7.1). But you can also use your own SMTP server to do this (see chapter 03.3.7.2).

Email sending using the EBF SMTP server

By default, the EBF Onboarder sends invitations, reminders and/or welcome messages to your users from the EBF SMTP server and uses a ‘noreply.onboarder@ebf.com’ address. But you can change the sender name, the ‘reply to’ email address and the sender email address.

Sender name customization

You can change the visible name of the sender so that your users can easily identify the sender.

ATTENTION: It is just the name that is replaced. The sender email address will remain the same (noreply.onboarder@ebf.com). See chapter 03.3.7.1.3 to learn how to change the sender email address.

To change the sender name, go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, enter the name that users should see as sender name in the field ‘Notification: From Name’ and save your changes:

NOTE:

• It’s recommended to send a test message to the admin’s email address afterwards to check if all settings are correct (see chapter 05.4).
• If you use Modern authentication, ‘Notification : From Name’ will be prefilled with the mail address of the configured mail account. The ‘From Name’ will be the ‘Display Name’ of the sender.

‘Reply to’ email address customization

You can replace the ‘Reply to’ email address so that your users can directly contact your IT help desk, for example, if they need more information regarding their device migration.

To do that go to ‘Settings’ >> ‘Tenant Settings’ >> ‘General Settings’, enter the email address that users should reply to in the field ‘Notification: ReplyTo (optional)’ and save your changes:

NOTE:

• It’s recommended to send a test message to the admin’s email address afterwards to check if all settings are correct (see chapter 05.4).
• If you use Modern authentication, ‘Notification : From Name’ will be ignored.

Sender email address customization

You can customize the sender email address to adapt it to your company email address.

ATTENTION:

• As you are using the EBF SMTP server, you have to make sure that your mail system accepts EBF messages which appear to be sent by your own SMTP domain but are sent by the EBF SMTP server. You may need to change the whitelisting rules for this and you need to add the following two IP addresses to your SPF record:

SMTP PORT	Hostnames	IP Address
Port 25	smtp-out.ebf.de	176.28.60.183
Port 25	smtp-out.ebf.com	62.138.245.88

NOTE: Currently we are using the smtp-out.ebf.de hostname to send out mails, but we will switch to the smtp-out.ebf.com host in the future. Therefore, we recommend to add both hostnames/Ips.

• You also have to verify that the server will not block the email address after a certain amount of mails which might happen for SPAM protection reasons.
• After making all necessary changes you have to contact the EBF support (support@ebf.com) as the EBF team needs to put the spoofing in place for you and help you test your network and SMTP configurations. Please provide your sender email address and details of the SPF record to the EBF team.

To change the sender email address, go to ‘Settings’ >> ‘Tenant Settings’ >> ‘Mail Settings’ and

• select the service SMTP,
• enter the EBF SMTP server (smtp.ebf.de) in the field ‘SMTP Host’,
• enter ‘25’ in the field ‘SMTP Port’,
• enter the SMTP Username and the SMTP Password of your dedicated user,
• enter the email address (your-address@yourdomain.com) that users should see as sender email address in the field ‘From Email’:

NOTE:

• Save your settings only if you are sure that EBF has prepared the spoofing for you for this new ‘From Email’ address.
• If you want to go back to the SMTP default settings, just clear all the fields and save this.
• It’s recommended to send a test message to the admin’s email address to check if all settings are correct (see chapter 05.4).
• If the sender name should be different from the email address, change this on the ‘General Settings’ page (Notification: From Name).

Email sending using your own SMTP server

If you want to use your own SMTP server to send the emails generated by the EBF Onboarder, you need to get an account from your SMTP team to configure the SMTP server on your EBF Onboarder tenant.

You need to add the following IP addresses to your firewall settings:

Hostnames	IP address
app-out.ebf.com	62.138.245.79

ATTENTION: Every communication (API requests and SMTP) comes from 62.138.245.79. Please update your network appliances accordingly.

To configure the SMTP server on your EBF Onboarder tenant, go to ‘Settings’ >> ‘Tenant Settings’ >> ‘Mail Settings’ and

• select the service SMTP,
• enter the name or IP address of your SMTP server,
• enter the SMTP Port your server is using,
• enter the name of the SMTP Service Account and its password,
• enter the email address your-address@yourdomain.com that users should see as sender email address in the field ‘From Email’:

NOTE:

• EBF default encryption for SMTP is TLS 1.2.
• If you want to go back to the SMTP default settings, just clear all the fields and save this.
• It’s recommended to send a test message to the admin’s email address to check if all settings are correct (see chapter 05.4).

Email sending using an Exchange Online Mailbox

If you want the emails to be sent from an email address of your own organization and with your own domain, you can integrate the EBF Onboarder in Exchange Online.

ATTENTION: On October 1, 2022, Basic Authentication was deprecated by Microsoft for Exchange Online.

Modern Authentication for Exchange Online Mailbox

NOTE: After setting up Modern Authentication, old SMTP configurations will no longer work in the EBF Onboarder.

In order to setup Modern Authentication in the EBF Onboarder portal, you must follow these steps:

1. Please make sure to use a Service Account created with your initial domain (yourcompany.onmicrosoft.com) and not your custom domain (e.g. @yourcompany.com). For the setup in the EBF Onboarder portal, you need its email address and password.
   

   NOTE:

   • Please make sure to login with this user to https://outlook.office365.com to confirm that it is working (e.g. that it is not forced to reset the password).
   • It’s recommended to use a dedicated account only for the migration project as accounts are typically limited to 10.000 mails within 24 hours. In case you have a high number of migrations (>10.000) and the migration mails and reminders will exceed the mail limit, the migration project should be done in waves and mails should be sent out once a week.

2. Create your own app in your Azure Portal. For the setup in the EBF Onboarder portal, you need the Application (client) ID and the Client Secret value of this app.
   • Login into the Azure Portal (Default: https://portal.azure.com/).
   • Within ‘Home’ and ‘Azure services’ click on ‘App registrations’.
   • Register a new app by clicking on ‚New registration‘.
   • Enter a user-facing display name and set up the app for ‚Accounts in this organizational directory only (Single tenant)’ and click on ‚Register‘:
   • You will find your Application (client) ID and Directory (tenant) ID on the next page.
3. Go to ‘API permissions’ on the left side on the same screen and
   • delete the existing permission ‚User.Read’ and confirm,
   • click on ‚+ Add a permission‘ and select ‚Microsoft Graph‘,
   • select ‚Delegated permissions‘,
   • add the following permissions for the Service Account: Mail.Send and Save
   • and ‚Grant admin consent for (your domain)‘.
4. Go to ‘Certificates & secrets’ and set up a new client secret:
   • Press ‘+ New client secret’, provide a meaningful description and select a value for ‘Expires’. It would be possible to choose the planned migration date, but it is recommended to add some months to be prepared for a possible delay.
   • Press ‘Copy the Value’ and save it at a save place as it will not be displayed again.lay.
5. Login to the EBF Onboarder portal, go to ‘Settings’ >> ‘Tenant Settings’ >> ‘Mail Settings’.
   • From the ‘Service’ drop down select your Microsoft Cloud. In most cases ‘Graph – Global Service GCC [DEFAULT]’ will be the right choice.
   • For ‘client id’ enter the Application (client) ID.
   • For ‘client secret’ enter the Client Secret value.
   • For ‘user’ and ‘password’ enter the credentials of the mail user.
   • If you want the mails to be sent from the account saved in the ‘Sent’ folder of the user’s mailbox, check ‘Save Mail to send items’.
   • Click on ‘Test Mail’ to confirm the configuration. An email will be sent to the email address you used to login to the EBF Onboarder portal.

   NOTE:

   • The ‘From Name’ will be the ‘Display Name’ of the sender.
   • ‘Notification : From Name’ will be prefilled.
   • ‘Notification : ReplyTo (optional)’ will be ignored.
   • Currently, every change in the settings will create a test mail to make sure the Mail system is still working.

Exchange Online Mailbox

NOTE: This service might be deprecated for our account.

Follow these steps to integrate the EBF Onboarder in Exchange Online:

• Ensure that you are using a user account with a licensed and enabled Exchange Online mailbox for the email address you want to use for the migration emails.
• Disable multi-factor authentication on this account as this is acting as a service account to forward the emails. The account should use a complex password that either never expires or expires long after the device migration is due to be completed.
• Enable SMTP AUTH on the mailbox being used: Go to the Microsoft Office 365 Admin Center, click on ‚Users‘ >> ‘Active Users‘, select the user account for the mailbox and click on ‚Mail‘. Click on ‚Manage email apps‘, check the option for ‚Authenticated SMTP‘ and save your changes.
• Ensure the mailbox account is exempt from any conditional access rules blocking legacy protocols.
• Go to ‘Settings’ >> ‘Tenant Settings’ >> ‘SMTP Settings’ in the EBF Onboarder portal and enter:
  • SMTP Host = smtp.office365.com
  • SMTP Port = 587
  • SMTP Username = Office 365 Account Username
  • SMTP Password = Office 365 Password
  • From Email = Default email address for this account
• Click on ‚Save Settings‘ and a test message will be sent automatically.

NOTE:

• Here you can read more about how to set up a multifunction device or application to send emails using Microsoft 365 or Office 365 (Option 1 is used in this scenario):
  https://docs.microsoft.com/en-us/Exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365
• Here you can read more about how to enable or disable authenticated client SMTP submission (SMTP AUTH) in Exchange Online:
  https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission

Email sending using your Gmail SMTP

If you want to use your SMTP Server from Gmail to send the emails generated by the EBF Onboarder, you need to follow the following steps:

• Log in to your Gmail account: https://myaccount.google.com.
• Enable two factor authentication for your Gmail account: https://myaccount.google.com/signinoptions/two-step-verification
• Enable an „app password“: https://security.google.com/settings/security/apppasswords (only possible after enabling two factor authentication): Select ‚Other (Custom name)‘ for ‘Mail’, enter any name you want and click on ‘Generate’. The newly generated password will be used in the EBF Onboarder SMTP settings.
• Go to ‘Settings’ >> ‘Tenant Settings’ >> ‘SMTP Settings’ in the EBF Onboarder portal and enter:
  • SMTP Serve = smtp.gmail.com
  • SMTP Port = 587
  • SMTP Username = Your productive SMTP username
  • SMTP Password = Your newly generated app password
• Click on ‘Test SMTP/save’. This should be green now.

03.4. Admin settings

The EBF Onboarder has multi-admin capacity. It provides the opportunity to create several admin accounts that are able to access and use the EBF Onboarder portal with customized rights. The advantage of this multi-admin capacity is that different admins (e.g. from different sites around the world) can conduct the migration of the devices for which they are responsible.

All admins and rights are managed by one super admin or top admin of the tenant. By default, the first administrator who has registered the tenant for his company is the super admin.

• The super admin can create the other admins for the tenant and is the only admin which is able to change the tenant settings (e.g. SMTP settings of the tenant, see chapter 03.3).
• Admins can, by default, manage and monitor all existing migrations without being allowed to change the tenant settings. They are able to change the settings of invitations and reminders and to launch a migration.

There are two additional roles/rights you can add to an admin:

• ‘Create migrations’: This admin can create new migrations.
• ‘Manage administrators’: This admin can create new admin accounts.

03.4.1. Admin accounts overview

To get an overview of all admin accounts you can go to ‘Settings’ >> ‘Admin Settings’:

A list of all admin accounts that have already been created for the tenant will be displayed. The first one in the list is the super admin. The column ‘Administrative rights’ provides information about the rights of the account:

03.4.2. Admin accounts setup

To create a new admin account the super admin or an admin with the right ‘Manage administrators’ needs to know the name and email address of the admin he wants to add. This is necessary since an invitation will be sent to the person as soon as he has been added as an admin. The invitation will ask him to choose his own password which is needed to access the EBF Onboarder tenant as an administrator.

The invitation will be sent by ‘<target> Onboarder’ from the email address ’noreply.onboarder@ebf.com‘ and the subject ‘New Account’.

NOTE: The invitation will be sent to the person as soon as you click on ‘Save Admin’. Thus, it is recommended that you inform the person in advance in order to avoid that he is surprised to receive the invitation from the EBF Onboarder. Also make sure that he understands that he has only 30 minutes to choose his password and activate his account.

The super admin or an admin with the right ‘Manage administrators’ needs to take the following steps to add another admin:

1. 1. Go to ‘Settings’ >> ‘Admin Settings’.
   2. Click on ‘New Admin’.
   3. Enter the name and email address of the new admin and select the rights which he should receive:

NOTE: If you don’t select any of these rights, the admin account will, by default, be able to manage and monitor all existing migrations. He will be able to change the settings of invitations and reminders and to launch a migration.

1. Click on ‘Save Admin’. An invitation will now be sent to the person’s email address.

03.4.3. Edit the admin

You can edit the name and right of an admin:

1. Go to ‘Settings’ >> ‘Admin Settings’.
2. Click on the name of the admin and edit the name.
3. Edit the ‘Administrative rights’ if desired.
4. Press the ‘Update’ button on the right to confirm the change.