Before you can migrate mailboxes between Microsoft 365 tenants, users need to exist in the destination tenant.
Copy identities copies users and groups from Entra ID to complete identity preparation as part of your migration projects. You can review and adjust all identity decisions, including mappings, license assignments, and domain mappings, before executing the migration.
Note: Copy identities is a public preview.
Some identity types and properties are not supported. For details, see Copy identities limitations.
Prerequisites
You have a ShareGate Migrate Pro or ShareGate Migrate Enterprise subscription.
You have global admin permissions in your Microsoft 365 source and destination.
Required Microsoft 365 permissions
You must once consent to a set of Microsoft 365 permissions on your tenants before using Copy identities.
You'll be prompted to consent to these permissions the first time you sign in with your Global admin account.
To learn about the required permissions for identity migrations, see Microsoft 365 permission scopes required for ShareGate.
How to copy identities
Select Copy from the sidebar menu.
Select the Copy identities tab.
Click Copy identities.
You land directly on the Review identity mappings screen.
Select your source tenant from the left dropdown and your destination tenant from the right dropdown.
If no source tenant is connected yet, click Add connection to connect to Entra ID first.
If this is your first time connecting to the source tenant, you'll be prompted to consent to a Microsoft 365 permission scope.
If no destination tenant is connected yet, click Add connection on the right side. Source and destination tenants must be different.
If this is your first time connecting to the destination tenant, you'll be prompted to consent to a Microsoft 365 permission scope.
Check the box next to each source identity you want to migrate.
Use the search bar to find specific identities.
Click a column header to sort by that column.
Use the check box in the column header to select all identities.
Review and adjust your mapping decisions, then click Start copy or Start precheck to verify what the migration will do.
What gets copied
Copy identities relies on available Microsoft 365 and Entra ID APIs. Not all identity types and properties are supported.
Users
ShareGate Migrate copies the following user types:
Member Users
Guest Users
Shared Mailboxes
Room Mailboxes
Equipment Mailboxes
Note: Guest users are migrated using Microsoft's invitation flow. A valid email address is required for each guest user.
The following properties are copied per user:
Category | Properties copied |
Core | Display Name, User Principal Name (UPN), Mail Nickname, Account Enabled, User Type, Mail address |
Profile | First Name, Last Name, Job Title, Department, Company, Office Location, Mobile Phone, Business Phone, Fax, Street, City, State, Postal Code, Country |
Account | Usage Location, Employee ID, Employee Type, Employee Hire Date, Employee Leave Date, Password Policies, Show In Address List, Is Resource Account |
Privacy | Age Group, Consent Provided for Minor |
Other | Preferred Language, Other Mails (alternate email addresses) |
Note: Only one business phone number can be set per user. If a source user has multiple business phone numbers, only the first one is copied.
For Shared, Room, and Equipment mailboxes, ShareGate Migrate also copies the following permissions:
Full Access
Send As
Send On Behalf
These permissions are copied for both individual users and groups as members.
Licenses are mapped from source SKU IDs to destination SKU IDs using License Mappings that you can configure.
Groups
Group type | Supported | Notes |
Security Groups | Yes | Static or dynamic membership; can have a Teams association |
Unified Groups (Microsoft 365) | Yes | Static or dynamic membership; can have a Teams association |
Distribution Lists | Not supported |
|
Mail-enabled Security Groups | Not supported | Flagged in the interface |
For supported group types, the following core properties are copied: Display Name, Mail Nickname, Group Type, Visibility, Description, Security Enabled, and Mail Enabled flags.
Additional properties by type:
Security Groups: Hide From Address Lists, Hide From Outlook Clients
Unified Groups (M365): Theme, Mail address, Allow External Senders, Auto Subscribe New Members, Hide From Address Lists, Hide From Outlook Clients
For membership:
Assigned groups: Owners and Members are copied.
Dynamic groups: Membership Rules are copied, with circular dependency detection and domain name mapping applied using your configured Domain Mappings.
Identity planning view
The identity planning view is your central workspace for reviewing and adjusting all mapping decisions before running the migration. Each row represents a source identity and shows its mapping status and destination.
You can take action on any row directly without leaving the screen.
How users and groups are matched
ShareGate Migrate looks for exact matches on specific properties:
Users are matched by User Principal Name (UPN).
Groups are matched by Mail nickname.
When no match is found
The identity's status changes to Will be created, and ShareGate will provision a new identity in the destination.
When multiple candidates are found
When two destination identities match the same source, it is treated as a conflict and the identity receives a Needs review status. ShareGate Migrate won't automatically pick one. You must resolve it manually.
Overriding a mapping
If the auto-matched destination identity is incorrect, or if multiple candidates were found and you need to pick the right one, you can resolve it from the side panel:
Click the identity row to open the side panel.
Search for and select the correct existing destination identity of the same type (user to user, group to group).
The mapping row updates to reflect your choice.
To revert, open the side panel and select the original auto-match or choose another candidate.
You can also create a new identity instead of mapping to an existing one. To do so, provide a new UPN in the side panel and ShareGate will provision a new identity in the destination.
Your override decisions are saved. If you close and reopen the planning view, all manual matches are preserved.
License assignment
You can assign destination licenses to identities directly from the planning view.
The License column shows the license that will be applied at the destination.
To assign a license, click a row to open the side panel and select the license to apply.
If an identity is mapped to a license with no available seats, the copy will fail for that identity and you'll be notified in the copy report.
Custom domain mapping
If your source and destination tenants use different domains, you can define domain mapping rules so that identities are matched and created with the correct destination domain.
To add a custom domain mapping, open the Domain mappings settings in the planning view and define your source to destination domain pairs. Mappings are saved and applied at execution time.
Importing mappings from a CSV
You can import mapping decisions in bulk by uploading a CSV file, instead of resolving them one by one in the side panel.
The CSV must follow this format:
Column | Description |
SourceObjectId | Object ID of the source identity |
SourceDisplayName | Display name of the source identity |
SourceUPN_ifUser | UPN of the source identity (users only) |
SourceMailNickname_ifGroup | Mail nickname of the source identity (groups only) |
DestinationObjectId | Object ID of the destination identity (optional; if left empty, the identity will be treated as a creation) |
DestinationDisplayName | Display name of the destination identity |
DestinationUPN_ifUser | UPN of the destination identity (users only) |
DestinationMailNickname_ifGroup | Mail nickname of the destination identity (groups only) |
For each row, leave the UPN columns empty for groups and the mail nickname columns empty for users.
Once imported, the mappings appear in the planning view and can be reviewed or adjusted before running the copy.
Copy report
As the copy completes, ShareGate generates a copy report summarizing the results of your identity migration.