Overview
Concepts and Terminology
In this documentation, the following abbreviations are used:
- AD = Active Directory
- DC = Domain Controller
- OU = Organizational Unit
- DN = Distinguished Name
- CN = Canonical Name
The AD Migration Project inside MigrationWiz is designed to allow AD object synchronization from a Source AD structure into a Target AD structure.
This synchronization process enables an easy transfer of objects from OUs in the source, recreating the OU structure at any point in the Target AD environment, including the entire user/group structures that can be easily transferred into a target environment with the option to keep these updated when objects are updated in the source. It provides a matching function to allow for the objects in the source to effectively merge with objects in the target based on different criteria.
Any object written to the target environment can then be moved to different OU’s and still be updated by subsequent sync events until they are stopped from syncing in the MigrationWiz console. Overall, the system provides a lot of flexibility in getting AD objects into the target environment as will be shown in this documentation.
In any migration you prepare, the target objects obtain the UPN suffix that is consistent with the default domain in the target AD. However, you can update the target domain suffix in the MigrationWiz console if you wish it to be different. Remember to do this before the first sync takes place.
What is Synchronized?
Using this migration project type in MigrationWiz connects to a Source AD Environment via an installed agent and picks up user and group objects from the selected OU’s. These items are synchronized to the Target AD environment via a Target Agent, as follows:
- Users – User Objects are created and populated with their data from the Source AD Environment
- Groups – Group Objects are created, and the membership is populated with user objects that are part of the migration scope. If the user is a group member and is being migrated as part of the project, then the group membership will persist.
- OU’s – Sub OU’s that are part of the scope of the migration project are also created in the Target AD environment. The structure therefore is preserved and starts at the entry point in the Target AD environment. Details on how this is done can be found in this documentation.
- Devices - This offering currently does not support devices. Support for devices will be added in a later version.
Licensing
This migration type requires the MigrationWiz Active Directory licenses. Groups in Active Directory do not consume licenses to migrate.
Source and Target Agents Requirements
Please consider the following requirements when using Source and Target Agents:
- The server where the agent is installed must be a Domain Controller.
- Connect to and log in to the relevant Source and Target AD environments. The rights needed to perform the appropriate tasks in each agent are:
Agent Type Requirements Source Domain Admin Rights are required in the Source AD 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.
Installation Prerequisites
The table below details the needed packages to be installed for the Source and Target agent to function correctly. Although the agent will prompt for the Windows Desktop Runtime as part of the loading process if it is not installed, it is a preference to install these three before running the agent.
Installation Package Required | Link to Download |
Visual C++ Redistributable 2015-2022 | https://aka.ms/vs/17/release/vc_redist.x64.exe |
Windows Desktop Runtime .Net - v6.0.28 | |
Microsoft .Net 6.0 Runtime - v6.0.28 |
https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-6.0.28-windows-x64-installer |
Important
The Domain Admin rights are required in the OU’s where objects are ‘moved’, after a synchronization so that the object can be continuously updated from the source.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.
Limitations
Please consider the following limitations for this type of migration.
- At this time, the AD Migration project type only supports standard domain suffixes such as .com, and .net, and may not support all non-standard domain suffixes.
If your organization uses a domain suffix that falls outside the standard set, you may face limitations when performing the AD migration process. Please make sure that your domain suffix is compatible before proceeding with your migration project.
Important
Consider that the previous limitation pertains to the BitTitan account username required to log into MigrationWiz via the source and destination agents installed in the Active Directory environments.
Walkthrough of the Migration Process
To sync the AD objects from the source to target environments, follow the steps below.
- Create the project inside MigrationWiz.
- Obtain the API keys and download the Source and Target Agent installation files.
- Install the Source Agent on a local DC in the source environment and configure the collection criteria.
- Transmit the AD object data to MigrationWiz.
- Install the Target Agent on a local DC in the target environment and configure the target injection point of the OU structure.
- In the MigrationWiz console, tag the accounts that you wish to synchronize. Note that piloting a few objects first is important to ensure that you have everything configured to suit your desired outcome.
- Active the synchronization process and the Target Agent will write details on a migration cycle.
- Lock the Source data, if necessary, (see notes on this later in this documentation).
- Rerun the collection on the source environment if updates are needed, these will then be written to the Target AD environment on the same synchronization schedule.
- Confirm the Target AD objects are in place, and everything is done.
- Remove the agents from the Source and Target Agent.
- Use the option to copy the project data into a MigrationWiz migration project for the email if needed.
Completed the process, you would have synchronized AD objects from the source to the Target AD environment. It is worth noting that like any migration project, regardless of type, you would be checking the target thoroughly to ensure that the results are what you expected them to be.
Important
Piloting a migration project is an important step in the whole process. It ensures that everything you have configured in the project is done correctly to match the outcome that you are expecting. With all migration projects, the potential for undesired situations due to misconfiguration of the target environment exists.
Please remember to perform a suitable test strategy and the pilot process is down to the user of the MigrationWiz system. The AD Migration project will go ahead and write/match/update objects based on what you configure in the console.
Prepare the Source and Target Environments
The project's setup generally requires only two configurations, one for the source and one for the target environment.
- Service account with AD objects read (source/target) and write (target) permissions.
- DN references for pickup and delivery points in both AD environments (target and source).
Please refer to the Administrative Accounts section for detailed instructions to grant the service account the necessary permissions. You can find the DN references, which pertain to the naming structure of your domain, by accessing the Users and Computers console in the Active Directory server.
In this example, in the AD Users and Computers, 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 Source and Target Agents in the local environments.
Creating the AD Project
Follow the steps below to create your AD Project.
- Select the Active Directory Migration Project on the Create Project page inside the MigrationWiz console.
- Add the Project Name and the Customer. The customer can be an existing customer from another migration project or a new one. The Project Name is important for the agent configuration, so please copy or paste it to Notepad for later.
- 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.
- 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.
- In the next step, the same API Key is displayed but the link shown is for the Target Agent.
Additional Step
On the Destination Setting page, the location of the data held is configured. There is the option to either have all the data collected from the Source Agent kept in a particular Azure data center based on your region, or to provide an SQL Database Connection String so it can be kept inside an Azure-based storage DB that you have created.
Important
The data collected is held inside the MigrationWiz database and deleted once you remove the project. You must adhere to your own geographic region's requirements for data sovereignty and have it placed in an Azure storage facility that is compliant with your local rules and regulations. Pick the Azure DB region carefully here.
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.
Important
Understanding the Matching Criteria is a critical step in ensuring that your migration project is successful. Please take time to go through the various options and decide the right approach for your migration project. Piloting is an important step and should be part of the migration process.
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.
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.
Important
When it finds a match, the object on the target will be updated with all the information held in the source object. Please be aware that the incoming data overwrites the target data in the object. This includes any matches found for an object in the destination that was not migrated with MigrationWiz.
If no match is found, then the Target Agent will create a new object in the OU structure.
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.
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.
Important
If the Matching Criteria are changed mid-project, it will only take effect on items that have not had their First Run. This is due to the ObjectGUID being read and stored during the First Run pass that it makes.
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.
- Accept the EULA on the front screen by clicking the Accept button.
- Sign in to the MigrationWiz system. Do this with your normal BitTitan login details, the same as you would use in the MigrationWiz console.
- Enter the API Key and Project Name from the Project Configuration screen.
- Enter the local AD credentials that you created as a Service Account for the agent to use.
Important
Just so you know, the Domain is the DN of the local AD where you want to start the access to the AD structure. This is known as the entry point into your AD environment. You can specify the root of the domain, as we have done above, or use an extended DN to pinpoint Ous as the top of the tree.
- Choose the OUs from the displayed list to start the source object scan. This list is developed when the connection to the local AD 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 - AD Source Agent shows a total count of transferred objects after the process runs. From the example above you can see that it transmitted 40 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.
Important
If you rerun the agent and add OUs to scan them, they will be sent to the MigrationWiz console. If you Unselect OU’s and transmit them then they are NOT removed from the MigrationWiz console.
Target Agent Configuration
In the same way the Source Agent was configured, there are 5 steps to complete the installation.
- Accept the EULA on the front screen by clicking the Accept button.
- Sign in to the MigrationWiz system with your BitTitan credentials, the same as you would use in the MigrationWiz console.
- Enter the API Key and Project Name from the Project Configuration screen.
- Enter the local AD credentials that you created as a Service Account for the agent to use.
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.
- 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.
Running the AD Migration Process for the First Time
In the MigrationWiz console, all the objects that were collected from the Source Agent scan process are shown. The console looks very similar to the migration projects that you may be familiar with.
Considerations
The following items should be checked and considered before the first run of a migration project.
- Check that the Source/Target indicators on the status bar are both green, showing that the agents are both connected successfully.
- Make sure that the target OU, where the object will be created, is configured as expected. If it is not found, verify that it is correctly set. This OU structure will be created from the Entry Point that was specified in the Target Agent configuration.
- Select a small number of accounts to test. Ensure you are comfortable with their location and that the matching criteria are as you would expect.
Changing the Target OU
You have the option to change the target Organizational Unit (OU) for creating an object by editing the account in the console and updating the OU. This process can be done for multiple accounts simultaneously.
You can access the edit screen by clicking on the Target OU in the console.
Please note that if you select multiple accounts, the entry appears empty at first instead of displaying a simple edit function. To ensure accuracy and make things easier, we recommend copying and pasting the DN from the Active Directory environment into the Target Agent machine console.
Transformation Options
In the toolbar, you can adjust the transformation options when the AD objects are created in the Target AD environment.
When the Transformation Option window opens, you can configure how the AD objects will be represented in the Target AD environment.
This configuration gives the additional flexibility to rewrite the objects’ UPNs in a way that represents them correctly in the Target AD environment. In some cases, the construct may be different, for example:
If the source uses firstname@domain.com and the target is firstname.lastname@domain2.com. The migration system rewrites the UPN as specified here if required. The default option is to leave the source UPN intact and write it to the Target AD environment exactly as it was.
It is a very useful option to have but again, please use it with knowledge of how you want the outcome to be in the target environment, testing with a small subset of accounts before you run it across the entire estate of the migration.
Running the Migration
Once you select the accounts on the console, you can click on the Write to Target function in the toolbar.
By clicking on the Write to Target button, you confirm that it will write a particular number of objects. To send the objects to the Target Agent for writing, click on OK.
Watching the Target Agent afterward, it will display the items that it has been written including the names of those users/groups it processed.
If you check the Target AD environment, you will notice that the OU structure has been created and the objects placed in the appropriate locations.
After the process has been completed you will see the OU creations as follows.
At this point, to move a group of objects, go back into the project and select them. After selecting the objects, the console will display the status of each object after the write/merge procedure. Please note that all written objects are sorted automatically and appear at the bottom of the list.
All these accounts will now stay synchronized to the target environment.
Updates from the Source Environment
when an object is modified in the source environment and the Source Agent is re-run to scan the objects again, the changes will be detected by the MigrationWiz console and transferred to the target environment within 300 seconds through the heartbeat function of the agent.
This will occur until the object is selected and the Stop button is clicked.
Lock Source
In the MigrationWiz console, the Lock Source option protects the data that is held in MigrationWiz from any updates from the Source Agent. It prevents any changes from being taken through and written to the target AD.
This is useful in some situations where you need to take a point-in-time snapshot of the AD objects in the source environment and not update them even if the Source Agent is rerun.
Note that if you unlock the source and run the Source Agent collection, then any object that is not ‘stopped’ for syncing automatically flow through to the Target AD environment.
Subsequent Migration Passes
Moving Objects
When the Target Agent creates or matches an object in the Target AD environment, its ObjectGUID is recorded in the system. This ensures that in future synchronization events, the matching criteria are no longer necessary and the ObjectGUID becomes the Anchor.
This means you can modify the structure of objects such as UPN and relocate them within the target environment. If the object is in the same domain, the Target Agent will locate it and apply the updates accordingly.
Important
If the Connection DN in the Target Agent is set to a deeper OU and an Object is moved outside of this structure, maybe a different branch inside the AD, then when the ‘update task’ comes through it will still find that object and update accordingly. This is because it will search for the ObjectGUID in the Target AD rather than the DN as a starting point. The DN in the Target Agent is purely there for use as the entry point to create the OU structure for inbound objects.
Continuous Updates to Target Object
With every pass of the objects in the target AD environment, they are set to the data that is contained in the project. This keeps the objects in sync with the source environment.
If you need to update these objects manually, or by other processes, in the target AD environment, then it is important that you 'Stop' the migration of those objects using the console to prevent your changes from being overwritten.
This is achieved with this button in the toolbar. This will prevent any further updates to the object in the target AD environment.
Moving the Project to a Mailbox Migration Project
Upon completing an AD migration project, there is most likely to be a need to use all those UPNs, sources, and targets in a mailbox migration or similar. Built into the console is the option to make a copy of the accounts that are in the AD project and create the mailbox project.
To do this, note that you can only select and copy objects that are User Objects. Groups cannot be selected. They must also have been written to the target as this is the way that the system will track the target UPNs from the Target AD environment.
To perform this task, click on the Export Project option in the toolbar.
It is a requirement that the MigrationWiz Mailbox Project be already created when you perform this task. When the Export Project window opens, you can choose the import configuration and project.
The options for selecting items newer/older than certain dates and endpoint selection are provided to help you locate the specific mailbox project that you want to import. It's important to note that these options are not related to the age of any objects in AD environments.
When the objects appear in the Mailbox Project, the source and target UPNs will match the source UPN and the ‘transformed’ UPN in the target. If you select the default option for transformation, then you can expect the UPN prefix to match the source.
These items are now separate from the AD migration project, and you can do as you wish with that project to process the mailbox data from the M365 source to target.
Final Steps
Once the migration project has been completed then all the following tasks should be performed.
At source perform the following tasks:
- Remove the Source Agent from the Source AD Environment
- Remove/Disable the Service Account used to perform the migration
At the target perform the following tasks:
- Remove the Target Agent from the Target AD Environment
- Remove/Disable the Service Account used to perform the migration
At MigrationWiz Console perform the following task:
- Remove the project from the MigrationWiz console – This will remove the information held about the accounts in the Azure DB storage.
Note that the agents will cleanly uninstall from the normal App installation area in Settings in Windows Server. All the information will be removed as part of the uninstallation process.