- Subject
- Microsoft 365 & SharePoint
- Filed
- Source
- [email protected]
- Loans
- 707
Active Directory Domain Migration: Mapping Users, Groups and OUs
Plan discovery, matching, passwords and relationships before moving AD objects. A pilot and staged validation help catch gaps that can affect Microsoft 365 access.

An Active Directory domain migration succeeds when the destination directory works as intended, not simply when the expected number of objects appears in it. Users, groups, contacts and managers can sit in different organizational units (OUs); existing destination accounts may need to be matched; and choices about passwords, group membership and SID history affect whether people and applications can use the new environment.

That makes discovery and relationship mapping central planning tasks. Selecting a department’s OU gives the team a starting point, but it doesn’t define the complete scope. The engineering users in a typical carve-out, for example, could belong to groups in another OU, rely on supplier contacts elsewhere, or report to a manager outside the selected branch. The migration plan needs to find those dependencies and establish what should happen to each one.
AvePoint Fly supports migrations of Active Directory users, groups, contacts and OUs between domains. Its workflow can be used with standalone Active Directory and with Active Directory connected to Microsoft Entra ID in a hybrid setup. The directory work still needs its own decisions and checks: device transitions, cloud identities and Microsoft 365 content are separate workstreams.
Define scope and destination design first
Begin by deciding what the destination should contain. Identify which source objects are in scope, where they should land, and whether each one should be created or matched to an existing destination object. Fly supports mapping users, groups and contacts into existing or newly created destination OUs.
| Object type | Documented support | Planning question |
|---|---|---|
| Users | Active Directory users and supported attributes | Should the person receive a new account or match an existing destination account? |
| Security and distribution groups | Global, universal and domain-local scopes | Which members and related objects must be available at the destination? |
| Contacts | Active Directory contacts and supported attributes | Which contact details and relationships must the destination retain? |
| Organizational units | Supported; destination OUs may already exist or be created | Where should migrated objects belong? |
Check default containers separately. Fly excludes built-in directories such as Computer and System from Active Directory migration. In the Builtin and Users containers, manually created objects can migrate, while preconfigured system objects cannot. An object’s presence under a selected branch therefore doesn’t establish that it is eligible. Review the actual objects and confirm which ones belong in the project.
Keep the scope clear when coordinating with other migration teams. This plan covers directory objects. A Windows device transition, Microsoft Entra ID identity work and Microsoft 365 content migration need their own configurations and validation, even when they form part of the same wider project.
Prepare connections, agents and permissions
Fly uses agents for the source and destination Active Directory environments. Set up the corresponding Active Directory Users and Groups connections, generate connection keys and configure each agent for its role. Before the pilot, prepare certificates, service accounts and network access required by the selected functions.
Plan agent deployment around the domains involved. Each connection is limited to one domain. In a multidomain forest, the migration process recommends using multiple agents to connect to the relevant domains. It also recommends installing agents on machines outside the domain controllers that can reach the appropriate Active Directory environment. Installing an agent on a domain controller is technically supported, but it isn’t required; a machine that can communicate with the domain controller can host an agent.
Check agent-host requirements separately from supported Active Directory versions. Confirm connectivity to AvePoint Online Services, Fly and the directories, along with the LDAP, LDAPS and RPC access required for the functions in scope. Password and SID-history scanning require RPC availability, so teams planning either function should validate that access before running a migration job.
Choose the destination attribute configuration early. By default, connecting the destination creates an attribute named flymigrationExtensionAttribute. The documented default configuration requires a destination service account with domain-admin and schema-admin permissions. The documented custom-attribute option requires domain-admin permissions. Review the choice with the directory owner and confirm the account permissions before deployment.
Set matching rules and OU placement deliberately
The migration policy controls how Fly matches objects, handles conflicts and configures options such as password synchronization and group membership. Matching rules run in sequence: if one rule doesn’t find a match, Fly tries the next. When no rule finds a match, Fly creates a destination object. Explicit user mappings take precedence over attribute-based mappings. If a source object has multiple potential destination matches, its migration stops for review rather than choosing one automatically.
Review the rules against both directories before the first run. A source user could become a duplicate destination account if the selected attribute doesn’t identify the intended existing account. A single match also needs to be checked: matching values alone don’t establish that the destination identity belongs to the right person.
After migrating an object, Fly saves its globally unique identifier (GUID) and uses it in subsequent jobs when source attributes change. That can help maintain consistent matching in later runs, but the initial match still deserves manual review. Establishing the right mapping early gives later incremental work a sound starting point.
Choose the conflict behavior for the destination design. Skip ignores a conflicting object. Overwrite changes the destination object’s attributes based on the source. Review existing destination objects and decide which behavior fits before applying the policy to a production wave.
Once connections and policy are prepared, create an Active Directory project. Add scanned objects in tree or search mode, or import mappings using the Excel template. The template identifies source users and groups by sAMAccountName, and contacts by cn, alongside the source OU, destination OU and object type.
Check naming and placement together. When a mapping specifies a destination object, Fly uses that object to generate the destination user’s User Principal Name (UPN), overriding the policy’s automated UPN format. This deserves a review before the pilot, especially when an account is being renamed.
Discover members and managers beyond the selected OU
Group membership depends on the member objects being ready in the destination. Each member must exist there, its OU must have been scanned by Fly, and it must match through the configured rules. Creating the group object doesn’t prove that all of its members have migrated or that its membership is complete.
Manager relationships have a similar dependency. To migrate the manager of a user, group or contact, the manager must be scanned into Fly and must exist in the destination. Include managers in discovery even when they fall outside the department’s initial OU boundary.
For a carve-out, use discovery to identify relationships that should change as well as those that should be carried over. Record the intended destination relationship and have the relevant owner review it. This helps avoid recreating an outdated relationship simply because it existed in the source.
The practical scope is therefore a set of related objects, not a single OU branch. Build the scan plan around users, groups, contacts, managers and any other dependencies included in the approved project. Then check that the objects needed to complete relationships are present in the scan and destination mappings.
Include contacts and their dependent attributes
Contacts should appear explicitly in scope and acceptance checks. Fly supports contact attributes including display name, email, company, department and phone information. Confirm which attributes the destination and dependent applications need. Some Exchange-related contact attributes are supported only when creating a new destination object, so creating a contact and updating an existing one aren’t equivalent cases.
Include a representative supplier or business contact in the pilot when contacts are part of the migration. Check its destination OU, required business attributes and any in-scope group or manager relationship. If an application uses the contact, ask its owner to validate that dependency as well.
Presence in the directory isn’t proof that every communication feature works. Address-book visibility and mail flow need checks in the relevant systems. Treat those as separate acceptance tests and confirm the result with the owners of the services that depend on the contact.
Resolve password and SID-history requirements before migration
Password planning depends on whether Fly creates the destination user. For users created during migration, the Sync user passwords policy option supports password synchronization. If it isn’t selected, Fly’s Active Directory migration policy documentation states that newly created destination users will be unavailable after migration. For existing destination users that Fly didn’t create, use the Sync user passwords post-migration job.
Include credential readiness in the pilot. A newly created destination account shouldn’t be treated as a usable sign-in until the planned password behavior has been checked. Confirm the expected result for both new accounts and matched existing accounts.
SID history needs separate preparation when it forms part of the approved access plan. Complete the documented SID-history preparation, configure the source scan and destination agent, and enable the corresponding migration-policy option. Because password and SID-history scanning require RPC availability, confirm the network requirement before those scans begin.
Enabling the SID-history option doesn’t establish that every resource-access dependency is covered. Define access checks with the application and infrastructure owners, then validate the relevant resources after migration. Keep password and SID-history decisions in the domain migration plan even if identity or security specialists handle the implementation.
Use a pilot to exercise the difficult cases
A useful pilot tests variation, not just whether a straightforward job can finish. A batch of new users with no existing matches won’t exercise matching, cross-OU membership, contact attributes or manager relationships. Select examples that put the project’s important decisions under review.
| Pilot case | What to verify |
|---|---|
| A new user and an existing destination user | Correct creation or matching, destination OU, selected attributes and planned password behavior |
| A group with members in different source OUs | Scan coverage, destination availability, matching and resulting membership |
| A supplier contact and a manager relationship | Required contact attributes and destination relationships in scope |
| A controlled source change after the first pass | Rescan, incremental migration and applicable post-migration actions |
These cases can be grouped by complexity to help with pilot planning. A lower-complexity case is a new user or group with no existing destination match and an unambiguous destination OU. It mainly tests standard attribute-based creation and placement.
A moderate case could be an existing destination account that needs attribute reconciliation, or a group whose members have been scanned across several source OUs. The checks then need to confirm that the matched identity is correct and that member scan coverage is complete.
Higher-complexity cases include contacts with Exchange-dependent attributes, managers outside the initial scan boundary, resource access that depends on SID history, and source changes that require a rescan. They call for focused review of contact attributes, cross-OU discovery, SID-history preparation and the sequence of rescan before incremental migration. These tiers are a suggested way to organize testing, not a built-in Fly template.
Before execution, review scanned objects, project mappings and policy. For the first run of selected mappings, use Migration → Full migration and confirm that an agent is active for the destination connection. Inspect the results before expanding the scope. The pilot should resolve mismatches, missing dependencies and unexpected attribute behavior.
Rescan source changes before incremental runs
Staged migrations need a way to handle changes between waves. After the initial migration, Fly supports incremental runs for newly added or updated directory objects and for objects with prior errors or warnings. When source objects change, rescan them on the source agent before running the incremental migration.
For example, if an engineering user’s department attribute changes after the pilot, refresh the source scan, run the relevant incremental job and check the destination value against the configured conflict behavior. A change in the source is a reason to refresh discovery before expecting an incremental run to reflect it.
An OU move or relationship change may also call for a relevant post-migration action. Review newly discovered objects against the project’s scope and mappings. Discovery alone doesn’t make an object part of the current migration wave.
Run post-migration actions and validate results
Fly provides four Active Directory post-migration actions:
- Sync user passwords.
- Migrate object managers.
- Migrate group membership.
- Sync objects OU changes.
Use the actions that fit the selected mappings and approved stage. Membership can be handled through the migration policy, but the member prerequisites still apply. For a post-migration membership job, confirm that required members are available and mapped. Check manager availability before running the manager job.
Use Sync objects OU changes deliberately when the source OU structure changes. The destination may have a different design, so a new source location doesn’t automatically establish that the object should move to the corresponding destination location. Check the intended placement first.
Fly’s mapping history records actions performed. Property reports can show attribute names with their old and new values; membership reports identify successful and failed members. Migration and error reports can be viewed in the product or exported as CSV or Excel files.
Use those records alongside destination checks. Verify that accounts landed in the intended OUs, existing users were matched correctly, group memberships are complete, contacts retain required attributes, and manager references resolve to the intended destination objects. Where appropriate, carry out sign-in and application-access checks agreed with the relevant owners. Those acceptance tests cover business dependencies; they aren’t automatic validation of every application by Fly.
Export final reports and archive the mappings before closing the directory workstream. When migration is complete and agents are no longer needed, follow the documented agent-removal process.
Carry identity decisions into connected workstreams
A completed directory migration doesn’t itself complete a Windows device transition, move Microsoft 365 content or prepare every cloud identity. Each requires its own configuration and validation. Where those activities belong to the same project, carry approved identity decisions into their plans.
Destination identities and mappings support user-dependent content details such as memberships, task assignments, file attribution and permissions in connected Microsoft 365 or hybrid Entra ID environments. Group membership and manager relationships carried across from Active Directory can also feed permissions used by Microsoft 365 applications and connected AI agents, including Copilot. An incomplete relationship can therefore affect what those tools can access for a person.
AvePoint’s 2026 State of AI research found that nearly nine in 10 organizations delayed AI initiatives by an average of almost six months because of unresolved data security and data management concerns. That figure is attributed to AvePoint’s research. For migration teams, the practical connection is that accurate identities, permissions and relationships provide part of the groundwork for wider modernization efforts.
The destination should be judged by more than its object count. It should have intentional OU placement, verified matches, the required relationships and a record of what the team checked. Review matching rules and placement again before each production wave, since source attributes and destination objects can change between waves. A domain migration is ready for the next workstream when its identities and dependencies have been validated against the agreed plan.
Common planning questions
How does a user migration differ from a group migration?
A user migration creates or matches a destination account using attributes such as sAMAccountName. Fly saves a GUID after migration to support later matching. A group migration has an additional dependency: members must already exist in the destination and must have been scanned and matched. The group object can be present even when its membership remains incomplete, so validate the group and its members separately.
How long does an Active Directory domain migration take?
Fly doesn’t specify a fixed duration. Timing depends on the number of migration waves, the number of agents needed in a multidomain forest, and how much rescanning and incremental work is generated by changes. A pilot that exercises different matching and relationship cases gives teams a more useful basis for planning production waves than a single assumed timeline.
Does this workflow cover Microsoft 365 content or Windows devices?
No. The workflow described here covers directory objects: users, security and distribution groups, contacts and OUs. Windows devices, Microsoft Entra ID identities and Microsoft 365 content have separate migration workstreams and validation. Fly can support those migrations, but completing Active Directory work doesn’t complete them automatically.
Does the process support a hybrid environment connected to Microsoft Entra ID?
Yes. Fly’s Active Directory-to-Active Directory workflow supports local-only Active Directory and hybrid setups connected to Entra ID. Moving connected cloud identities between Entra ID tenants is a separate workflow.
What is SID history, and when might it be needed?
SID history preserves a user’s earlier security identifiers so the user can retain access to resources that still check identities against the previous domain. It requires its own preparation: the documented SID-history scan, a destination agent configured for it and the related migration-policy option. Password and SID-history scanning both require RPC availability. SID history doesn’t apply to Entra ID tenant-to-tenant migration, which uses cloud-native attribute matching.
What do Skip and Overwrite do?
Skip ignores the conflicting object and leaves the existing destination object unchanged. Overwrite replaces destination attributes based on the source. Review the destination design and existing objects before choosing the behavior for each wave.
How often should teams review mappings and OU placement?
Review them before each production wave, not only during initial setup. Destination objects can be added, source attributes can change, and the selected conflict behavior still needs to fit the intended destination design. Confirm the mappings and policy against current conditions before running the next set of objects.
