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 tenants. 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 destination tenant. 

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

What is Synchronized?

Using this migration project type in MigrationWiz connects to a Source Entra ID 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 Microsoft Entra is 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 is used as either the Source or Destination Endpoint.
• Although Password Syncing is shown in the Source Agent, it is not supported when Entra ID is used as a Source Endpoint.
• Although Enable Auto-Sync option is shown in the UI, it is not supported when Entra ID is used as a Source Endpoint.
• Although the Simulate Change feature is shown in the UI, it is not supported when Entra ID is used as the Destination endpoint. Using it may unintentionally create objects in the destination.

Prerequisites

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 and Target Environments

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

Create a New Source Application Registration Steps

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

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:

Create a New Destination Application Registration Steps

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

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 below listed permissions need to be added when using Entra ID as the destination:

    • User.ReadWrite.All. Read and updates user profiles.
    • Group.ReadWrite.All. Read and updates group profiles.
    • User.EnableDisableAccount.All. Enables or disables user accounts.

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.
   

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 Microsoft Entra ID 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.

Password Syncing

Password Sync

Assign Random Password

The Random Password feature does not apply for this migration scenario. By default, users are created in Entra ID with auto-generated passwords enabled. Migrated users in the destination will require a password reset before they can log into the destination tenant.

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.

Please review the following video for detailed information on migrating Security Groups when Entra ID is the destination.

Simulate Change

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. 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 Trigger Manual Heartbeat 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.