Federation Migration: Okta to Entra ID¶

# Step 1: Enable staged rollover for password hash sync
Connect-MgGraph -Scopes "Policy.ReadWrite.AuthenticationMethod"

# Create staged rollover policy
$params = @{
    featureRollouts = @(
        @{
            feature = "passwordHashSync"
            isEnabled = $true
            isAppliedToOrganization = $false
        }
    )
}

# Step 2: Add pilot group to staged rollover
$pilotGroup = Get-MgGroup -Filter "displayName eq 'Okta-Migration-Pilot'"

# Add group to PHS staged rollover
New-MgPolicyStagedRolloutPolicy -Body @{
    feature = "passwordHashSync"
    isEnabled = $true
    isAppliedToOrganization = $false
}

# Assign pilot group
$policy = Get-MgPolicyStagedRolloutPolicy -Filter "feature eq 'passwordHashSync'"
New-MgPolicyStagedRolloutPolicyAppliedTo -StagedRolloutPolicyId $policy.Id -Body @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/groups/$($pilotGroup.Id)"
}

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Domain.ReadWrite.All"

# Verify current domain federation status
Get-MgDomain -DomainId "contoso.com" | Select-Object Id, AuthenticationType

# Expected output for federated domain:
# Id           AuthenticationType
# --           ------------------
# contoso.com  Federated

# Convert domain from federated to managed
Update-MgDomain -DomainId "contoso.com" -AuthenticationType "Managed"

# Verify conversion
Get-MgDomain -DomainId "contoso.com" | Select-Object Id, AuthenticationType

# Expected output after conversion:
# Id           AuthenticationType
# --           ------------------
# contoso.com  Managed

# View current federation configuration
Get-MgDomainFederationConfiguration -DomainId "contoso.com"

# Key properties of the federation configuration:
# - IssuerUri: Okta issuer URL (e.g., https://your-org.okta.com)
# - PassiveSignInUri: Okta SAML endpoint
# - SigningCertificate: Okta signing certificate (base64)
# - ActiveSignInUri: Okta WS-Trust endpoint (for rich clients)
# - PreferredAuthenticationProtocol: samlP or wsFed

# Emergency rollback -- re-federate domain to Okta
$federationConfig = @{
    issuerUri = "https://your-org.okta.com"
    passiveSignInUri = "https://your-org.okta.com/app/office365/sso/saml"
    signingCertificate = "<base64-encoded-okta-signing-certificate>"
    preferredAuthenticationProtocol = "samlP"
}

# Re-configure federation
New-MgDomainFederationConfiguration -DomainId "contoso.com" -BodyParameter $federationConfig

# Convert domain back to federated
Update-MgDomain -DomainId "contoso.com" -AuthenticationType "Federated"

# Verify rollback
Get-MgDomain -DomainId "contoso.com" | Select-Object Id, AuthenticationType

# List all domains and their authentication types
Get-MgDomain | Select-Object Id, AuthenticationType, IsVerified

# Migrate domains in order:
# 1. Test/dev domains first
# 2. Secondary production domains
# 3. Primary domain last

# Example: Migrate domains in sequence
$domains = @("test.contoso.com", "subsidiary.contoso.com", "contoso.com")

foreach ($domain in $domains) {
    Write-Host "Converting $domain to managed authentication..."
    Update-MgDomain -DomainId $domain -AuthenticationType "Managed"

    # Validate
    $result = Get-MgDomain -DomainId $domain
    Write-Host "$domain authentication type: $($result.AuthenticationType)"

    # Wait for validation before proceeding to next domain
    Read-Host "Validate $domain and press Enter to continue"
}

# Verify PHS is enabled in Entra Connect
Get-ADSyncAADCompanyFeature

# Expected: PasswordHashSync = True

# If not enabled, configure PHS:
Set-ADSyncAADCompanyFeature -PasswordHashSync $true

# Force initial password hash sync
Start-ADSyncSyncCycle -PolicyType Initial

# Cloud Sync is configured via the Entra admin center
# No on-premises server required beyond the provisioning agent

# Verify Cloud Sync agent status
Get-MgServicePrincipal -Filter "appId eq '1a4721b3-e57f-4451-ae87-ef078703ec94'"