A typical migration project using Migration for Active Directory Express can be broken up into four (4)phases.
This user guide walks you through the steps required to complete each phase, which can also be used to migrate devices from AD environments to Entra environments. The Microsoft Entra ID Device Join Quick Start Guide walks you through the process of configuring and performing migrations for AD to Entra migrations.
Best practices for each phase of the migration project are presented below:
Phase 1: Create a Workflow with the Workflow Wizard
-
The wizard begins with selecting the environment type for both source and target environments.
-
Agents for both source and target local environments are deployed.
-
Workflow options are configured and CSV files containing the Users, Groups and Devices to discover from the Source and the Users and Groups to match in the Target are uploaded.
-
Migration Profile, Credential Profile, Credential Cache Profile, Microsoft Entra ID Join Profiles (for cloud environments) and Repositories are configured.
Phase 2: ReACL Devices
-
Run a ReACL (file level re-permissioning) job on as many Devices as possible early in the process.
-
ReACL is a non-destructive process that can be repeated as often as necessary up until Cutover in Phase 5.
-
Troubleshoot any Devices with ReACL jobs which did not complete successfully.
-
Run a ReACL job again close to the actual Cutover date. This will allow you to complete most of the ReACL process early and provide time to resolve any issues with things such as anti-virus software and Group Policies.
Phase 3: Cutover Devices
-
Using some test Devices, Users, and Groups, verify a successful Device Cutover.
-
Typically, a final ReACL job should be run the weekend before the scheduled Cutover to ensure any new Users and other changes are processed.
-
A workstation reboot is required after the target account is enabled, the source account is disabled, and the Cutover is complete. This is usually completed in the evening when fewer end-users are impacted. Any impacted end-users should be alerted that this reboot is necessary.
-
Optionally, use the Autopilot Cleanup option to prepare the AutoPilot-provisioned device for migation. This must be done before the cutover if the source Entra ID Joined device is Autopilot-provisioned and the Entra ID Join Profile has the Autopilot/Intune Cleanup option selected.
Phase 4: Cleanup
-
The Cleanup phase typically takes place about two months after all Device Cutovers are complete. During the Cleanup phase, all permissions should be removed from the source domain and then the Active Directory agent should be removed from the Devices.
-
Optionally, use the Set Intune Primary User action after the Device Cutover is completed.
Networking
Outbound Internet Access
By default, each computer being migrated will require outbound access to the public Internet to securely communicate with the On Demand Migration services.
Important Tip: If your organization requires computers communicate externally using a web proxy see our web proxy configuration requirements.
Application Ports
Each computer being migrated will require the Active Directory device agent and this agent will communicate to the On Demand Migration services, outbound over ports:
Domain Controller Ports
Active Directory migrations also require a variety of Microsoft defined ports for communication between domain controllers. For a complete list of required ports, click here.
Important Tip: For complete port information, review the Service overview and network port requirements for Windows documentation from Microsoft Support.
Accounts
Local Active Directory Account
- The agent installer will prompt for a domain account with permission to read and write on-premises Active Directory.
- An agent intended to sync all domains in a forest, must have access rights to all domains and objects used in workflows.
Microsoft Entra ID Application Account
- When creating a new Cloud Environment, an account with the Global Administrator Role is required to grant permissions and establish a connection.
- This account also needs the Global Administrator Role enabled during the first Read workflow so that it can create and configure Microsoft Entra ID PowerShell Accounts required for Directory Sync tasks.
Microsoft Entra ID PowerShell Accounts
- An OAuth token will be used by the application to create two (2) PowerShell accounts which are used to read and update objects in the cloud.
- The accounts will have Exchange Administrator, User Administrator and Teams Administrator roles assigned in order to read and update objects in the cloud.
- The accounts being used do not require any Microsoft 365 licenses.
- The accounts must be excluded from MFA requirements.
- An OAuth token will also be used by the used by the application to create a mail-enabled security group which will contain the two PowerShell accounts.
Agents
Migration for Active Directory Express is a 100% SaaS platform but to commit changes to on-premises directories (if applicable) such as Active Directory, a local agent must be installed and configured.
You will need at least one Directory Sync Agent installed per forest (environment). You may have up to five agents per forest. Adding more agents can offer limited fault-tolerance and can improve synchronization throughput, especially for near real-time password synchronization.
Important Tip: If you are only connecting to Microsoft Entra ID, local agents are not required.
Devices
The following is required for any Active Directory Computer(s) (devices) that will be migrated.
Device Agents
Each Active Directory Computer that will be migrated must have an agent installed on the workstation to orchestrate local jobs that must occur to prepare and execute the workstation’s domain move.
Operating Systems
All computers or servers being migrated to the new domain must run one of the following operating systems:
- Windows 10
- Windows 11
- Windows Server 2016
- Windows Server 2019
- Windows Server 2022
Please Note: Entra ID Device Join is only supported for Windows 10 and 11.
PowerShell
- All client operating systems must have at least PowerShell 2.0 installed.
.NET Framework
- All Devices must have .NET Framework 4.7.2 or newer installed. This will appear as ".NET 4.7.2 Extended" in the add/remove programs list.
- If not present, an appropriate version of .NET Framework will be installed during agent installation if an internet connection is available.
Remote Devices
To successfully migrate a remote employee’s remote device using the Offline Domain Join (ODJ) feature the Cache Credential action must be run to collect the user’s target credentials, so later you may cutover the device, while it is disconnected from the network.
The following is required:
Cached Credentials Action
- One-way external trust must be configured from the source domain to the target domain when the Cache Credential activity is processed
For more information about AD Trusts, check out this MS Press article about configuring trusts.
Network
• Network connectivity to both the source and target environments (Active Directory Domain Controllers) when the Cache Credential activity is processed
Important Tip: Offline domain join files must be created prior to running the Offline Domain Join process. A full explanation of Microsoft’s Djoin.exe utility and how to create these files can be found here.
How do I set up Offline Domain Join (ODJ)?
For complete details on how to set up ODJ, click here.
Web Proxy
Some organizations may require all computers communicating externally direct their traffic through a web proxy to centralize communications. Active Directory agents can be configured to use a web proxy for communication to the On Demand Migration cloud services.
Proxy Server
- At least one (1) standard web proxy that supports http/TCP traffic.
Proxy Address
- The associated web proxy URL must be defined during configuration of the device agent.
Security
- If accessing the web proxy requires an additional username and password this will be required during configuration of the device agent.
Ports
All agents configured to use a web proxy will utilize the following outbound TCP ports:
Please Note: Agents configured to use a web proxy will not require UDP port 3030. For more information, see the Web Proxy Configuration under Architecture.
Important Tip: Additional bandwidth overhead may occur when a web proxy is utilized to centralize all traffic.
Repositories
The following four Device Actions, when used, will require a defined storage share accessible from the device being migrated:
- Upload Logs
- Device Download
- Offline Domain Join
- Microsoft Entra ID Cutover
How do I configure repositories?
For complete details on how to configure repositories, click here.
What is a Workflow?
A workflow is a configurable series of steps that provides an easy automation framework to connect and manage Directory object synchronization. Activities such as creating, updating and deleting objects along with property/attribute synchronization and transformation.
How do I create and manage Workflows?
To create a Worklfow, simply open the left navigation menu and click Create a Workflow in the side navigation menu, see figure 1, or click the New button under Workflows on the dashboard. The Workflow Wizard will open and will guide you through the creation of the Workflow.
To manage a Workflow, click the Manage button under Workflows on the dashboard.
Figure 1: Side Navigation Menu
What should be entered as the Workflow Name?
You can name your workflow anything you'd like but remember that you may be referencing the same environment in multiple workflows. We suggest a name that generally describes the flow of objects. Then use the description field for the distinguishing characteristics. After this step, the wizard will guide you through all the necessary components that will make up your workflow.
What are the steps to create a Workflow?
Migration for Active Directory Express uses a wizard interface to guide you through the steps of creating and configuring the Workflow. To launch the wizard, click Create a Workflow in the side navigation menu or click the New button under Workflows on the dashboard.
Steps of the Workflow Wizard:
-
Select Environment Types - You are prompted to select the environment type for both source and target environments. Options are Local (a traditional on-premises Active Directory environment.) and Cloud (a Microsoft Entra ID environment.) See the Environments topic for more information.
-
Configure Source Environment:
-
Provide source environment name - Provide a descriptive name for the source environment that makes it easy to identify. For example, the Bluefish Resort on-premises Active Directory environment could be named bluefishresort.com.
-
(For Local Environments) Provide a name for the agent - Enter the name of the server used as the Directory Sync Agent. Directory Sync Agent is needed to connect to the local Active Directory Environment. See the Agents topic for more information.
-
(For Local Environments) Deploy a new agent - Download the Agent and use the provided information when installing the agent software on a domain-joined machine. See the Agents topic for more information.
-
(For Local Environments) Deployed Agent status -The current status of the agent deployment.
-
(For Cloud Environments) Connect to your Cloud Environment - Add a commercial or GCC tenant. Important: A Service Principal and two PowerShell service accounts will be created in the tenant. These service accounts must be excluded from MFA requirements, as described in the Account Prerequisites
-
Configure Target Environment:
-
Provide target environment name - Provide a descriptive name for the target environment that makes it easy to identify. For example, the Bluefish Resort on-premises Active Directory environment could be named bluefishresort.com.
-
(For Local Environments) Provide agent name - Enter the name of the server used as the Directory Sync Agent. Directory Sync Agent is needed to connect to the local Active Directory Environment. See the Agents topic for more information.
-
(For Local Environments) Deploy Agent - Download the Agent and use the provided information when installing the agent software on a domain-joined machine. See the Agents topic for more information.
-
(For Local Environments) Deployed Agent status - The current status of the agent deployment.
-
(For Cloud Environments) Connect to your Cloud Environment - Add a commercial or GCC tenant. Important: A Service Principal and two PowerShell service accounts will be created in the tenant. These service accounts must be excluded from MFA requirements, as described in the Account Prerequisites
-
Configure Workflow:
-
Name the Workflow - You can name your workflow anything you'd like but remember that you may be referencing the same environment in multiple workflows. We suggest a name that generally describes the flow of objects. Then use the description field for the distinguishing characteristics.
-
Users File to import for scoping and matching - Upload a CSV containing the Users to discover from the Source and the Users to match in the Target. Note that Import file must include ObjectID’s. The file must include at least one user to continue.
-
Groups File to import for scoping and matching - Upload a CSV containing the Groups to discover from the Source and the Groups to match in the Target. Note that Import file must include ObjectID’s
-
Devices File to import for scoping and matching - Upload a CSV containing the Devices to discover from the Source. Note that Import file must include ObjectID’s
-
Select OU’s in which to create objects - This is the Organizational Unit where you plan to store any newly created objects.
-
Choose your target domain - Select from the list of domains.
-
Password Settings - Enter the default password for new users. Note that the password policy on the source must meet or exceed the policy on the target.
-
(For Local Environments) Configure Migration Profiles - Configure the Device Migration options. See the Migration Profiles topic for more information.
-
(For Local Environments) Configure Credential Profiles - Credentials Profiles contain the source and target administrator’s credentials and domain information used during an Offline Domain Join (ODJ) or remote device cutover process. See the Credential Profiles topic for more information.
-
(For Local Environments) Configure Credential Cache Profiles - Credentials Cache Profiles contains the target domain controller information required to cache a user’s target credentials prior to the Offline Domain Join (ODJ) cutover process. You may skip this step if Offline Domain Join is not in-scope of your migration project. See the Credential Profiles topic for more information.
-
(For Cloud Environments) Microsoft Entra ID Join Profile - Microsoft Entra ID Join Provisioning Package file contains the target Microsoft Entra ID information used during Microsoft Entra ID Device cutover process.
-
Repositories - Repositories are specified storage locations on your network used for the following specific job types. See the Repositories topic for more information.
-
Downloads - See the Downloads topic for more information.
-
Summary - Please verify that all of the information has been correctly entered. Click the Edit button next to information that needs to be changed. Click Run Workflow to start the workflow or click the X button to finish changing the wkflow without running the workflow.
