Overview

The Active Directory Migration Project within MigrationWiz is designed to facilitate seamless identity synchronization between a source and target using Microsoft's Entra ID and Active Directory tenant. This process enables the efficient transfer of identity objects—such as users and groups—while preserving organizational structure and access configurations.

By leveraging Entra ID’s robust identity management capabilities, the migration ensures that objects from the source environment are accurately replicated in the target On-Premise Active Directory tenant. 

The following guide shows the scope and requisites when using Microsoft Entra ID as Source in Active Directory Migrations.

What is Synchronized?

Using this migration project type in MigrationWiz connects to a Source AD Environment via Entra ID. These items are synchronized to the Target environment via a Target Agent, as follows:

• Users – User Objects are created and populated with their data from the Source Environment.
• Groups – Security Group Objects are created, and the membership is populated with user objects that are part of the migration scope. If the user is a member of a Security Group and is being migrated as part of the project, then the group membership persists.
  • Members of a Security Group are added automatically, while Security Group Owners must be added manually.
  • Regardless of the Membership type that is used for a source security group, the Membership type of the migrated security group in the destination will be set as Assigned.
  • Mail-enabled Security Groups will be created as Standard Security Groups in the destination tenant.

Licensing

This migration type requires one MigrationWiz Active Directory license per user being migrated. Groups do not require a migration license.

Limitations

• App password usage, MFA/2FA, and ADFS are not supported for the migration service accounts being used for this migration scenario.
• Filtering options for Users or Groups are not available when using Microsoft Entra as the Source Endpoint. All Users and Groups will be automatically discovered and imported into the MigrationWiz project.
• Distribution Groups or Lists (DLs) are not migrated when using Microsoft Entra ID as either the source or the destination endpoint.
• Although the SID History and Computer Move options are shown in the UI, they are not supported when Entra ID is used as either the Source or Destination Endpoint.
• Although Password Syncing option is shown in the UI, it is not supported when Entra ID is used as a Source Endpoint.
• Although Enable Auto-Sync option is shown in the Source Agent, it is not supported when Entra ID is used as a Source Endpoint.
• For Domain Controllers (DC) running Windows Server 2025, the agent must be installed and run from directly from the domain controller. Remote use of the agent is not supported at this time for server 2025.

Prerequisites

Target Agent Requirements

Please consider the following requirements when using On-Premise Active Directory Target Agent:

• Connect to and log in to the relevant Target AD environments. The rights needed to perform the appropriate tasks in each agent are:

  Agent Type	Requirements
  Target	Domain Admin Rights are required in the Target AD

• Create these accounts specifically for the MigrationWiz AD migration project, limit the rights of the account to these criteria, and remove them once the project has been completed.

Considerations

• The password is not stored in any plain text functions inside the agent and it is also NEVER transferred or used in the MigrationWiz SaaS platform for any tasks. It is purely for agent-based, local read, or write functions only.
• The Agents perform all of the transactions over port 443. Consider that these transactions are ‘outbound initiated’.
• MigrationWiz backend reaches out to the agent at no time, it is always based on the AD Agent ‘asking’ the backend the work it needs to perform.
• Suppose you wish to apply a Domain Admin membership to the Source and Target Agent account and this is an acceptable policy inside your organization. In that case, it is certainly a function that will allow the writing of the objects inside your Target AD seamlessly. Please consider the security implications of having an additional DA account and guarding the password.

Entra ID Properties Mapping

The following properties are included in the migration process when Microsoft Entra ID is selected as the source or destination. Please review them carefully:

Prepare the Source Environment

The project's setup requires you to you to Create a New Application Registration, Obtain the AppID and TenantID from the Application Registration and to Create a Client Secret.

Create a New Application Registration Steps

Create a new Application Registration in the Microsoft 365 source tenant.

1. Log in to the Microsoft Entra admin center with a Global Administrator login.
2. Click View all products and select Entra ID (Azure AD) in the Microsoft Entra Admin Center.
3. In the left sidebar, open the Applications dropdown list and select App Registrations, which is found under the Identity dropdown list.
4. Select New Registration at the top of the screen.
   
5. Give the app a distinct name. You can change this later if necessary.
6. Select the Accounts in this organizational directory only ('Tenant name only' - Single tenant) radio button.
7. Click Register.

8. In the Overview tab, you will find the Application (client) ID.

9. Copy it to another application, such as Notepad, for use later in this process (endpoint creation).

10. Under the Manage menu, select Authentication.

11. Set the option Allow public client flows to Yes.

12. Click Save.
    

13. From the Manage menu, select API permissions.

14. Click Add a Permission.

15. Select Microsoft APIs (default window).

16. Select Application permissions.

17. The following permissions need to be added when using Entra ID as the source:

    • User.Read.All. Read user profiles.
    • Group.Read.All. Read group profiles.
    • GroupMember.Read.All. Read all group memberships.

18. Click Add Permissions. Thеse permissions only allows the OAuth application (MigrationWiz) to be associated with the GraphAPI.

19. Click Grant admin consent.

20. Click Yes to confirm the settings. Under the Status column, you should see a message that permission has been granted for the domain.

Your API permissions should look like this:

Obtain the AppID and TenantID from the Application Registration

Follow the steps below to obtain the AppID and TenantID from the Application Registration.

1. Navigate to the App Registrations item as shown below. In the Overview tab, you will find the Application (client) ID and the Directory (Tenant) ID.
2. Copy both of these to another application, such as Notepad, for use later in this process. This is needed for the MigrationWiz Project Setup.
   

Create a Client Secret

Create a Client Secret for the application by following the steps below.

1. Go to Manage > Certificates & secrets from the left sidebar.
2. Create a new secret client by clicking + New client secret.
3. Copy and save the client secrets' value on a notepad or other preferred tool.
   

Prepare the Target Environment

The project's setup typically requires only one configuration for the target environment.

1. Service account with AD objects read and write permissions.
2. DN references for pickup and delivery points in the target AD environment.

In this example, in the AD Users, the Advanced Features are turned on which opens more functionality when right-clicking on objects amongst other things. By right-clicking on the top-level item, we can see that the DN reference is as shown.

This information becomes very useful as you go through and configure the Target Agent in the local environments.

MigrationWiz Steps

Create an Active Directory Migration Project

1. Click the Go to My Projects.
2. Click the Create Project.
3. Create an Active Directory Migration Project.
4. Click Next Step.
5. Enter a Project name.
6. Select or create a Customer.
7. Select the Source Agent Type. Select Microsoft Entra ID and then click on the Next Step button.
   
8. Select the Destination Agent Type. Select Active Directory and then click on the Next Step button.
   
9. Click Next Step.
10. On the next screen, you get the API key. This is loaded into the Source and Target Agents.

    Important

    The API key is the same for both the source and Target Agent. Record this on a Notepad as well for easy source and Target Agent configuration.

11. The download link for the Source Agent is also presented on this screen. Download this installation file and keep it ready for placing in the source environment.
    

12. In the next step, the same API Key is displayed, but the link shown is for the Target Agent.

Understanding the Matching Criteria

The last item to configure in the project setup is the Matching Criteria. This is found in the Advanced Options for the Project, available on the screen following the previous step but also accessible anytime through the project console.

The criteria are found in the Source/Destination section, as shown here.

When clicking on the Matching Criteria, the following dialog box is shown.

The default item is the SAM Account Name, also known as Alias. The matching options are the following:

• Email Address
• SAM Account Name
• UPN Prefix
• Full UPN
• Employee ID
• CustomAttribute1 (Extension Attribute)
• Display Name
• CUSTOM (user-defined field)

Note the use of CUSTOM means that you can provide any AD field existing in your environment and the matching takes place on that item.

Default Organizational Unit (OUs) Name

During a migration to an On-Premise Active Directory Endpoint, default Organizational Units (OUs) are automatically created and named as "OU=CloudUsers" to organize migrated objects.

Here is what it would look like:

Keep in mind that the default OU names are fully editable and can be changed whenever needed.

Password Syncing

Password Sync

Assign Random Password

The Assign Random Password option is only available if the Password Sync is not selected in the Advanced Options menu. The random password assigned to the account is similar to standard Microsoft passwords, but with a bit of extra complexity to meet the requirements of the destination Active Directory.

While typical password rules include at least 8 characters with a mix of upper- and lower-case letters, numbers, and special characters, this setup uses 10-character passwords to ensure compatibility with stricter policies and to add more security.

Enable Account in Target

The Enable Account in Target option ensures that the migrated user account is enabled. By default, accounts without a set password are created in a disabled state. This setting is enabled by default, along with the Assign Random Password option, to ensure accounts are both assigned a password and activated.

Migration First Run

The matching function takes an item in the Matching Criteria, in this case, SAM Account Name. Then, it searches for the SAM Account Name in the target environment.

The system then records the ObjectGUID of the Target AD object and uses that for future updating of the object. If things change on the target object, moving, among others, then the system finds it based on the ObjectGUID that is unique to that object.

Simulate Change

The Simulate Change option is a toggle option that is Disabled by default. When enabling this option, the Target Agent will read it for the batch and in the status page of the Agent in Runtime, the object will not be written to the target Active Directory, but instead it will add the item to the log file (verbose) that shows exactly what items and properties would be written in this migration.

In the Target Agent report, the results will be showed in Purple as shown below:

Migration Future Passes

Once a match has been made by the first run of the object migration attempt consider that:

• The system continues using the obtained ObjectGUID.
• The Matching Criteria will no longer apply to it.
• The two objects are bound together by that initial ObjectGUID pick which ensures that no additional AD objects are created in the case that the matching criteria change and would no longer apply to that object combination.

Agent Installation and Configuration

Install the agent by taking the installation file from the project configuration and placing it on any machine part of the source/target domain.

If the agent can see a DC in its local environment, then it will use the administrative credentials that you supply it to attach to a local DC and extract data or write data.

The installation does not need to be carried out on a DC itself. Once you have run the installation you will be presented with the configuration screen.

Source Agent Configuration

There are five steps to complete the Source Agent configuration.

1. Accept the EULA on the front screen by clicking the Accept button.
   
2. Sign in to the MigrationWiz system. Do this with your normal BitTitan login details, the same as you would use in the MigrationWiz console.
   
3. Enter the API Key and Project Name from the Project Configuration screen.
   
4. Choose the OUs from the displayed list to start the source object scan. This list is developed when the connection to Entra ID is created.
   

Using this screen, you can select everything you wish to scan and then press the Start Scan and Transmit button as shown. This will take those objects and place them in the MigrationWiz, ready for matching/writing to the target environment. 

Once done, MigrationWiz - Entra ID Source Agent shows a total count of transferred objects after the process runs. From the example above you can see that it transmitted 63 objects into MigrationWiz.

As the source scan is a single event, the agent can be closed now. It does not continuously synchronize or transmit objects to the MigrationWiz console. This is only done when you click on the Start Scan and Transmit button.

The Reselect OUs to Scan button clears all the selections and lets you start fresh with the selection.

Detailed Log

The Detailed Log displays the number of objects transmitted to the MigrationWiz Console, providing a general indication of transmission activity to offer more detailed insight.

The status screen includes a dropdown option that expands to show the scan status of each object that has been updated or written. This allows for greater visibility into the transmission process, particularly when tracking updates or newly added objects.

Please consider that when the Do Not Update from Source option is enabled in the line item edit tab, the following will appear in the detailed log:

Auto Update Source Agent on Start

When launching an existing build of the Source Agent, an auto-update popup will appear, notifying of a new version and prompting for an update if available.

If 'Yes' is selected, the popup closes, and the Agent must manually be reopened. Upon reopening, the updated build agent is launched.

Enable Auto-Sync

Although the Enable Auto-Sync option is shown in the UI, it is not supported when Entra ID is used as a Source Endpoint. 

Target Agent Configuration

In the same way the Source Agent was configured, there are 5 steps to complete the installation.

1. Accept the EULA on the front screen by clicking the Accept button.
   
2. Sign in to the MigrationWiz system with your BitTitan credentials, the same as you would use in the MigrationWiz console.
   
3. Enter the API Key and Project Name from the Project Configuration screen.
   

4. Enter the AD credentials that you created as a Service Account for the agent to use.
   

   • AD Server URL. Specify the URL or network address of the Active Directory (AD) server used for authentication and directory services. Installation can be done locally or on non-Domain Controller machines.
     

     Important

     If your domain controller is running on Windows Server 2025, the agent must be installed and run on the 2025 server. Enter Local for the AD Server URL.

   • Username. The username used to authenticate in the Active Directory server.
   • Password. The password associated with the Active Directory username.
   • Domain. The Active Directory domain name in DC=domain prefix, DC=domain suffix format.

   When entering the DN for the Domain field, it is important to note that this determines where the Target Agent begins building the OU structure for the newly created accounts. In the provided example, the top of the tree is used. This is the preferred method for creating the objects in the target AD. In the example, the Distinguished Name that is used is:

   DC=planeium, DC=com

   This is obtained using the User and Computers console and right-clicking on the entry point you want to select. 

   

   Important

   The MigrationWiz AD system creates the entire OU structure underneath the entry point you select. It does NOT simply drop all the accounts into a flat OU.

5. The Target Agent now sits and waits for work to be done from the MigrationWiz console. The heartbeat is set to 300 seconds (5 minutes), but you can change it to a longer interval if you require it. The value of 300 seconds is the minimum setting.
   

If necessary, you can click the Get Ad Objects Now button to trigger the collection of objects to synchronize immediately.

Auto Update Destination Agent on Start

When launching an existing build of the Destination Agent, an auto-update popup will appear, notifying of a new version and prompting for an update if available.

If 'Yes' is selected, the popup closes, and the Agent must manually be reopened. Upon reopening, the updated build agent is launched.