Migrating Exchange Hybrid from the Shared Service Principal to a Dedicated Entra ID Hybrid Application

For over a decade, hybrid Exchange deployments (Exchange Server 2013, 2016, 2019, and early SE deployments) relied on Microsoft's well-known shared multi-tenant Service Principal (00000002-0000-0ff1-ce00-000000000000) for server-to-server OAuth federation, intra-organization Free/Busy lookups, MailTips, and cross-premises archive discovery.

Under Microsoft’s Secure Future Initiative (SFI) and the latest Exchange Server Subscription Edition (SE) architectural standards, shared multi-tenant service principals represent an unacceptably broad attack surface. Organizations are mandated to migrate their hybrid federated trust to a Dedicated Entra ID App Registration owned, isolated, and audited directly inside their own tenant.

This runbook guides messaging engineers and infrastructure architects through the end-to-end migration from the legacy shared principal to a dedicated application registration using certificate-based authentication.


Exchange Hybrid Authentication Architecture: Legacy vs Dedicated Entra ID App DEPRECATED: Shared Service Principal Shared App ID (00000002-0000-0ff1-ce00...) Global shared multi-tenant trust; no customer key ownership Unconstrained Token Scope Tokens accepted broadly across workloads without tenant isolation Legacy OAuth Partner Application Set-PartnerApplication -ApplicationIdentifier fixed to shared GUID Vulnerabilities & Compliance Risks No Conditional Access support, non-rotatable shared trust, scheduled for hard retirement under Microsoft SFI 2026 STANDARD: Dedicated Tenant App Dedicated Tenant App Registration Unique Client ID owned exclusively inside your Entra ID tenant x509 Certificate-Based Authentication Enterprise PKI / self-signed SHA-256 certificate with automated rollover Granular Least-Privilege Permissions Restricted to Free/Busy, MailTips, and cross-premises archive scopes Zero Trust & Auditing Benefits Full Entra ID sign-in audit logs, Conditional Access integration, seamless compatibility with Exchange SE & 2019 CU14+ Migration preserves uninterrupted Free/Busy lookup during live transition

1. Why the Shared Service Principal Must Be Retired

In traditional Exchange Hybrid deployments configured via the Hybrid Configuration Wizard (HCW), cross-premises OAuth relied on a shared multi-tenant Microsoft service principal:

  • App ID: 00000002-0000-0ff1-ce00-000000000000 (Office 365 Exchange Online)
  • Token Issuer: https://sts.windows.net/<tenant-id>/

Because this App ID was shared across hundreds of thousands of tenants, individual organizations could not:

  1. Enforce Conditional Access policies on token issuance.
  2. Control key rollover lifecycles independently.
  3. Isolate intra-organization tokens from general workload service principals.
  4. Granularly revoke consent without tearing down the entire hybrid trust.

Transitioning to a Dedicated Hybrid Application decouples your organization from this shared footprint, giving your security team complete visibility into all hybrid OAuth token exchanges via standard Entra ID sign-in and audit logs.


2. Migration Prerequisites

Ensure the following prerequisites are met prior to executing the migration:

  1. Exchange On-Premises: Exchange Server SE RTM or Exchange Server 2019 CU14+ with latest Security Updates applied.
  2. Administrative Privileges:

- Cloud: Entra ID Application Administrator or Global Administrator, and Exchange Administrator. - On-Premises: Organization Management role in Exchange on-premises.

  1. PowerShell Modules:

- Microsoft.Graph.Applications (v2.20+) - ExchangeOnlineManagement (v3.6.0+)

  1. Certificate Requirements: A valid x509 certificate (SHA-256, 2048-bit minimum key size) installed in Cert:\LocalMachine\My on all on-premises Exchange servers.

3. End-to-End Migration Runbook

The following PowerShell runbook automates the cloud application provisioning, certificate binding, and on-premises Exchange configuration.

Save and execute this as Migrate-ExchangeHybridDedicatedApp.ps1:

POWERSHELL
<#
.SYNOPSIS
    Migrate-ExchangeHybridDedicatedApp.ps1
    Migrates Exchange Hybrid from the legacy shared service principal to a
    dedicated Entra ID App Registration.

.DESCRIPTION
    1. Generates or exports a hybrid OAuth signing certificate.
    2. Registers the dedicated Entra ID application.
    3. Configures required API permissions and grants admin consent.
    4. Updates on-premises Exchange PartnerApplication configuration.
    5. Validates cross-premises OAuth connectivity.

.NOTES
    Author: Sunil Chauhan (LAB 365  https://www.lab365.in)
    Version: 1.0 (November 2026)
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $false)]
    [string]$AppName = "Exchange-Hybrid-Dedicated-OAuth",

    [Parameter(Mandatory = $false)]
    [string]$CertSubject = "CN=Exchange-Hybrid-OAuth-Cert",

    [Parameter(Mandatory = $false)]
    [int]$CertValidityYears = 2
)

Write-Host "==========================================================" -ForegroundColor Cyan
Write-Host " LAB 365 - Dedicated Hybrid App Migration Runbook        " -ForegroundColor Yellow
Write-Host "==========================================================" -ForegroundColor Cyan

# -------------------------------------------------------------------
# Step 1: Create / Retrieve the OAuth Signing Certificate
# -------------------------------------------------------------------
Write-Host "`n[Step 1/5] Checking OAuth Signing Certificate..." -ForegroundColor Cyan

$existingCert = Get-ChildItem -Path Cert:\LocalMachine\My |
    Where-Object { $_.Subject -eq $CertSubject -and $_.NotAfter -gt (Get-Date).AddMonths(1) } |
    Sort-Object NotAfter -Descending | Select-Object -First 1

if ($null -eq $existingCert) {
    Write-Host "Creating new self-signed hybrid OAuth certificate..." -ForegroundColor Yellow
    $cert = New-SelfSignedCertificate `
        -Subject $CertSubject `
        -CertStoreLocation "Cert:\LocalMachine\My" `
        -KeyExportPolicy Exportable `
        -KeySpec Signature `
        -KeyLength 2048 `
        -KeyAlgorithm RSA `
        -HashAlgorithm SHA256 `
        -NotAfter (Get-Date).AddYears($CertValidityYears)
    Write-Host "[+] New certificate created with thumbprint: $($cert.Thumbprint)" -ForegroundColor Green
} else {
    $cert = $existingCert
    Write-Host "[+] Using existing valid certificate: $($cert.Thumbprint)" -ForegroundColor Green
}

# Export public CER for Entra ID registration
$cerPath = "$env:TEMP\$($cert.Thumbprint).cer"
Export-Certificate -Cert $cert -FilePath $cerPath -Force | Out-Null
Write-Host "Exported public key to: $cerPath"

# -------------------------------------------------------------------
# Step 2: Register Dedicated Entra ID Application
# -------------------------------------------------------------------
Write-Host "`n[Step 2/5] Provisioning Dedicated Entra ID Application..." -ForegroundColor Cyan

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All" -NoWelcome

# Convert Certificate to Binary for Graph upload
$certBytes = [System.IO.File]::ReadAllBytes($cerPath)
$certBase64 = [Convert]::ToBase64String($certBytes)

$keyCredential = @{
    Type  = "AsymmetricX509Cert"
    Usage = "Verify"
    Key   = [System.Text.Encoding]::ASCII.GetBytes($certBase64)
}

# Check if application already exists
$existingApp = Get-MgApplication -Filter "displayName eq '$AppName'" -ErrorAction SilentlyContinue

if ($null -eq $existingApp) {
    $appParams = @{
        DisplayName    = $AppName
        SignInAudience = "AzureADMyOrg"
        KeyCredentials = @($keyCredential)
    }
    $newApp = New-MgApplication @appParams
    Write-Host "[+] Created Entra ID App Registration: $($newApp.DisplayName) (AppId: $($newApp.AppId))" -ForegroundColor Green
} else {
    $newApp = $existingApp
    Write-Host "[+] Found existing App Registration: $($newApp.DisplayName) (AppId: $($newApp.AppId))" -ForegroundColor Green
    # Add new certificate to existing application
    Update-MgApplication -ApplicationId $newApp.Id -KeyCredentials @($keyCredential)
}

# Ensure Service Principal exists in tenant
$sp = Get-MgServicePrincipal -Filter "appId eq '$($newApp.AppId)'" -ErrorAction SilentlyContinue
if ($null -eq $sp) {
    $sp = New-MgServicePrincipal -AppId $newApp.AppId
    Write-Host "[+] Instantiated Enterprise Service Principal: $($sp.Id)" -ForegroundColor Green
}

# -------------------------------------------------------------------
# Step 3: Assign Exchange Online Hybrid API Permissions
# -------------------------------------------------------------------
Write-Host "`n[Step 3/5] Assigning Hybrid Partner Scopes..." -ForegroundColor Cyan

# Query Exchange Online Resource SP (Office 365 Exchange Online)
$exoSP = Get-MgServicePrincipal -Filter "appId eq '00000002-0000-0ff1-ce00-000000000000'"

# Target App Role: Organization.Read.All or Exchange.ManageAsApp (depending on scenario)
$partnerRole = $exoSP.AppRoles | Where-Object { $_.Value -eq "Exchange.ManageAsApp" -or $_.Value -eq "MailboxSettings.Read" } | Select-Object -First 1

if ($partnerRole) {
    try {
        New-MgServicePrincipalAppRoleAssignment `
            -ServicePrincipalId $sp.Id `
            -PrincipalId $sp.Id `
            -ResourceId $exoSP.Id `
            -AppRoleId $partnerRole.Id -ErrorAction SilentlyContinue
        Write-Host "[+] Assigned $($partnerRole.Value) role to dedicated service principal." -ForegroundColor Green
    } catch {
        Write-Host "Role assignment already present or managed via admin consent." -ForegroundColor Yellow
    }
}

# -------------------------------------------------------------------
# Step 4: Configure On-Premises Exchange Partner Application
# -------------------------------------------------------------------
Write-Host "`n[Step 4/5] Updating On-Premises Exchange Configuration..." -ForegroundColor Cyan

$tenantDomain = (Get-MgOrganization | Select-Object -First 1).VerifiedDomains |
    Where-Object { $_.IsInitial -eq $true } | Select-Object -ExpandProperty Name

$metadataUrl = "https://login.microsoftonline.com/$tenantDomain/federationmetadata/2007-06/federationmetadata.xml"

Write-Host "Run the following commands inside the on-premises Exchange Management Shell (EMS):" -ForegroundColor Yellow
Write-Host @
# 1. Register the new Dedicated Cloud Partner Application
New-PartnerApplication -Name "$AppName" `
    -ApplicationIdentifier "$($newApp.AppId)" `
    -MetadataUrl "$metadataUrl" `
    -Enabled `$true

# 2. Update Intra-Organization Configuration
Set-IntraOrganizationConfiguration `
    -TargetApplicationId "$($newApp.AppId)" `
    -TargetMetadataUrl "$metadataUrl"

# 3. Apply the new certificate to the On-Premises Auth Server
Set-AuthConfig -NewCertificateThumbprint "$($cert.Thumbprint)" -NewCertificateEffectiveDate (Get-Date)
Set-AuthConfig -PublishCertificate
Set-AuthConfig -ClearPreviousCertificate
@ -ForegroundColor Gray

# -------------------------------------------------------------------
# Step 5: Validation Instructions
# -------------------------------------------------------------------
Write-Host "`n[Step 5/5] Migration Complete. Validation Steps:" -ForegroundColor Green
Write-Host "1. Test OAuth token acquisition from EMS:"
Write-Host "   Test-OAuthConnectivity -Service EWS -TargetUri https://outlook.office365.com/ews/exchange.asmx -Mailbox user@$tenantDomain -Verbose"
Write-Host "2. Validate cross-premises Free/Busy resolution in Outlook / OWA."

4. Validating Cross-Premises Free/Busy & OAuth Connectivity

Once the dedicated application is active and the on-premises partner configuration is updated, execute standard connectivity verification:

Test 1: Verify On-Premises OAuth Token Retrieval

Run the following command from an on-premises Exchange Management Shell:

POWERSHELL
Test-OAuthConnectivity -Service EWS `
    -TargetUri "https://outlook.office365.com/ews/exchange.asmx" `
    -Mailbox "[email protected]" `
    -Verbose

Expected Result:

TEXT
ResultType : Success
Detail     : Verification of OAuth connectivity succeeded. Valid token received with Audience: https://autodiscover-s.outlook.com/

Test 2: Test Cloud-to-On-Premises Intra-Organization Free/Busy

Connect to Exchange Online PowerShell and run:

POWERSHELL
Test-OrganizationRelationship -Identity "OnPremises" `
    -UserIdentity "[email protected]" `
    -Confirm:$false `
    -Verbose

Verify that the FreeBusy test passes with HTTP status 200 OK and that calendar slots are parsed without falling back to basic authentication.


5. Troubleshooting Common Migration Failures

Issue 1: 401 Unauthorized - InvalidAudience

  • Symptom: Test-OAuthConnectivity fails with an invalid audience error.
  • Root Cause: The on-premises Exchange TargetApplicationId does not match the Client ID of the new dedicated Entra ID App registration, or the metadata endpoint URL is resolving to an incorrect tenant identifier.
  • Fix: Verify the App ID using Get-PartnerApplication | Select-Object Name, ApplicationIdentifier and ensure it equals $newApp.AppId.

Issue 2: Certificate Thumbprint Mismatch

  • Symptom: Token validation fails with SignatureVerificationFailed.
  • Root Cause: The public certificate uploaded to the Entra App registration differs from the private key bound to the local Exchange AuthConfig.
  • Fix: Re-export the certificate from Cert:\LocalMachine\My where Thumbprint matches (Get-AuthConfig).CurrentCertificateThumbprint, and re-upload the key credentials to Entra ID via Update-MgApplication.
  • Symptom: Cloud requests reject the on-premises token claiming ConsentRequired.
  • Root Cause: The enterprise service principal in Entra ID was not granted tenant-wide admin consent.
  • Fix: In the Microsoft Entra admin center, navigate to Enterprise applications > Exchange-Hybrid-Dedicated-OAuth > Permissions and click Grant admin consent for [Tenant].

6. Decommissioning the Legacy Shared SPN Configuration

After a 14-day bake period with zero hybrid lookup errors:

  1. Remove legacy partner applications tied to 00000002-0000-0ff1-ce00-000000000000 from on-premises:
POWERSHELL
   Get-PartnerApplication | Where-Object { $_.ApplicationIdentifier -like "*00000002-0000-0ff1*" } | Remove-PartnerApplication -Confirm:$false
   
  1. Confirm in Entra ID Sign-In logs that hybrid authentication requests are exclusively mapped to your dedicated application ID.