Applies to: Office 365 Dedicated Topic Last Modified: 2014-04-02 The information in this guide describes the requirements, policies and process that govern how Microsoft and subscribers to SharePoint Online Dedicated plans validate and fulfill the prerequisites when they migrate SharePoint Online users to a new domain. Domain migration is the process of moving users from one domain to another without compromising security or losing existing user permissions. There are various scenarios that necessitate domain migrations. Here are two examples: Company acquisitions and divestitures where users with the acquired company must be migrated to the parent company s domain. A migration from another directory service to Active Directory. These and other situations can require domain name changes or domain consolidations or separations. When a user is migrated across domains, the domain name, user name, and Security Identifiers (SID) change, and SharePoint must be updated to avoid a mismatch in the SharePoint database. If this is not done, the Portal, Team, and My Site access control list (ACL) will not be accurate, making the site inaccessible to the user. For detailed information about domain migration, see: Domain Migration Overview Planning Requirements and Recommendations Domain Migration Tool Configuration and Operation Additional Considerations
Requirements The most important component of a successful and timely domain migration is a comprehensive migration plan. Customers must create a plan to remediate the known failure modes identified for SharePoint Online domain migrations. The SharePoint Online Domain Migration Planning Template is provided for this purpose. Using this guide and the associated planning template, your organization can identify and capture all the known facts related to a domain migration and perform the tasks required for successful completion of the migration, including submission of the required configuration requests (CRs). In addition to planning and remediation, you must perform the following tasks, all of which are described later in this guide: Submit the appropriate CRs at the appropriate points in the process. Create a document library. Create and upload.csv files to the appropriate document library. View and verify migration results. Submit a monthly migration status update. After your organization has completed and submitted a domain migration plan, Microsoft: Reviews the high-level domain migration plan and provides feedback to ensure there are no scheduling conflicts between the required activities. Reviews the domain migration plan and verifies that your organization has a remediation plan for the known failure modes. Deploys the Domain Migration Tool (DMT) in Microsoft test environments for complete execution of the plan as part of release verification. The benefits of following this domain migration process include: Microsoft planning experience. Microsoft has experience in evaluating how different migrations scenarios are managed and can suggest input early in the migration process. Structured process. Microsoft aims to bring structure to the complex domain migration process and provides remediation to the known failure modes. Important: The policies and process described in this guide do not cover overall migration for your organization. The scope is limited to remediation of user profiles and permissions for domain migrations. Active Directory information captured and covered here is limited to what is required for user profile and permission remediation. For instance, no Active Directory
migration remediation steps are included. Instructions apply only to domain migrations for SharePoint Online.
Domain Migration Overview Topic Last Modified: 2015-03-09 Microsoft uses the Domain Migration Tool (DMT) to migrate SharePoint Online user permissions shortly after users Active Directory accounts are migrated to a new domain, or when users Active Directory account names change. The DMT calls the STSADM o-migrateuser command and executes the command in bulk. Your organization can use the STSADM o-migrateuser command to do on-premises testing prior to the actual migration. To ensure a successful domain migration, you must complete certain prerequisites before Microsoft can ready your SharePoint farm for migration. The following diagram depicts the phases in the planning and migration process and the parties responsible for each task. A description of the process follows the diagram. Planning Process This section describes the high-level steps that your organization needs to accomplish before domain migration can take place in the SharePoint Online pre-production environment (PPE). 1. Envision. Your organization creates a vision and scope document for domain migration and gets the requisite in-house executive sign-off. You submit a CR through the Microsoft Service Deliver Manager (SDM) expressing the intent for domain migration. Microsoft recommends that you start this process soon after the vision and scope document is approved by its executives. This will help you to plan effectively, keeping all the Active Directory planning in mind. 2. Plan. Your organization creates a domain migration plan using the SharePoint Online Domain Migration Planning Template. Note: This is not a Standard Configuration List item. The domain migration plan created using the planning template must include the following for Microsoft review: Project scope. Migration plan. Remediation steps for known failure modes identified in the policies presented here. For more information, see Known Failure Mode/User Experience Impact Remediation Requirements.
DMT configuration and scheduling requirements. The planning template must include the CR number You can choose to hire Microsoft Consulting Services to help create the plan or execute the plan on your own. 3. Review/Approval: Microsoft reviews the domain migration plan. Approval of the migration plan is based on the details provided for remediation of known failures. The outcome of this phase is the approval to install the DMT. The goal of this review process is to assess your organization's readiness to proceed with DM and fulfill the pre-requisites. The engagement is not a replacement for end-to-end domain migration planning and remediation. 4. Execution Action (PPE). You create a request to execute all pre-migration CR s listed in the signed off planning template in PPE first. The CR list will be per the section 3.0 of the approved planning template. Deploy (PPE). DMT is installed in PPE after the approval. After the PPE is validated and signed off, the DMT is installed in production. Action (Production). SharePoint Online executes all pre-migration CRs signed off on PPE. The CR list will be per the section 3.0 of the approved Domain Migration planning template. Deploy (Production). The DMT is now installed on your production farm and configured according to the details provided in section 3.2 of the approved Domain Migration planning template.
Microsoft requires a status update from your organization on a monthly basis against the approved domain migration project plan (as defined in the DMT policy) using the Customer Request Analyst System (CRAS). For the template used to communicate this status, see the monthly status update template. The DMT is uninstalled from yourr production farm after the specified domain migration end date. Domain Migration Tool Installation Timeline The following table shows the key milestones that your organization must understand to ensure a successful deployment of the Domain Migration Tool (DMT) to the SharePoint Online PPE and production environment. Action Timing Your organization submits the domain migration plan through your Microsoft Service Delivery Manager (SDM) You must use the Domain Migration Planning Template. Microsoft reviews the planning document. You notify the SDM of your intent to submit CRs that were the outcome of the planning template. The DMT is installed on your PPE farm, if approved. You migrate users in three PPE. Microsoft deploys the DMT to production, if PPE signs off. Microsoft uninstalls the DMT from production. Within 5 business days. Within 5 business days. Within 3 business days of execution of all business CRs (follows standard implementation process). Per your project plan. Within 3 business days (follows standard implementation process). Within 3 business days domain migration end date specified in document.
Planning Requirements and Recommendations Topic Last Modified: 2015-03-09 This section presents the requirements that are essential for completing your domain migration plan. It includes the following: Planning recommendations. Scheduling recommendations for Active Directory migrations impacting domain migrations. Remediation steps for known domain migration failure modes. Daily migration sequence during the DMT run. The remediation steps described must be detailed in the domain migration plan, and you must submit the associated change requests (CRs) through your Microsoft Service Delivery Manager (SDM). To create the domain migration plan, use the SharePoint Online Domain Migration Planning Template available from the Customer Extranet site. Planning Recommendations In order to plan for successful migration, the following components need to be understood and considered. Active Directory migrations User Profile Synchronization User Log on account/domain
Your organization's representative must have expertise in these areas in order to successfully plan and execute domain migrations. Active Directory Migration Recommendation You plan your SharePoint Online domain migration during Active Directory migration planning to understand the dependencies: 1. Service Account must always be migrated first. 2. User Groups should be migrated before users. 3. Site Collection Admin and other administrator accounts should be migrated next.
Note: User group migration is not part of DMT. Group migration is a manual process where the group needs to be re-permissioned. Known Failure Mode and User Experience Impact Remediation Requirements In this section, various failure scenarios are described along with the necessary remediation steps. In order to make your online environment aware of the changes in domain and reorganization, certain changes must be made. These changes will be requested using the CR process by submitting the CRs mentioned below. In the absence of these changes, your online environment, user profiles, and People Picker may not work correctly for the migrated users. Forefront Identity Manager Impact and Remediation Microsoft Forefront Identity Manager (FIM) is used to facilitate synchronization between multiple endpoints. For example, FIM sits between Active Directory and the User Profile Service Application and is responsible for syncing changes between both endpoints. Without a healthy FIM, SharePoint synchronization will cause undesired results. User Experience Impact The following scenarios describe the FIM filters impact on domain migrations. User Experience Issue Scenario When new Active Directory domains are introduced, the user profile for the user in the new domain will not be populated in SharePoint Online. It will result in incomplete user profiles in people search. Remediation. Create a new User Profile Sync connection point to the new domain. The old domain connection can remain, but the migrated users can be disabled using FIM filters. Domain Migration Failure Scenario If new Account Profiles are imported in the SharePoint Online farm before running the DMT, the migration will fail. SharePoint User Profile Synchronization connection connects with Active Directory to import all user profiles from an Organizational Unit (OU) container specified in the user profile connection configuration. Applying FIM filter allows filtering user profiles from an OU container specified in the user profile connection configuration that SharePoint Online is importing users from. Your organization
may have specific user accounts that they don t wish to be synchronized with SharePoint Online. For example, if new account profiles are imported in the SharePoint Online farm before running the DMT, the migration will fail for those users. Remediation. Apply a FIM filter to ensure user profiles in the new domain are not imported prior to the domain migration. You must submit a CR for FIM Filter update that keys off an attribute to flag accounts during User Profile Synchronization. FIM filter is applied to the Active Directory (Exclusion filter using and/or criteria). Warning: This action requires an understanding of the existing FIM filters and the addition of at least those filters. Your organization must determine whether any of the Active Directory attributes are being used to control the flow of users (especially if all user objects are copied into the target domain before they are physically migrated). Failure to plan and execute this step may result in duplicate user profiles, which will result is duplicate users in people search. For more information about user profile synchronization, see the TechNet article Plan for profile synchronization (SharePoint Server 2010). User Profile Synchronization and DMT The User Profile Synchronization service populates user profile data with mapped attributes to Active Directory. The service runs in two modes: Incremental Sync. This mode only syncs properties that have changed since the last run. Full Sync. This mode refreshes the user profile data. If the proper CRs are in place to exclude the source domain objects, and if new connection targets (pointing to the target domain) are created, the next profile sync will ensure that the correct user profiles are synced and any duplicate or old user profiles are marked for deletion. During run state, the User Profile Synchronization service is configured to run daily in incremental mode, whereas full sync can be performed on request. Microsoft recommends running at least the incremental sync after the following events: If sync search settings are modified on the existing connections. When a new connection is created pointing to the target domain.
Based on the Active Directory and DMT run schedule, there may be a need to restrict migrated users from being synchronized in SharePoint Online. In order to achieve this, your organization can either delay the CR for Active Directory connection (new domain) or move the user into an OU* that is outside of the Synch container (for existing domains). You can also set an extension attribute and use them in the FIM filter to exclude such users. This will also have an impact on People Picker People Picker Impact and Remediation The People Picker control is used to select users and groups, and to grant permissions to lists, libraries, and sites. The control provides basic functionality for finding and selecting users, groups, and claims to assign permissions in a site. The exact sources of those users, groups, and claims depend on the authentication method used by the web application that contains the site collection. User experiences issues. People Picker allows recognizing user names against the domain through the People & Groups control. If a new forest is being introduced, the users in this domain will not be recognized by SharePoint Online. If users in this domain cannot be recognized, they cannot be given access or added to audience or setup alerts. Remediation. New domain information should be added to the People Picker searchadforests property by submitting the appropriate CR (Configure People Picker searchadforest). Web App Policy Remediation Failure scenario. User Login using new domain account before the DMT is executed. In this scenario SharePoint will create a partial user profile record. After that happens the user is no longer unique in the SharePoint. When you attempt to execute DMT for these users, it will fail because DMT requires the user account to be unique with no traces in SharePoint. Remediation. Microsoft strongly recommends that you create a security group in the old domain and the new domain. When the user is migrated: 1. Put the user in the security group of the source domain. 2. Remove the user from the security group of the target domain, in target domain. 3. Submit the appropriate CR to create/deny all web application policy for both security groups across all web applications in SharePoint.
The following information relates to the use of Active Directory security groups, Active Directory extension attributes, and establishing forest level trusts with regards to FIM and People Picker. Use of Active Directory Security Groups Create Active Directory security groups in source and target. The Active Directory security group will be created in old and new domain The Active Directory security groups will be used to identify user s account that will be denied access to a SharePoint resource. The Active Directory security group can be retired in new domain after the migration is complete. Use of Active Directory Extension Attributes Use extension attributes in both the domains. The extension attributes will be used: To track users as they are migrated On FIM filters In People Picker SearchCustomFilters Forest Level Trust and Domain Context Create forest trust between the Managed Forest and new domain. Create a domain context entry in the SearchADForest. Create a LDAP query to filter out users based on extension attributes. Add FIM filters in the old and new domain Orphaned Sites Impact and Remediation Content orphans are created if there is a record in the SharePoint Allsites table, but there is no corresponding record in the sitemap table in the configuration database. Here are some scenarios that can trigger orphans: Failed restore. Merge operation. Database shuffling. Failed site creation during self-service site creation operation (for example, when creating My Sites).
Orphan site impact for Domain Migration: Users associated with orphan sites will fail during the migration event if this step is not completed. Remediation requirement: Customers are recommended to review the Orphan site report on a regular basis to ensure that the users associated with these orphan sites are not part of the domain migration before the clean-up is complete. 1. Weekly orphan site clean-up for sites > 250 MB 2. Daily orphan site clean-up for sites < 250 MB
If the customer sees a site in their orphan site report that was not caught in the automated clean-up process that could be because that particular site could potentially impact the service and SPO may have to manually clean-up the site accessing its impact to the service. The customer can submit a service request (SR) with Office 365 support (MOSSUP) for orphan sites clean-up no more than once a month throughout their domain migration project. SPO will not approve an SR which does not meet the monthly cadence. The severity for the SR should be set as Sev-b. DMT Requirements to Remediate Failures during Migration Event Failure scenario 1. If the format of the.csv file is incorrect, the DMT won t be able to load the values into the database. Remediation. The user accounts to be migrated must be listed in a.csv file. The user accounts listed in the.csv file must contain the old domain and user names and the new domain and user names. The accounts in the.csv file must be formatted in sequence (old, new) as shown in the following table: Windows Classic EUROPE\USER1, US\USER1 EUROPE\USER2, US\USER2 EUROPE\USER3, US\USER3 Windows Claims i:0#.w europe\user1, i:0#.w us\user1 i:0#.w europe\user2, i:0#.w us\user2 i:0#.w europe\user3, i:0#.w us\user3 Failure scenario 2. DMT will fail if there are trailing spaces before and after the values in the.csv file. Remediation. Ensure that there are no whitespaces before and after the values in the.csv file For more information about DMT configuration requirements, see Domain Migration Tool Configuration and Operation. SharePoint Features Impacted with Domain Migration The following SharePoint Online user features may be impacted with domain migrations. Email alerts. If the user email address has changed due to domain migration, user alerts may not work correctly until the user profiles are synchronized with the new domain. Tasks. The My Tasks view may not display correctly until the DMT tool has been executed. My Site and social data. Basic user profile properties that are configured to sync from Active Directory will be populated after the user profile sync is executed in SharePoint Online. But userupdated properties and social data such as My Colleagues and Recommended Links will not be
populated. Your organization must create their own solution to populate these properties from the old profile of the user. Preferred name. When users are migrated from the old domain to the new domain, the display name has the old domain. Monthly Status Check You organizaiton should work with your Microsoft SDM to update and submit this status table on a monthly basis for the duration of the migration. Customer name Total number of Total number of Outstanding Feedback users planned to users migrated to issues migrate date Daily Migration Sequence As highlighted in the workflow diagram that follows, there are three key events in a daily migration that must occur in the following sequence to ensure successful migration: 1. Accounts in your Active Directory are migrated. 2. The DMT runs. 3. The incremental User Profile Synchronization runs.
Important: Your organization should unblock the new domain and block the old domain between steps 2 and 3 so that the users show up in SharePoint Online in the correct domain with all the permissions. User Handling in the Source and Target Domains The following table represents handling of users in source and target domains prior to and after user migration. Before Successful SharePoint Online Migration During Active Directory and SharePoint Online Migration After successful Active Directory and SharePoint Online Migration
Before Successful During Active After successful Active SharePoint Online Directory and Directory and Migration SharePoint Online SharePoint Online Migration Migration Authorization (web app Restrict user from using Restrict user from Restrict user from using policy using the SG to new domain account. logging in using either old domain account. deny users) domain account or at the minimal no users from the new domain account. Permissions (people Restrict users new Ensure no new Ensure no new picker). This is also by account from being permissions are being permissions are being Active Directory resolved in people assigned to either user assigned to users old attribute. It is picker. account or at the domain account. recommended to have minimal no users from one connection per the new domain forest) account. Profile (FIM filter using Ensure that profile is Ensure that profiles are Ensure the profile is Active Directory pulled from old domain not being updated in being built from New attribute. It is account in SharePoint SharePoint Online or at domain account. recommended to have Online. the minimal no user one connection per profiles from the new forest). domain account. The next table describes the user state in the old and the new domain during the different phases of the domain migration. Phase Old Domain: User Exists Old Domain: User Active New Domain: User Exists New Domain: User Active Pre-migration Yes Yes Yes No During migration Yes Yes Yes Yes After migration No No Yes Yes End state No No Yes Yes
Domain Migration Tool Configuration and Operation Topic Last Modified: 2015-03-09 Domain migrations are performed by a migration timer job that runs each night. The following diagram illustrates the workflow of the Domain Migration Tool (DMT).
DMT Configuration After the DMT is approved, your organization must designate a security group containing all users who need access to the DMT site collection. After the DMT is installed on your farm, you receive notification regarding the site address for uploading the.csv file. By default, the migration timer job runs daily beginning at 23:00 local server time (in the data center housing your organization's farm). The timer job executes up to the specified number of user domain migrations (per the domain migration plan). The timer job runs late at night to allow you to migrate a batch of users in Active Directory each day after business hours and still leave enough time for the migration in SharePoint Online to also complete before business hours the next day. Note: After the DMT has been run successfully for a batch of at least 500-1,000 users, you can review the results list. If more daily migrations are required, you can notify Microsoft through the original CR. A maximum of 10,000 users can be migrated per day. Threshold for DMT Schedule and the Users Records There are two options for DMT scheduling: The DMT can be schedule hourly and up to 1,000 user records. If the DMT is scheduled to run once a day, the.csv file can contain 10,000 user records. For example, if your organization has 40,000 users, they can upload the.csv file with 40,000 users and the DMT will execute 10,000 users per day per the schedule.
For the duration of a domain migration project, it is recommended that the frequency of any user profile synchronization (full or incremental) be reduced to minimize the chance that this activity overlaps with domain migration in your Active Directory or in SharePoint Online with the DMT. DMT Operation The user accounts to be migrated must be listed in a.csv file. After the deployment of the DMT, you can access the site to upload.csv files into the Domain Migration Records document library. The user accounts listed in the.csv file contain the old domain and user names and the new domain and user names. The accounts in the.csv file must be formatted in sequence (old, new) as shown in the following table. Windows Classic EUROPE\USER1, US\USER1 EUROPE\USER2, US\USER2 EUROPE\USER3, US\USER3 Windows Claims i:0#.w europe\user1, i:0#.w us\user1 i:0#.w europe\user2, i:0#.w us\user2 i:0#.w europe\user3, i:0#.w us\user3 If the format is incorrect, the DMT won t be able to load the list into the database. Your organization can choose a file-naming convention for the.csv files. Microsoft recommends using a format like the following to track uploaded files: EUROPE-2011-01-27-1225-205.CSV
Important: Each uploaded.csv file must have a unique file name. Uploading a file with the same name as an existing file in the document library won t trigger the event handler and, therefore, the file will be ignored by the DMT. The following screen shot shows the SharePoint library where.csv files are uploaded. A successful upload of the.csv file will be captured by the event handler, and the content will be loaded into the DMT database. The migration timer job runs based on the frequency specified by your organization in the domain migration planning template, and will read from the DMT database to check if there are any items inside. The result will be written to the Domain Migration Results list library, as shown in the following screen shot. The list that logs migration status can quickly become very long. If the logging information needs to be viewed from the browser directly, either delete outdated log items frequently or create another view to show only failed migrations. Note: If an empty line is included at the beginning or end of the.csv file, the log will capture a failed migration with the comment System.Exception Domain Migration Failed! Old Account =, New
Account =. Error: User accounts are the same. Migration will not be performed. Troubleshooting All messages generated in the results list are the same as those for the STSADM -o MigrateUser command. For more information, refer to related documentation in the TechNet library. Changes to Configuration After DMT Installation Your organization must submit a CR through your SDM to request a change in the domain migration configuration settings. The following configuration settings are allowed. Change in the DMT frequency Migration end date The above items are high-level guidelines. Microsoft strongly recommends that you use the Domain Migration Planning template for specific remediation steps and the execution plan.
Additional Considerations Topic Last Modified: 2013-05-16 You should be aware of the following when performing domain migrations and using the Domain Migration Tool (DMT). Organization Hierarchy Changes Organization hierarchy changes may result in disjointed hierarchy during the migration. A user might be migrated before his or her manager. It is important to set correct expectations for the organization chart Web Part. Know Your Configuration Although not a requirement for the DMT, Microsoft recommends that you understand your current environment, including the following: Service accounts used in the farm Credentials in Secure Store Service Any Microsoft Business Connectivity Services (BCS) integration with credentials Any Windows Azure integration FIM filters in user profile sync targets Active Directory containers being synchronized Audiences using Active Directory properties and Active Directory security groups Distribution lists in Alerts InfoPath form connection files InfoPath submission through email connection
Know Your Customization There may be on-premises services and applications providing services and data to your online environment. Also, there may have full trust code running in the Office 365 environment. Your organization must inspect all code to trace if any of the service or user account is being used as a credential to access resources (for example, databases or file systems). Testing Consideration and Scope The extent of testing depends largely on the complexity of the implementation. For the most part, the site should work normally for migrated users after DMT execution. But there may be certain features that do not get remediated as expected. The following features and scenarios should be included in your testing plan. These scenarios are only indicative of the scope, and not the complete scope. 1. The user logs into sites where the user is directly assigned permission. 2. The user logs in to sites were they have been given permission through SharePoint groups. 3. The user logs into sites where they have been granted permission through Active Directory groups. 4. Site alerts. 5. Audience targeting. 6. People Picker ability to search users across the new domain. 7. My Site. 8. Org hierarchy Web Part. 9. Social data and personal sites. 10. Work flow, running instances and workflow history. 11. Tasks, created by, modified by attribute values. Known Limitations 1. The DMT does not support migration of groups, so any organization that uses security groups to define permissions in SharePoint Online must plan separately to re-permission groups where necessary. 2. In between profile syncs, any new user who accesses SharePoint Online for the first time can authenticate, but the additional profile properties from Active Directory won t be available until the next sync.
3. Your organization must ensure that it doesn't load so many account migration jobs into the DMT that they will be processed on a day and time that conflicts with the user profile synchronization.