Matching
What is matching?
Matching is a process in Domain Move that provides a method for objects between different directories to be paired together for migration and synchronization purposes.
Why is matching required?
Matching is required because it provides a mapping between source and target objects for the purposes of group membership synchronization and email address translation during migration.
What is matched?
All Users and Groups are matched between a source environment and a target.
When does matching occur?
Matching automatically occurs during the discovery process and can be run manually at any time by an authorized project administrator.
How does matching work?
Domain Move will attempt to match users and groups in the source environment with users and groups in the target environment.
During project setup, you may choose up to 3 attribute pairs that Domain Move will use to make this object pairing determination.
Matching is processed in the order listed. If there is no match on the first attribute, Domain Move moves down the list.
With the Integration project type, if no match is found, Domain Move may create the users and groups for you.
What are the projects requirements for matching?
To complete the project setup and match objects, you will be required to setup pairs for Environments, Domains and Attributes for Users and Groups.
Can I run a match myself?
Yes, there is an action available called Match. This action will match an unmatched user or group against the target environment without the need to run a full discovery in source and target.
How do I run the match action?
It’s easy, navigate to the users or group you would like to match. Select the item then select the Match action from the action drop-down menu. Once selected, click the Apply Action button to begin. The status of the object will change to Matching. When successfully complete, the status will change to Matched.
Are there matching logs?
Yes, within the discovery logs, matched objects will be logged. However, the easier method is to export all discovered users and groups. The export of all discovered objects will provide a list of all matched and unmatched objects. Navigate to the user or group management view then select all the objects. Afterwards, select the Export action from the action drop-down menu.
Agents
What is the Directory Sync agent?
The Directory Sync agent is the key component that communicates between a local Active Directory environment and the Directory Sync service.
Where do you install the agent?
The agent must be installed in every forest that you plan to include as a Directory Sync environment. We suggest that you create a virtual machine exclusively for this purpose. Review the Directory Sync Requirements for the minimal hardware and software requirements.
How do I download and install the agent?
First, choose the environment that the agent will be associated with.
You will be able to download the latest version of the agent from the Directory Sync agent screen. Copy the URL and the access key that will be needed during the install of the agent. The downloadable executable is the same for all projects, it is the Registration URL and Registration Key that makes the agent unique when it is installed.
To install of the agent enter credentials that have read or read\write access to the domain, depending on the direction of synchronization.
Copy and paste the information from the Directory Sync agent screen.
No further action is needed on the workstation. A look at services confirms that the Directory Sync agent is running.
A list of agents appears on summary screen, including status information as well as the registration URL and access keys should you need them again in the future.
Where do I manage agents?
To manage agents, simply open the left navigation menu and click Directory Integration, located under Setup, see figure 1.
Figure 1: Domain Move Setup and Settings Menu
How do I manage the agents?
On the Agents page, you can check the current status of your current agents or add new ones. Select an agent for additional options. You have the option to copy the Registration URL or the Registration Key if you need to reinstall the agent for any reason. The History button will give you details on the run history. When the agent is updated, any agent using the old version will offer you the upgrade option so that you can update your current agent installation.
How do I uninstall an agent?
If you need to uninstall an agent from any machine, in order to reinstall on the same machine, you must first delete the registry folder located at HKEY_LOCAL_MACHINE> SOFTWARE> Quest > Agent and then uninstall.
Afterwards, simply create a new agent (with a new access key) under Agents managements from the left navigation menu before re-installing on the same machine.
Discovery
What is discovery?
The discovery service is used to collect user and group identity and properties for the purposes of Domain Cutover preparation.
When discovery is complete, it will have collected all user, group, and contact information within the configured Azure directory environments. It will use this data based on project configuration to find matching objects between environments for the purposes of synchronization.
The Domain Move Directory Discovery Service runs by default every twenty-four (24) hours. This frequency may be changed as needed.
Should I change the default discovery frequency?
After the initial discovery has successfully completed, subsequent discovery jobs will be deltas, which are quicker. Monitor the time it takes to run a delta sync. If the total discovery time exceeds 24 hrs., adjust the frequency to fit the environment size. The more directory objects, the more time a discovery will take. Be sure the initial discovery completed successfully. Otherwise, each new discovery job will run a full discovery again.
The Domain Move Directory Discovery Service may be run at any time by an authorized project administrator.
Can I run a full discovery?
Yes, a full discovery may be run after the initial discovery has completed when required. However, it is recommended that delta discovery be allowed to run to ensure new and modified object changes are processed quickly.
Click the drop-down menu located in the top left corner.
Click the Discovery link from menu.
- Hover over the desired tenant environment.
Click RUN DISCOVERY to begin the process.
When should I run a full discovery?
Full discovery should only be run when previously skipped objects are now required for the project.
Yes, the Domain Move Directory Discovery Service can be disabled at any time by an authorized project administrator. Click DISABLE for the desired environment while in the discovery management page.
To manually disable all future discoveries, follow these steps.
Click the drop-down menu located in the top left corner.
Click the Discovery link from menu.
- Hover over the desired environment.
Click DISABLE to stop all future the processes.
When should I disable discovery?
In most cases, discovery services should not be disabled during an active project. Inactive projects can either be archived if they are no longer required, which will end all related services, or the discovery service can be disabled until the project becomes active.
It is recommended that discovery services be disabled before a Domain Cutover event is started. For more information about Domain Cutovers, review this help article.
Yes, Domain Move provides authorized administrators access to the discovery and tenant logs. To download the logs, simply navigate to the DISCOVERY section from your project dashboard then click the LOGS link for the desired environment.
Domain Cutover
What is a Domain Cutover?
The Domain Move project type includes the “Domain Cutover” or move functionality. After a tenant mailbox and group migration, the next step during a domain consolidation or divestiture project will be to move your registered Microsoft 365 Domain (i.e. Exchange Online Accepted Domain) from one Microsoft Microsoft 365 tenant to another.
Moving a domain from one Microsoft 365 tenant to another is a tedious, multi-step, manually intensive procedure that must be carefully planned and executed at the proper time to ensure a seamless user transition. One of the biggest obstacles during this process is email sent to the domain in transit is not deliverable because it is held until the Domain move is complete. This can cause delays, lost messages and productivity.
The On Demand Migration Domain Cutover is the solution. This powerful feature guides the migration operator through the domain move process, and streamlines many of the steps. It works in conjunction with the Email Relay Service (ERS) to maintain deliverability throughout the move. Mail is never held but delivered on-time, ensuring your users never miss that business-critical message.
Figure 1: Domain Cutover In-Progress
How does Domain Cutover Work?
The Domain Cutover feature is designed to fulfill three major needs when moving an Accepted Domain from one tenant to another. Those are, moving user’s addresses, moving the domain and most importantly, ensure continuity of mail routing during the domain transition.
The Domain Cutover wizard will follow these 6 primary stages. Read through each one before continuing. They provide important details to the process that will help with planning and preparation.
1. Start
During the start of this process Domain Move will validate groups and request some input before beginning.
- Domain Move will warn that any Mailbox or Group not migrated cannot be migrated after the Domain Cutover begins. Note the option to refresh changed Mailboxes and Groups and migrate them again after Domain Cutover is finished is available.
- Choose Replacement Source Domain – When removing a primary address from a source user, it must be replaced with a new domain. Choose the domain to replace the domain being moved. This may impact the user’s UPN, Mail and Proxyaddresses attributes. Note this will remove the source domain name configured for cutover from the source environment.
Choose Target Address Assignment Scope of Users to be Updated – When moving Domains, select how the target address is assigned. This only impacts the target environment. User Logins (userPrincipalName) are not modified in the target user.
i. As Primary Email Address - Domain will be added as the primary email address and will replace the existing primary email address for matched objects.
ii. As Secondary Email Address Only - Domain will be added as a secondary email address for matched objects.
iii. Do Not Update – Domain will not be added for matched objects.
2. Enable Relay
During Step 2, if you have chosen to used the On Demand Migration Email Relay Service, the Email Relay Service (ERS) Relay servers will brought online to service the Domain being cutover to the target tenant. This step can take up to 60 minutes before the relays are activated. Don’t worry, Domain Move will keep you up to date. Once this step is complete you will be able to move onto Step 3.
3. Redirect MX
During Step 3, the DNS administrator of the Domain being moved will execute an update to their public DNS MX record to direct traffic to the ERS Relay Servers. It can take up to 2 hours before an MX record change is propagated globally. Be sure to keep your TTL low during the transition.
After this step is complete, all inbound mail from the Internet for the domain being moved will be routed to the Domain Move ERS relays that were setup during step 2. Mail will be delivered to the target user’s mailbox until step 5 is complete.
The Project Administrator may elect to skip redirection to the ERS relays but instead choose to queue mail using their own systems. This is also acceptable. Domain Move will continue with the remainder of the Domain Cutover process. Quest is not responsible for any mail flow if by-passing ERS is elected.
Important Note to Administrators: If you are using a 3rd party email provider or relay system to receive all Internet mail before directing traffic to the Domain Move, it is recommended that you contact Support with a list of IPs to have them whitelisted during the Domain Cutover process to avoid any mail delivery delays.
4. Move Domain
During Step 4, Domain Move will do most of the heavy lifting. This step is the most complicated, lengthy and error prone depending on the size and complexity of the environment. The following actions will take place during this step. User status will begin to update during this step. The Domain Move Project administrator will also receive notifications if the Domain Cutover fails during these activities and when it complete.
- Read email addresses in source AD and tenant
- Remove email alias addresses (Proxyaddresses) from the source AD and tenant
- Replace Primary address from the source AD and tenant
- Replace User Login (userPrincipalName) from the source AD and tenant
- Remove domain from source tenant
- Add domain to target tenant
- Administrator must verify domain in target (This is a manual step executed by the Tenant Administrator within the Microsoft 365 Admin Portal or using the Powershell Confirm-MsolDomain cmdlet.)
- Add email addresses in target (The target UPN is not modified)
5. Restore MX
During Step 5, the DNS administrator of the Domain being moved will execute an update to their public DNS MX record to direct traffic to the Exchange Online Protection (EOP) (e.g. contoso-com.mail.protection.outlook.como) or another relay service.
After this step is complete, all inbound mail from the Internet for the domain being moved will be routed to the new destination tenant. Domain Move ERS relays will no longer be used.
6. Complete
During this final step of the Domain Move Domain Cutover please allow up to 48 hours for the Cutover Domain wizard to deprovision the ERS engine and cleanup this domain move; this is to ensure that any outstanding mail items are delivered before the service is shut down. During this time, you may be prevented from making certain changes to this Domain Move project.
If all Domains have been cutover and ERS is no longer required it is recommended that it be disabled in the Domain Move Project. Once ERS is disabled, the associated Transport Rules, Groups and Connectors will be removed in the configured Microsoft 365 tenants. The same is true for the Calendar Sharing configured between the tenants using Domain Move. If this feature is disabled in the Domain Move Project, the associated Organization Relationships setup in each tenant will be removed automatically.
What to plan for using Domain Cutover
As each production environment has different operations, standards and policies, be sure to carefully plan your environment’s domain cutover process. While this wizard will assist with specific portions of the domain cutover process, there may be additional reconfiguration necessary to support a successful domain cutover.
Updating the Source Environment
During the 4th step of the Domain Cutover process, the source objects (users, groups, contacts) both local and in the cloud, will have their proxyaddresses and UserPrincipalName (users only) updated to replace the Domain being cutover. Therefore, be sure to plan your local Mailbox migrations beforehand and Unified Groups (Office 365 Groups) and Microsoft Teams must be manually remediated to remove the proxy address or the group must be deleted before proceeding.
Updating the Target Environment
Once the domain has been moved to destination Microsoft 365 tenant during step 4, the wizard will re-assign their addresses (userPrincipalName is not updated, logins remain unchanged) to users and groups that have been matched by Domain Move. However, the wizard will not update the following objects in the target environment:
- Users not Prepared by Domain Move
- Distribution Groups not Migrated by Domain Move
- Mail-Enabled Public Folders
- Mail-Enabled Contacts
Please ensure that these object types are remediated with the proper address after the Domain Cutover is complete.
Other Considerations during a Domain Cutover
- Only one domain can be cutover at a time using Domain Move.
- Disable the scheduled Discovery jobs in all environments before starting the Domain Cutover.
- All Users and Groups in Domain Move must be migrated before Domain Cutover. If not, they cannot be migrated after the Domain Cutover is complete.
- Any user or group in the source that contains a proxyaddress of the Domain being Cutover will have their status updated in Domain Move. Their proxyaddresses will be removed in the source to remove the Domain later. These users will not be able to be migrated afterwards.
- Plan to move or remediate Office 365 Groups (Unified Groups) and Microsoft Teams before the Domain Cutover. Either remove the address associated with the Domain Cutover or delete the group or team.
- Plan to manually reassign primary or alias addresses to Mail contacts, Public Folders or unmatched users and groups in the Target environment.
- Plan to migrate local Exchange Mailboxes before the Domain Cutover.
- Plan to setup the local AD Domains before the Domain Cutover if UPN reassignment is required in the Target environment.
- Plan to move other configurations related to the domain being cutover such as Exchange Policies, Transport Rules, Connectors, EOP Rules, GPOs, etc.
- Remove all Skype for Business licenses from the users in the Source tenant using the Skype for Business Admin Portal. This will remove the Skype for Business SIP address connected to the domain.
- Update your SharePoint Online website address 24 hours before your Domain Cutover.
- You cannot remove a domain that has subdomains. You must first delete the subdomains before you can remove the parent domain.
- The Microsoft Online routing domain that's issued by Microsoft 365 (for example, contoso.onmicrosoft.com) cannot be moved or deleted.
- If using a 3rd party email relay system to receive all Internet mail before directing traffic to the Domain Move mail gateways, it is recommended that you contact Support with a list of IPs to have them whitelisted during the Domain Cutover process to avoid any mail delivery delays.
Domain Cutover Logging
- Domain Cutover Logs – At various stages of the Domain Cutover Wizard the Domain Cutover Logs download link will be presented. Click this link to open the current logs. These logs pertain to the activities being driven by the Domain Move engine.
- User Move Logs – During the Domain Cutover the User status will be updated. Double click a user to display their activity logs. Click on the Move log to review the history of the user’s Domain Cutover process.
- Directory Sync Lite Logs – When the Domain Move engine has a job that needs to be executed on the local Active Directory, it gives this job to Directory Sync Lite. Launch the Directory Sync Lite Console then click the View Logs button to review the actions taken locally.
User Status Types during a Domain Cutover
- Moving – During Step 4 the user’s status will update to the Move state.
- Moved – When Step 4 is complete for the user, their status will change to the Moved state.
- Move Error – During Step 4 if at any time a local user or group cannot be remediated, an error will be logged. Open the user Move log to determine why. Remediate the problem and rerun Step 4.
What account roles are required for Domain Cutover?
There are two accounts used during the domain cutover process. Each require the Global Administrator role to facilitate the process on your behalf.
- Application Service Account – Global Administrator Role
- Binary Tree PowerShell Account – Global Administrator Role
If I lowered my application account roles to the minimum, should I raise them before the domain cutover?
If you have your application account roles are set to the minimum requirements, then assign the Global Administrator role before beginning the domain cutover. Otherwise it will fail, and you will be required to restart the process.
Is my organization required to modify our MX records?
Domain Move does not require you utilize our Email Relay Services to route inbound mail to the target mailbox during the Domain Cutover event. The Project Administrator may elect to skip redirection to the ERS relays but instead choose to queue mail using their own systems. This is also acceptable. Domain Move will continue with the remainder of the Domain Cutover process. Quest is not responsible for any mail flow if by-passing ERS is elected. The Domain Cutover process will still provision the mail relays for your project, this can take as much as 60 minutes to complete. You will not be able to continue to the next step until this process is complete, please plan accordingly.
Are 3rd party email service providers such as Proofpoint or Mimecast supported during a Domain Cutover?
If you choose to have all inbound Internet mail for your domains to be directed to a 3rd party email relay prior to directing the traffic to the Domain Move Email Gateways as recommended, you may experience rate controls being applied, causing email delivery delays.
To avoid this situation, bypass your 3rd party provider during the domain cutover event or contact Support with a list of IPs and dates to have the system whitelisted.
Additional Information on Domain Migrations
- Common Errors when trying to remove a domain from Microsoft 365
- How to migrate mailboxes from one Microsoft 365 tenant to another
- Confirm-MsolDomain