Directory sync keeps the people, groups and contacts of one directory in step with another: Active Directory, Entra ID (Microsoft 365) and Google Workspace, in any pairing. It is what you run before a migration so every mailbox has an account to land in, and during a coexistence so joiners, leavers and group changes follow along. You find it under Directory sync in the side menu.
What it syncs
| Object | Matched by | What is written in the target |
|---|---|---|
| Users | Sign-in name (after the name rule below) | Created with name, title, department, phone and mobile; updated when those change; sign-in blocked when they leave the source |
| Groups | Group name | Created; description updated; members added (removed only if you switch that on) |
| Contacts | Email address | Mail contacts (Entra ID / Exchange Online), shared contacts (Google Workspace), contact objects (Active Directory) |
| OU structure | OU path | Between two Active Directories only: the tree is recreated, parents first |
| Computer accounts | Computer name | Between two Active Directories only: pre-staged, disabled, in the matching OU |
Which directions work
- Entra ID ↔ Entra ID — two Microsoft 365 tenants.
- Entra ID ↔ Google Workspace — either way.
- Active Directory → Entra ID and Entra ID → Active Directory.
- Active Directory ↔ Google Workspace.
- Active Directory ↔ Active Directory — including OU structure and computer accounts.
Every sync runs in one direction: the source is the authority and is never changed. If two directories must feed each other, set up two syncs with different content (for example users one way, contacts the other).
Step by step
- Add the two directoriesEntra ID and Google Workspace come from tenants you have already connected on a project: on Directory sync, press Add next to the tenant. An Active Directory is added by creating an agent — see Install the Active Directory agent.
- Set up the syncGive it a name, choose From and To, tick what to sync, and set the rules below. Press Create and preview.
- Read the previewPress Preview. MigrateX reads both directories and lists every change it would make: Create, Update, Block sign-in, Add member. Nothing has been written.
- ApplyPress Apply. Exactly the previewed changes are carried out — not a newer plan. Each row turns to Done or Failed with the reason.
- Preview againA second preview should say In step. Whatever it still lists is what did not go through the first time.
- Put it on a scheduleUnder Rules and schedule, choose every 15 minutes, hourly, six-hourly or daily. A scheduled run plans and applies in one go, so turn it on only after a preview looks right.
You see: counters per kind of change at the top of the sync, the full list below, and the time of the last run on the Directory sync page.
The rules
| Rule | Choices | Example |
|---|---|---|
| Sign-in names in the target | Keep the name before the @ · first.last · first initial + last name · first name + last initial | jane.doe · jane.doe · jdoe · janed |
| Domain in the target | One domain for everyone (the target's own by default), or keep each person's domain | jane.doe@contoso.com → jdoe@fabrikam.com |
| Only members of this group | A group name in the source; empty means everyone | Migration wave 1 |
| When someone leaves the source | Block sign-in in the target, or leave them as they are | Only applies to people this sync created or updated |
| Remove group members | Off by default | Applies only to groups this sync created or updated |
Changing the name rule later is safe.People the sync already created or updated keep the account they have; the new rule applies to people not yet brought over. The preview always shows the effect before anything is written.
New accounts and passwords
- Entra ID and Google Workspace: a new user gets a long random temporary password that nobody sees and must change it at first sign-in. Reset the password in the admin console when you hand the account over, or let your identity provider take over.
- Active Directory: a new user is created disabled, without a password. Set one and enable the account when you are ready.
- MigrateX never reads, copies or sets anyone's existing password, in any direction.
What it does not do
- Passwords and SID history are not copied. For an Active Directory to Active Directory move that needs them, use Microsoft's own migration tooling for that step, after MigrateX has put the objects and the OU structure in place.
- Nothing is deleted — not users, not groups, not contacts, not OUs. The strongest action is blocking a user's sign-in.
- No licenses are assigned. Give the new accounts their Microsoft 365 or Workspace licenses in the admin console (or by group-based licensing).
- Printers are not copied. Print queues republish themselves from the print server once it is in the new domain.
- Nested groups are synced as groups; a group that is a member of another group is not added as a member.
What each directory needs
- Entra ID: the tenant connected with the Shared mailboxes & groups scope ticked (for groups), and the Exchange Administrator role granted to MigrateX (for mail contacts) — the same as for a migration.
- Google Workspace: the tenant connected with the group scopes delegated. For shared contacts, add one more scope to the domain-wide delegation:
https://www.google.com/m8/feeds/. Without it users and groups still sync; contacts report the missing scope by name. - Active Directory: an agent in that network. Reading needs an ordinary domain account; a target also needs rights to create and change objects in the OUs you sync.
Who can do what
- Owners create and remove agents and delete syncs.
- Operators add directories, set up syncs, preview, apply and schedule.
- Viewers can read the previews and results.
- Every create, preview, apply, settings change and removal is written to the Activity log.
If something fails
| You see | It means | Do this |
|---|---|---|
| A row marked Failed with a reason | The target directory refused that one change (a name already taken, a missing right) | Fix the cause and preview again; only what is still missing is listed |
| “N changes waiting for the agent” | The target is an Active Directory and its agent has not run since you applied | Wait for its next run, or start the scheduled task by hand. The agent must run with -Mode ReadWrite |
| “is no longer connected to a tenant” | The project connection behind that directory was removed or revoked | Connect the tenant again on its project |
| “add the scope https://www.google.com/m8/feeds/” | Google shared contacts need that extra delegation scope | Add it under Admin console → Security → API controls → Domain-wide delegation |
| “Waiting for the agent” on a directory | The agent has never called in | Run it once with the token — see the agent guide |