3.2 SourceAnchor, Synchronization Rules & Microsoft Entra Connect Health

SourceAnchor, Synchronization Rules & Microsoft Entra Connect Health

1. SourceAnchor, ImmutableID, and Identity Matching Mechanics

The sourceAnchor is an attribute in on-premises AD DS that uniquely and immutably identifies an identity object throughout its entire lifecycle. In Microsoft Entra ID, this attribute is stored in the cloud as the immutableId (represented as a Base64-encoded string).

+-----------------------------------------------------------------------------------+
|                    SOURCEANCHOR TO IMMUTABLEID CONVERSION                         |
|                                                                                   |
|  [On-Premises AD DS Object]                       [Microsoft Entra ID Object]    |
|   Attribute: mS-DS-ConsistencyGuid                 Attribute: immutableId         |
|   Format: Raw Binary GUID                          Format: Base64 String          |
|   Hex: 6a 3b 84 a9 e2 11 4e 88...                  String: ajuEqeIRCk6I...        |
|          |                                                ^                       |
|          +-----------> [Base64 Conversion] ---------------+                       |
+-----------------------------------------------------------------------------------+

mS-DS-ConsistencyGuid vs. objectGUID:

• objectGUID (Legacy Anchor): Generated automatically by AD DS upon object creation. While unique within a domain, objectGUID is strictly immutable in AD DS. If a user account is migrated to another forest or domain using Active Directory Migration Tool (ADMT), AD DS generates a new objectGUID in the destination domain. Because the cloud immutableId remains linked to the old GUID, the user's cloud identity is duplicated or orphaned.
• mS-DS-ConsistencyGuid (Modern Best Practice): A writable binary attribute in AD DS. During initial synchronization, Entra Connect reads the object's objectGUID, writes that exact binary value into the user's mS-DS-ConsistencyGuid attribute in AD DS, and uses it as the sourceAnchor. If the user is subsequently migrated to another forest, migration scripts can copy the original mS-DS-ConsistencyGuid value to the new account in the target forest, preserving the exact link to the user's existing Entra ID mailbox, licenses, and OneDrive data.

Soft Match vs. Hard Match Mechanics:

When synchronizing an on-premises user to an existing cloud-only user (e.g., during cloud-to-hybrid onboarding), Entra Connect uses matching rules:

1. Soft Match (Attribute Matching):
   • Matches an unmanaged cloud user to an on-premises user if UserPrincipalName matches exactly, OR if the primary SMTP address in proxyAddresses matches mail.
   • Limitation: Soft matching only functions if the cloud user object has never been synced before (immutableId is $null). Once matched, Entra Connect converts the cloud user to a synced object and binds its immutableId permanently.
2. Hard Match (Direct Anchor Binding):
   • Explicitly populates the cloud user's immutableId with the Base64-encoded binary GUID of the on-premises account using PowerShell.
   • Used to remediate broken sync links or resolve duplicate object creation.

# Converting an On-Premises Active Directory objectGUID to Base64 ImmutableID
$adUser = Get-ADUser -Identity "ranchen" -Properties objectGUID, mS-DS-ConsistencyGuid
$guidBytes = $adUser.objectGUID.ToByteArray()
$immutableId = [Convert]::ToBase64String($guidBytes)
Write-Output "Base64 ImmutableID: $immutableId"

# Performing a Hard Match in Microsoft Entra ID via Microsoft Graph PowerShell
Connect-MgGraph -Scopes "User.ReadWrite.All"
Update-MgUser -UserId "ranchen@contoso.com" -OnPremisesImmutableId $immutableId

---

2. Synchronization Rules Editor & Precedence Management

Custom attribute flows are implemented using the Synchronization Rules Editor (syncruleseditor.exe).

+-----------------------------------------------------------------------------------+
|                       SYNCHRONIZATION RULE PRECEDENCE                             |
|                                                                                   |
|   [Rule Precedence: 1 to 99]    ---> Custom Inbound / Outbound Rules (Highest)    |
|   [Rule Precedence: 100 to 399] ---> Out-of-the-Box Default Rules (Baseline)      |
|   [Rule Precedence: 400+]       ---> Catch-All & Fallback Rules (Lowest)          |
|                                                                                   |
|   RULE: If two rules contribute to the same Metaverse attribute,                 |
|         the rule with the LOWER numeric precedence value WINS.                    |
+-----------------------------------------------------------------------------------+

Rule Types and Transformation Expressions:

• Inbound Rules: Transform attributes from a Connector Space into the Metaverse.
• Outbound Rules: Transform attributes from the Metaverse into a Connector Space.
• Link Types:
  • Provision / Projection: Creates a new object in the target space if no match exists.
  • Join: Matches an existing CS object to an existing Metaverse object using join criteria (e.g., sAMAccountName equals accountName).
• Transformations:
  • Direct: Direct 1-to-1 attribute mapping (e.g., givenName -> givenName).
  • Constant: Hardcodes a static value (e.g., setting accountEnabled to True).
  • Expression: Uses declarative logic (e.g., IIF(IsNullOrEmpty([mail]), [userPrincipalName], [mail]) or Left([department], 10)).

[!WARNING] Never Modify Default Synchronization Rules Directly: Default rules (precedence ≥ 100) are overwritten during Entra Connect upgrades. To customize attribute flow, disable the default rule, clone it, assign the cloned rule a lower precedence number (e.g., 50), and modify the clone.

---

3. Microsoft Entra Connect Health & Operational Monitoring

Microsoft Entra Connect Health provides cloud-based monitoring, alerting, and diagnostic telemetry for hybrid identity components.

+-----------------------------------------------------------------------------------+
|                    MICROSOFT ENTRA CONNECT HEALTH ECOSYSTEM                       |
|                                                                                   |
|  +------------------------------------------------------------------------------+ |
|  |                 MICROSOFT ENTRA CONNECT HEALTH CLOUD PORTAL                  | |
|  |  - Centralized Health Dashboard & Email Alert Notifications                  | |
|  |  - Sync Error Reports (Duplicate Attributes, Data Validation, Large Object)  | |
|  |  - Password Hash Sync Latency & Performance Diagnostics                     | |
|  +------------------------------------------------------------------------------+ |
|        ^ (HTTPS 443)                     ^ (HTTPS 443)            ^ (HTTPS 443)   |
|        |                                 |                        |               |
|  +-------------------+         +-------------------+    +--------------------+    |
|  | Sync Health Agent |         | AD DS Health Agent|    | AD FS Health Agent |    |
|  | (Entra Connect)   |         | (Domain Ctrlrs)   |    | (WAP & AD FS Farm) |    |
|  +-------------------+         +-------------------+    +--------------------+    |
+-----------------------------------------------------------------------------------+

Core Monitoring Agents:

1. Entra Connect Health Agent for Sync: Installed on the Entra Connect server. Monitors synchronization errors, run cycle durations, password hash synchronization heartbeat, and staging mode status.
2. Entra Connect Health Agent for AD DS: Installed on physical/virtual on-premises domain controllers. Monitors AD replication latency, SYSVOL replication, Kerberos/NTLM authentication traffic, and PDC Emulator performance.
3. Entra Connect Health Agent for AD FS: Installed on internal AD FS federation servers and perimeter Web Application Proxy (WAP) servers. Tracks token issuance rates, bad password lockouts, and federation metadata validation.

Common Synchronization Errors & Remediation:

• Duplicate Attribute Conflict (AttributeValueMustBeUnique): Occurs when two on-premises objects share the same UserPrincipalName or ProxyAddresses (SMTP alias). Entra ID requires tenant-wide uniqueness for these attributes. Entra ID generates a quarantine proxy address (e.g., user@contoso.onmicrosoft.com with a modified alias) until the on-premises duplicate is cleared.
• Data Validation Failure: Occurs when an attribute contains illegal characters, unsupported format strings, or exceeds maximum length constraints.
• Large Object Error: Occurs when a single security group exceeds membership limits or contains excessive nested attributes beyond the synchronization threshold.

Staging Mode and Disaster Recovery:

Staging Mode configures the Entra Connect sync engine to execute all import and synchronization cycles (building and updating its local Connector Spaces and Metaverse) while suspending all export operations to Microsoft Entra ID and AD DS.

# Checking Current Synchronization Scheduler & Staging Mode Status
Get-ADSyncScheduler

# Output includes:
# SyncCycleEnabled                : True
# StagingModeEnabled              : True   <-- (Exports are suspended)
# CustomizedSyncCycleInterval     : 00:30:00

# Exporting and analyzing pending changes on a Staging Server using csexport.exe
cd "C:\Program Files\Microsoft Azure AD Sync\Bin"
.\csexport.exe "contoso.onmicrosoft.com - AAD" export.xml /f:x
.\CSExportAnalyzer.exe export.xml > pending_changes.csv

[!TIP] Warm Standby Disaster Recovery Architecture: Deploy a secondary Entra Connect server in Staging Mode connected to the same SQL database or a replicated instance. If the primary sync server suffers a catastrophic hardware failure, promoting the staging server to primary requires only running Set-ADSyncScheduler -StagingModeEnabled $false—eliminating prolonged sync downtime.