#Install the Active Directory Migration Agent

Refer to the following sections to prepare and install the Active Directory migration agent.

#System Requirements

Refer to the following table for the system requirements of the Fly Active Directory Migration Agent.

Components	Requirements
Operating System	Windows Server 2016, Windows Server 2019, Windows Server 2022, Windows 10, Windows 11*Note: 32-bit operating systems are not supported. Only operating systems with Desktop Experience are supported.
Number of CPU Cores	Recommended: 4 or above.
Available Physical Memory	Recommended: 8 GB or above.
Available Disk Space	Refer to Comment 1 below the table.
.NET Framework Version	.NET Framework 4.7.2 to 4.8.
Net.Tcp Port Sharing Service	Net.Tcp Port Sharing Service has started.
Transport Layer Security (TLS) Version	TLS 1.2 is enabled.
Visual C++ Redistributable Version	Visual C++ Redistributable 2015-2022.

Comment 1: The Agent server will store the temporary files and job logs of migrations.

• We recommend 50 GB or above for migration projects with less than 100 GB of data.

• We recommend 100 GB or above for large migration projects with more than 200 GB of data.

  When checking the installation rules, Fly checks the storage space of your drive C by default. Make sure there is available space of 2 GB or above in your drive C.

#System Services Port Requirements

Refer to the following information for the system services port requirements of the Fly Active Directory Migration Agent.

Application Protocol	Protocol	Ports
Lightweight Directory Access Protocol (LDAP) Server	TCP	389
Remote Procedure Call (RPC)	TCP	135
RPC randomly allocated high TCP ports	TCP	49125 - 65535
Lightweight Directory Access Protocol over SSL (LDAPS) Server	TCP	636

For more details, refer to How to configure RPC dynamic port allocation to work with firewalls.

#Network Requirements

Before performing Active Directory migrations in Fly, make sure the network of the server where you want to install the Active Directory agent can connect to the AvePoint Online Services, Fly, and the source/destination Active Directory.

If your organization has an access policy and only specific IP addresses are allowed, you need to navigate to AvePoint Online Services > Administration > Security > Reserved IP addresses to download the list of reserved IP addresses required by AvePoint Online Services and Fly, and then add the IP addresses to the safe IP address list of the server where you want to install the Active Directory agent.

#Permission Requirements

Before performing Active Directory migrations in Fly, prepare the following accounts for the migration:

• Local Administrator of the system where the agent will be installed is required by the installation.

• Source Active Directory agent: A service account that is the domain admin of the source Active Directory.

  You can also prepare a user account with sufficient permissions instead of a domain admin by completing the following steps:

  1. Open Active Directory Users and Computers.

  2. Locate and right-click the domain name, and then click Properties.

  3. On the Security tab, click Add and select the user you want to assign permissions to.

  4. In the Permissions section, select Allow for the following permissions:

     • Add/remove replica in domain

     • Reanimate tombstones

     • Enable per user reversibly encrypted password

     • Manage replication topology

     • Add GUID

     • Read only replication secret synchronization

     • Run Protect Admin Groups Task

     • Write domain password & lockout policies

     • Write Other domain parameters (for use by SAM)

     • Migrate SID history

     • Unexpired password

     • Replicating Directory Changes

     • Replication synchronization

     • Replicating Directory Changes All

     • Update password not required bit

  5. Click the Advanced button. In the Advanced Security Settings window, select one of the permission entries, and click Edit.

  6. On the Permission Entry window, select the following permissions and properties:

     Type	Entries
     Permissions	List contents
     Permissions	Read all properties
     Permissions	Write all properties
     Permissions	Read permissions
     Permissions	Create all child objects
     Permissions	Delete all child objects
     Properties	Read all properties
     Properties	Write all properties

  7. Once completed, click OK.

• Destination Active Directory agent: If you want to use the default flymigrationExtensionAttribute attribute, a service account that is both a domain admin and a schema admin of the destination Active Directory is required.

  If you want to use custom attribute, a service account that is the domain admin of the destination Active Directory is required.

#Download Agent

You can either download the Active Directory agent when creating a connection for Active Directory migration or follow the steps below to download the agent:

1. Click Settings in the left pane, and select Agents > Active Directory agent tab.

2. Click the down arrow next to Download agent, and then click Download source agent or Download destination agent to download the corresponding agent.

3. In the panel, click Download.

4. To verify whether a downloaded package has been tampered with, check its hash value and compare it with the one displayed in the panel. Following the steps below to obtain the hash value from the package:

   1. Extract the downloaded agent package.

   2. Open Windows PowerShell and enter the following commands:

      Get-FileHash -Algorithm SHA256 -Path "[file path]"

      Replace [file path] with the full path of the ZIP file in the extracted package.

      

#Install the Source Agent

Refer to the following steps to install the source Active Directory agent:

1. Copy the downloaded ZIP file of the source agent to the machine where you want to install the agent.

2. Extract the file.

3. Right-click the Setup.exe application file in the extracted folder, and select Run as administrator.

4. On the installation wizard, configure the installation path and click Next.

5. Fly will perform a brief pre-scan of the environment to ensure that all rules meet the requirements. The status for each rule will be listed in the Status column.

   

   For details about the system requirements, refer to System Requirements.

   NOTE

   You cannot proceed with the installation if any of the rules have a Status of Failed.

6. Click Next to install the agent. When the installation is finished, click Configure now to configure settings for the agent.

   

7. In the Connect AvePoint Online Services step, configure the following settings:

   • AvePoint Online Services application (client) ID – Enter the ID of your app registration in AOS > Administration > App registrations. Note that the fly.admigration.readwrite.all permission is required for this app registration.

     

   • Certificates – Enter the certificate thumbprint in AOS > Administration > App registrations. For how to upload a new certificate, refer to the Register an App section in Configure App Registrations for detailed information.

     

   • Note the following:

     • Client secrets are not required for the connection.

     • The certificate (.pfx) must be installed on the Local Machine that has source Active Directory agent installed.

       

   • Proxy settings – Configure the following settings:

     • Proxy Host – The hostname or IP address of the proxy server.

     • Proxy Port – The port used to access the proxy server.

     • Username – The username to log in to the proxy server.

     • Password – The password to access the proxy server.

8. Click Next to go to the Connect Connection step.

9. In the Connect Connection step, configure the following settings:

   • Connection key – Paste the connection key you copied when you create the connection.

   • Connection name – After you entered the API key, the name of connection you created will be automatically filled in and cannot be edited.

   • Shared key – Enter 6 to 15 characters as the shared key. This key is used to encrypt Active Directory user passwords before sending them to the Fly database for migration. You need to save the shared key and provide the identical one to the destination agent for decryption.

   NOTE

   We recommend that you connect only one Active Directory agent per connection.

10. Click Next to go to the Connect Active Directory step.

11. In the Connect Active Directory step, configure the following settings:

    • Active Directory server information – Enter the host or IP: port of the source Active Directory.

      NOTE

      If you are using port 636 for the connection, a distinguished name (DN) is required for the service account. The SID migration may fail if port 389 is blocked by the source domain controller.

    • Domain – Click Connect to retrieve the domain name of the source Active Directory.

    • Service account – Enter the account of a domain admin of the source Active Directory.

    • Password – Enter the password for the account specified above.

12. Click Next to go to the Scan Source Objects step.

13. In the Scan Source Objects step, select the OUs you want to scan. You can also enter the OU name in the search box to search for the OU.

14. Click Next to go to the Scan Schedule step.

15. In the Scan Schedule step, configure the following settings:

    • Scan security properties:

      • User passwords – Select this to scan and migrate the user passwords. Note that the Remote Procedure Call (RPC) server must be available for this migration.

      • Security Identifier (SID) History – Select this to scan and migrate the Security Identifier (SID) History. Note that the Remote Procedure Call (RPC) server must be available for this migration. Before performing the SID History migration, refer to the Prepare for SID History Migration section for detailed preparation steps.

    • Scan method:

      • Scan and send now – Select this to scan source objects and send the scanned objects to Fly immediately.

      • Scan on a specific date and time – Configure the start and end date and time, and the interval of recurring jobs.

16. Click Submit to save your configurations.

#Install the Destination Agent

Refer to the following steps to install the destination Active Directory agent:

1. Copy the downloaded ZIP file of the destination agent to the machine where you want to install the agent.

2. Extract the file.

3. Right-click the Setup.exe application file in the extracted folder, and select Run as administrator.

4. On the installation wizard, configure the installation path and click Next.

5. Fly will perform a brief pre-scan of the environment to ensure that all rules meet the requirements. The status for each rule will be listed in the Status column.

   

   For details about the system requirements, refer to System Requirements.

   NOTE

   You cannot proceed with the installation if any of the rules have a Status of Failed.

6. Click Next to install the agent. When the installation is finished, click Configure now to configure settings for the agent.

   

7. In the Connect AvePoint Online Services step, configure the following settings:

   NOTE

   The same app registration can be used for both source and destination agents.

   • AvePoint Online Services application (client) ID – Enter the ID of your app registration in AOS > Administration > App registrations. Note that the fly.admigration.readwrite.all permission is required for this app registration.

     

   • Certificates – Configure the certificate thumbprint in AOS > Administration > App registrations. For how to upload a new certificate, refer to the Register an App section in Configure App Registrations for detailed information.

     

     Note the following:

     • Client secrets are not required for the connection.

     • The certificate (.pfx) must be installed on the Local Machine that has destination Active Directory agent installed.

     • You can choose to create a new certificate for the destination agent or use the same one as the source agent. In either case, the certificate (.pfx) must be installed on the Local machine that has destination Active Directory agent installed.

       

   • Proxy settings – Configure the following settings:

     • Proxy Host – The hostname or IP address of the proxy server.

     • Proxy Port – The port used to access the proxy server.

     • Username – The username to log in to the proxy server.

     • Password – The password to access the proxy server.

8. Click Next to go to the Connect Connection step.

9. In the Connect Connection step, configure the following settings:

   • Connection key – Paste the connection key you copied when you create the connection.

   • Connection name – After you entered the API key, the name of connection you created will be automatically filled in and cannot be edited.

   • Shared key – Enter the same shared key configured in the source agent. It is required to decrypt passwords while syncing the passwords for destination Active Directory users.

   NOTE

   We recommend that you connect only one Active Directory agent per connection.

10. Click Next to go to the Connect Active Directory step.

11. In the Connect Active Directory step, configure the following settings:

    • Active Directory server information – Enter the host or IP: port of the destination Active Directory.

      NOTE

      If you are using port 636 for the connection, a distinguished name (DN) is required for the service account. The SID migration may fail if port 389 is blocked by the source domain controller.

    • Domain – Click Connect to retrieve the domain name of the destination Active Directory.

    • Service account – Enter an account that is both a domain admin and a schema admin of the destination Active Directory.

    • Password – Enter the password for the account specified above.

    NOTE

    After the destination Active Directory is connected to Fly, a new attribute named flymigrationExtensionAttribute will be created in the destination Active Directory by default.

    To use your own custom attribute instead of the default flymigrationExtensionAttribute by completing the following steps:

    1. On the server where the agent is installed, navigate to...\FlyAdAgent\DestinationAgent\bin.

    2. Open the appsettins.json file.

    3. Add the following command:

       "EXTENSION_ATTRIBUTE_NAME": "<attribute name>" Replace "<attribute name>" with the name of your desired single-string attribute.

       

    4. Once completed, save your updates. The configured attribute will be used for migration. We recommend you restart your Fly Destination AD Agent Service for the changes to take effect.

12. Click Next to go to the Advanced settings step.

13. In the Advanced settings step, you can turn on the toggle to enable the Security Identifier (SID) History migration if required. Note that before performing the SID History migration, refer to the Prepare for SID History Migration section for detailed preparation steps.

14. Once enabled, configure the following settings:

    • Source Active Directory server – Enter the host or IP: port of the source Active Directory.

    • Domain – Click Connect to retrieve the domain name of the source Active Directory.

    • Service account – Enter the account of a domain admin of the source Active Directory.

    • Password – Enter the password for the account specified above.

15. Click Next to go to the Import Objects step.

16. In the Import Objects step, configure the interval time for importing objects from Fly to the destination agent. The unit is Second.

17. Click Finish to finish the installation of the destination agent.

#Prepare for SID History Migration

Before performing the Security Identifier (SID) History migration, you need to complete the following steps to prepare for the migration:

1. Create a local group in the source domain:

   1. Open Active Directory Users and Computers.

   2. Locate and right-click the required OU and select New > Group.

   3. In the New Object - Group window, enter the group name using the following format: <source domain’s NetBIOS name>$$$.

      For example, if the NetBIOS name of your source domain is FLY, the group name must be FLY$$$.

      You can run the following commands in PowerShell to retrieve the BIOS name of your source domain: (Get-ADDomain).NetBIOSName.

      NOTE

      The SID History migration will fail if members are added to this newly created local group.

2. Enable TCP/IP client support on the source domain PDC emulator:

   1. On the domain controller in the source domain that holds the PDC emulator operations master (also known as Flexible Single Master Operations or FSMO) role, navigate to Start menu> Run.

   2. In the Run window, enter regedit in the Open field, then click OK.

      

   3. In the Registry Editor window, Go to the following registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\LSA

   4. Locate the TcpipClientSupport registry entry (type: REG_DWORD). Right-click it and select Modify....

   5. In the Edit DWORD (32-bit) Value window, enter 1 in the Value data field.

      

   6. Click OK.

   7. Close Registry Editor window and restart the computer for the change to take effect.

3. Log on as an administrator to any domain controller in the destination and source domain.

4. Navigate to Start menu > Administrative Tools > Group Policy Management.

5. In the Group Policy Management window, navigate to Forest > Domains > Domain Name > Domain Controllers > Default Domain Controllers Policy.

6. Right-click the Default Domain Controllers Policy, and click Edit. The Group Policy Management Editor window appears.

   NOTE

   If you cannot edit the policy, you can try to re-open the Group Policy Management Editor window by navigating to Start menu> Run. In the Run window, enter gpmc.msc in the Open field, then click OK.

   

7. Enable auditing in the destination and source domain by following the steps below:

   1. In the Group Policy Management Editor window, navigate to Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Audit Policy.

   2. In the right pane, configure the following audit policies:

      • Audit account management policy – Right-click it, and then click Properties. Select Define these policy settings, select both the Success and Failure checkboxes. Click Apply then OK.

      • Audit directory service access – Right-click it, and then click Properties. Select Define these policy settings, select the Success checkbox. Click Apply then OK.

   3. To apply the policy immediately, open an elevated Command Prompt and run the following command: gpupdate /force.

8. Enable the advanced audit policy in the source and destination domain by following the steps below:

   1. In the Group Policy Management Editor window, navigate to Computer Configuration > Policies > Windows Settings > Security Settings > Advanced Audit Policy Configuration > Audit Policies > Account Management.

   2. In the right pane, configure the following policies by right-clicking each one and selecting Properties. Then click Configure, select both the Success and Failure checkboxes, and click Apply and then OK.

      • Audit Application Group Management

      • Audit Computer Account Management

      • Audit Distribution Group Management

      • Audit Other Account Management Events

      • Audit Security Group Management

      • Audit User Account Management

   3. In the Group Policy Management Editor window, navigate to Computer Configuration > Policies > Windows Settings > Security Settings > Advanced Audit Policy Configuration > Audit Policies > DS Access.

   4. In the right pane, configure the following policies by right-clicking each one and selecting Properties. Then click Configure, select the Success checkbox, and click Apply and then OK:

      • Audit Detailed Directory Service Replication

      • Audit Directory Service Access

      • Audit Directory Service Changes

      • Audit Directory Service Replication

   5. To apply the policy immediately, open an elevated Command Prompt and run the following command: gpupdate /force.

   NOTE

   It may also be necessary to reboot the domain controller to have auditing take effect. Even with group policy applied on the default domain controller for the domain audit, the server audit setting on the primary domain controller (PDC) may not be enabled. Please confirm this setting is enabled for the local security policy on the PDC server. If not enabled, use the local security policy to enable this setting.

#Account Permissions

To perform a SID History migration, specific permissions must be configured in both the source and target domains:

• Migrate SID History permissions in the destination domain. This is typically granted to Domain Admins and Enterprise Admins by default.

• To grant this permission to a specific user or group:

  1. Open Active Directory Users and Computers.

  2. Right-click your destination domain and select Properties.

  3. In the Properties window, click Security tab.

  4. Click Add to add required groups and users, or select an existing one to update.

  5. In the Permissions for Everyone section, select the Allow checkbox for Migrate SID history.

  6. Click Apply then OK.

• Source credential’s administrator access to the source PDC emulator. This is typically granted to Domain Admins and Enterprise Admins by default.

• To grant this permission to a specific user or group:

  1. Open Active Directory Users and Computers.

  2. Navigate to the Builtin container and double-click the Administrators group.

  3. On the Members tab, check if the source service account is a member of the group. If not, click Add to add the source service account.

  4. Click Apply then OK.