Tutorial: Deploy Entra Cloud Sync¶

# Run on the server designated for the Cloud Sync agent

# Check Windows version (Server 2016+ required)
[System.Environment]::OSVersion.Version

# Check .NET Framework version (4.7.2+ required)
(Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full").Release
# 461808 = .NET 4.7.2; 528040 = .NET 4.8

# Verify domain join
(Get-WmiObject Win32_ComputerSystem).Domain

# Verify connectivity to Entra ID endpoints
$endpoints = @(
    "login.microsoftonline.com",
    "provisioning.microsoftonline.com",
    "aadconnectapi.msappproxy.net",
    "msappproxy.net",
    "servicebus.windows.net"
)

foreach ($endpoint in $endpoints) {
    $result = Test-NetConnection -ComputerName $endpoint -Port 443
    Write-Host "$endpoint : $($result.TcpTestSucceeded)" -ForegroundColor $(
        if ($result.TcpTestSucceeded) { "Green" } else { "Red" }
    )
}

# Create a pilot OU for testing Cloud Sync
# Run on a domain controller or machine with RSAT
New-ADOrganizationalUnit -Name "CloudSync-Pilot" `
    -Path "OU=Users,DC=contoso,DC=com" `
    -Description "Users for Cloud Sync pilot testing"

# Move 10-20 test users to the pilot OU
$pilotUsers = @("testuser1", "testuser2", "testuser3")
foreach ($user in $pilotUsers) {
    Get-ADUser -Identity $user |
        Move-ADObject -TargetPath "OU=CloudSync-Pilot,OU=Users,DC=contoso,DC=com"
}

# Verify users are in the pilot OU
Get-ADUser -SearchBase "OU=CloudSync-Pilot,OU=Users,DC=contoso,DC=com" -Filter * |
    Select-Object SamAccountName, UserPrincipalName, DistinguishedName

# Ensure UPN suffixes match your verified domain in Entra ID
$forest = [System.DirectoryServices.ActiveDirectory.Forest]::GetCurrentForest()
$forest.Domains | ForEach-Object {
    $domain = $_
    $domain.Name
}

# Add custom UPN suffix if needed
# Active Directory Domains and Trusts > Properties > UPN Suffixes
# Or via PowerShell:
Set-ADForest -Identity (Get-ADForest) `
    -UPNSuffixes @{Add="contoso.com"}

# Verify all pilot users have the correct UPN suffix
Get-ADUser -SearchBase "OU=CloudSync-Pilot,OU=Users,DC=contoso,DC=com" -Filter * `
    -Properties UserPrincipalName |
    Select-Object SamAccountName, UserPrincipalName

# Run the installer (interactive or silent)
# Interactive:
.\AADConnectProvisioningAgentSetup.exe

# Silent installation:
.\AADConnectProvisioningAgentSetup.exe /quiet

# During installation, you will be prompted to:
# 1. Accept the license agreement
# 2. Sign in with Global Administrator or Hybrid Identity Administrator credentials
# 3. Sign in with AD Domain Administrator credentials (or use gMSA)

# Verify the agent service is running
Get-Service "AADConnectProvisioningAgent" | Select-Object Status, StartType

# Output should show:
# Status    StartType
# ------    ---------
# Running   Automatic

# Verify agent registration in Entra admin center
# Entra admin center > Identity > Hybrid management > Entra Connect > Cloud Sync
# The agent should appear with status "Active"

# Check agent logs
Get-WinEvent -LogName "AAD Connect Provisioning Agent" -MaxEvents 20 |
    Format-Table TimeCreated, Message -AutoSize

# Install on a DIFFERENT domain-joined server for high availability
# Same installation process as above
# Both agents will appear in the Entra admin center
# Cloud Sync automatically distributes load and fails over between agents

# Verify PHS is working after initial sync
# Check Entra audit logs for password sync events
Get-MgAuditLogDirectoryAudit -Filter "activityDisplayName eq 'Change user password'" `
    -Top 10 |
    Select-Object ActivityDisplayName, ActivityDateTime, InitiatedBy, Result

# Check provisioning logs in Entra admin center
# Entra admin center > Identity > Hybrid management > Cloud Sync > Provisioning logs

# Or via Graph API:
$provLogs = Get-MgAuditLogProvisioning -Top 50 |
    Where-Object { $_.ServicePrincipal.DisplayName -eq "Azure AD Cloud Sync" }

$provLogs | Select-Object ActivityDateTime, Action,
    @{N="Source"; E={$_.SourceIdentity.DisplayName}},
    @{N="Target"; E={$_.TargetIdentity.DisplayName}},
    StatusInfo | Format-Table -AutoSize

# Verify pilot users appear in Entra ID
$pilotUsers = @("testuser1@contoso.com", "testuser2@contoso.com", "testuser3@contoso.com")

foreach ($upn in $pilotUsers) {
    $user = Get-MgUser -UserId $upn -Property `
        DisplayName, OnPremisesSyncEnabled, OnPremisesImmutableId,
        OnPremisesLastSyncDateTime -ErrorAction SilentlyContinue

    if ($user) {
        [PSCustomObject]@{
            UPN = $upn
            DisplayName = $user.DisplayName
            Synced = $user.OnPremisesSyncEnabled
            ImmutableId = if ($user.OnPremisesImmutableId) { "Set" } else { "Missing" }
            LastSync = $user.OnPremisesLastSyncDateTime
        }
    } else {
        [PSCustomObject]@{
            UPN = $upn
            DisplayName = "NOT FOUND"
            Synced = $false
            ImmutableId = "N/A"
            LastSync = $null
        }
    }
} | Format-Table -AutoSize

# Test sign-in for a pilot user
# Use a browser InPrivate/Incognito session:
# 1. Navigate to https://myapps.microsoft.com
# 2. Sign in with the pilot user's UPN and on-prem AD password
# 3. Verify successful sign-in
# 4. Check the sign-in logs for the authentication method

# Verify in sign-in logs:
$signIn = Get-MgAuditLogSignIn -Filter `
    "userPrincipalName eq 'testuser1@contoso.com'" -Top 1

$signIn | Select-Object UserPrincipalName, AppDisplayName,
    @{N="AuthMethod"; E={$_.AuthenticationDetails[0].AuthenticationMethod}},
    Status, ConditionalAccessStatus

# Change password on-premises
Set-ADAccountPassword -Identity "testuser1" `
    -NewPassword (ConvertTo-SecureString "NewP@ssw0rd!2026" -AsPlainText -Force) `
    -Reset

$startTime = Get-Date
Write-Host "Password changed at: $startTime"
Write-Host "Waiting for sync (typically < 2 minutes)..."

# Poll until the new password works in Entra ID
# (Manual test: try signing in with new password every 30 seconds)

# Identify a test user for SOA switching
$testUser = "testuser1@contoso.com"

# Step 1: Remove user from Cloud Sync scope
# Move user to an OU not in the sync scope filter
Get-ADUser -Identity "testuser1" |
    Move-ADObject -TargetPath "OU=CloudManaged,OU=Users,DC=contoso,DC=com"

# Step 2: Wait for sync cycle (2 minutes)
Start-Sleep -Seconds 120

# Step 3: Verify user is now cloud-managed
$user = Get-MgUser -UserId $testUser -Property OnPremisesSyncEnabled
Write-Host "Sync enabled: $($user.OnPremisesSyncEnabled)"
# Should be: $false or $null

# Step 4: Test cloud-managed attribute update
Update-MgUser -UserId $testUser -Department "Cloud Managed - Test"

# Step 5: Verify the update persists
$user = Get-MgUser -UserId $testUser -Property Department
Write-Host "Department: $($user.Department)"
# Should be: "Cloud Managed - Test"

# If issues are detected, move user back to sync scope
Get-ADUser -Identity "testuser1" |
    Move-ADObject -TargetPath "OU=CloudSync-Pilot,OU=Users,DC=contoso,DC=com"

# Wait for sync cycle
Start-Sleep -Seconds 120

# Verify user is synced again
$user = Get-MgUser -UserId "testuser1@contoso.com" -Property OnPremisesSyncEnabled
Write-Host "Sync enabled: $($user.OnPremisesSyncEnabled)"
# Should be: $true

# Create a monitoring script for ongoing sync health
# Run as a scheduled task or Azure Automation runbook

$healthCheck = @{
    AgentStatus = (Get-Service "AADConnectProvisioningAgent").Status
    SyncErrors = (Get-MgAuditLogProvisioning -Filter "statusInfo/status eq 'failure'" `
        -Top 100).Count
    LastSync = (Get-MgAuditLogProvisioning -Top 1).ActivityDateTime
    TotalSyncedUsers = (Get-MgUser -All -Property OnPremisesSyncEnabled |
        Where-Object { $_.OnPremisesSyncEnabled -eq $true }).Count
}

$healthCheck | ConvertTo-Json

# Agent-side diagnostics
Get-WinEvent -LogName "AAD Connect Provisioning Agent" -MaxEvents 50 |
    Where-Object { $_.Level -le 2 } |  # Errors and warnings
    Format-Table TimeCreated, Level, Message -AutoSize

# Network connectivity test
Invoke-WebRequest -Uri "https://login.microsoftonline.com" -UseBasicParsing |
    Select-Object StatusCode