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.

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.

1. Create the project inside MigrationWiz.
2. Obtain the API keys and download the Source and Target Agent installation files.
3. Install the Source Agent on a local DC in the source environment and configure the collection criteria.
4. Transmit the AD object data to MigrationWiz.
5. Install the Target Agent on a local DC in the target environment and configure the target injection point of the OU structure.
6. 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.
7. Active the synchronization process and the Target Agent will write details on a migration cycle.
8. Lock the Source data, if necessary, (see notes on this later in this documentation).
9. 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.
10. Confirm the Target AD objects are in place, and everything is done.
11. Remove the agents from the Source and Target Agent.
12. 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.

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.

1. Service account with AD objects read (source/target) and write (target) permissions.
2. 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.

1. Select the Active Directory Migration Project on the Create Project page inside the MigrationWiz console.
   
2. 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.
3. 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.

4. 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.
   
5. 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.

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.

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. 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.

5. 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.

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 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.

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.

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.

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.

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.