Active Directory / LDAP → Microsoft Entra ID provisioning

// LDAP scoping filter (find enabled users in on-prem AD)
(&(objectClass=user)(objectCategory=person)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

// Source attribute → Target attribute mapping (Entra ID provisioning)
givenName           → name.givenName
sn                 → name.surname
mail               → mail
sAMAccountName      → onPremisesSamAccountName
objectGUID         → onPremisesImmutableId (Base64-encoded)
memberOf            → transitiveMemberOf (group sync)
userAccountControl → accountEnabled (bit 2 = disabled)

// Entra ID Connect sync rule (onPremisesSyncEnabled = true enables provisioning)
userAnchor: objectGUID → immutableId
matching: onPremisesSamAccountName + userPrincipalName suffix match

How we'd take this from discovery to a production-safe cutover — the phases, the canonical mapping, and the edge cases that bite.

Synchronising identities from on-premises Active Directory (or generic LDAPv3 directory) into Microsoft Entra ID (formerly Azure AD) is the foundational identity plane for Microsoft 365, Teams, Intune, and SaaS SSO. The integration uses Microsoft Entra Connect (or its cloud-native successor, Entra Connect Cloud Sync) as the provisioning engine, running on a staging server inside the perimeter. LDAP queries filtered by OU and attribute scope feed a delta-sync pipeline that writes users, contacts, and group memberships into the Entra ID tenant. The following pathway takes a typical green‑field deployment from environment discovery through production cutover.

Implementation Phases

1. Environment discovery and inventory. Enumerate every AD/LDAP partition, naming context, and site that will be in scope. Document OU hierarchy, existing security groups, mail-enabled Universal Distribution Groups, and any LDAP referrals pointing to external forests. Export a full user and group inventory with attribute cardinality — this becomes the baseline for conflict detection later.
2. Target tenant readiness. Verify the Entra ID tenant domain is verified and that no conflicting UPN suffixes exist. If a custom UPN suffix is used on-premises that is not a registered domain in Entra ID, add it in the Entra admin centre under Custom domain names before installing the sync tool. Confirm that Password Hash Synchronisation (optional but recommended for non-federated scenarios) and Seamless SSO are licensed appropriately.
3. Install and configure Microsoft Entra Connect. Run AzureADConnect.msi on a dedicated Windows Server 2016+ staging/production server. Choose Express Settings for a guided path or Custom to define OU scope explicitly. In the filtering page, select only the OUs that contain identities destined for the cloud — exclude service accounts, system containers, and any OU holding legacy accounts that must never appear in Entra ID. Enable Directory extension attribute sync only if custom attributes are required, as each extension consumes a schema slot in Entra ID.
4. Define attribute mapping and transformation rules. In the Synchronisation Rules Editor, review inbound synchronisation rules for users. The default rule maps userPrincipalName → userPrincipalName, sAMAccountName → onPremisesSamAccountName, and objectGUID → sourceAnchor (binary-to-string encoded as Base64). Add precedence rules for mail vs. userPrincipalName as the sign-in name. For groups, ensure the groupType bitmask is interpreted correctly so that Security groups and Distribution groups are created as appropriate Entra ID group types — mail-enabled Universal Distribution groups become Microsoft 365 groups if Exchange Hybrid is configured.
5. Password hash sync and writeback (optional). If Password Hash Synchronisation is enabled, configure the Azure AD Connect wizard to use TLS 1.2 between the sync server and the Azure AD endpoint. Set the sync schedule to the default 30‑minute delta; for near-real-time requirements add Microsoft Entra Connect Cloud Sync agents for sub‑5‑minute delta. Enable Password writeback only after confirming that password complexity rules in on-premises AD are compatible with Entra ID self-service reset policies.
6. Pilot / staging mode validation. Set the sync server to Staging Mode (checkbox in the wizard) so that the sync cycle runs but writes nothing to Entra ID. Run a full initial sync, export the connector space delta to a CSV, and compare object counts and attribute values against the on-premises inventory. Validate that no duplicate users are created — especially for accounts that already exist as cloud-only or guest accounts — by reviewing the metaverse duplicate attribute reports.
7. Production cutover and delta reconciliation. Exit Staging Mode. Perform an initial full import from AD, followed by a full synchronisation. Immediately after the first delta write, run the Entra ID Provisioning logs blade and filter for errors. Cross-reference the Entra ID audit log for Add user and Update user events. Confirm group memberships match the on-premises memberOf attribute by exporting both datasets and running a diff.
8. Ongoing monitoring and health checks. Configure Microsoft Entra Connect Health for sync and integrate the alert email distribution list. Schedule a monthly review of the Synchronization Service Manager profiler to catch rule changes. Set an alert on the SyncError metric in Entra ID diagnostics — threshold of zero for the first 30 days post-cutover.

Field Mapping

Edge Cases

• Duplicate userPrincipalName conflict. A cloud-only user with the same UPN as an on-prem account causes a object_sync_error. The resolution is to either rename the cloud account's UPN (e.g. [email protected] → [email protected]) or to set an immutableId mapping before cutover.
• Empty or null sourceAnchor. InetOrgPerson entries or contacts created without objectGUID cannot receive a stable anchor. The sync engine falls back to a hash of objectSID, but this is not guaranteed across domain moves — enforce a rule that all synced objects must carry objectGUID.
• Circulareference in group membership. AD groups that contain other groups in a circular chain cause the sync engine to log cycle-detected errors and may silently drop memberships. Use the Synchronisation Rules Editor to enable recursive group expansion or manually flatten circular nesting before scoping.
• Domain / UPN suffix mismatch. On-prem accounts using a UPN suffix (e.g. @corp.contoso.com) that is not registered in Entra ID will receive the tenant's default suffix, breaking sign-in. Every UPN suffix must be added as a custom domain in Entra ID before the first sync.
• Mail-enabled Universal Distribution groups without mail. Groups that have groupType set to Universal Distribution but lack a mail attribute are synced as Security groups in Entra ID, silently losing the ability to send mail. Configure Exchange Hybrid or set a mail alias via a sync rule transform before cutover.
• Deleted-object garbage collection delay. When a user or group is deleted from AD, the Tombstone lifecycle (default 180 days) means the deletion may not propagate to Entra ID until the tombstone expires. Manually soft-delete or hard-delete the corresponding Entra ID object in the Entra admin portal to avoid phantom accounts persisting.
• Filtered-out objects that already exist in Entra ID. If an OU is removed from the sync scope after initial provisioning, the objects in that OU are not automatically deleted from Entra ID — they remain orphaned. Configure an outbound scoping filter that explicitly targets those OUs and sets the Delete flow rule, then verify the connector space before committing.
• Password Hash Sync certificate rotation. The TLS certificate used between the sync server and Entra ID auto-renews; however, if the server has no internet access on the required endpoints (provisioningapi[.].blob.core.windows.net), the sync stalls silently. Validate firewall rules during discovery.

Cutover

Cutover is a staged operation that must be fully reversible. Begin by placing the sync server into Staging Mode and running a full import and full sync while the server is still staged — this produces a complete preview of what Entra ID will look like after the first production write. Export both the on-premises user and group inventory and the staged metaverse projection, then run a deterministic diff in PowerShell (Compare-Object $cloudList $onPremList -Property userPrincipalName,memberOf) and remediate any discrepancies before exiting Staging Mode. Once Staging Mode is disabled, perform a delta sync and immediately run the Entra ID provisioning logs report, scanning for entrySyncError and objectSyncError events; triage each error before the next delta cycle runs. To guarantee reversibility, retain the Staging Mode export as a snapshot and do not decommission the on-premises AD — the on-prem directory remains the system of record. If a rollback is required, run Set-MsolDirSyncEnabled -EnableDirSync $false (via MSOnline module) to disable directory synchronisation, clean the delta in Entra ID, and re-enable sync after scope corrections are applied. Finally, validate sign-in for a sample of five users per OU by confirming their Entra ID UPN resolves and that group membership is reflected in an Azure AD‑joined application access check before closing the cutover window.