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.
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:
- Enforce Conditional Access policies on token issuance.
- Control key rollover lifecycles independently.
- Isolate intra-organization tokens from general workload service principals.
- 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:
- Exchange On-Premises: Exchange Server SE RTM or Exchange Server 2019 CU14+ with latest Security Updates applied.
- Administrative Privileges:
- Cloud: Entra ID Application Administrator or Global Administrator, and Exchange Administrator. - On-Premises: Organization Management role in Exchange on-premises.
- PowerShell Modules:
- Microsoft.Graph.Applications (v2.20+)
- ExchangeOnlineManagement (v3.6.0+)
- Certificate Requirements: A valid x509 certificate (SHA-256, 2048-bit minimum key size) installed in
Cert:\LocalMachine\Myon 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:
<#
.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:
Test-OAuthConnectivity -Service EWS `
-TargetUri "https://outlook.office365.com/ews/exchange.asmx" `
-Mailbox "[email protected]" `
-Verbose
Expected Result:
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:
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-OAuthConnectivityfails with an invalid audience error. - Root Cause: The on-premises Exchange
TargetApplicationIddoes 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, ApplicationIdentifierand 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\MywhereThumbprintmatches(Get-AuthConfig).CurrentCertificateThumbprint, and re-upload the key credentials to Entra ID viaUpdate-MgApplication.
Issue 3: Inactive Exchange Service Principal Consent
- 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:
- Remove legacy partner applications tied to
00000002-0000-0ff1-ce00-000000000000from on-premises:
Get-PartnerApplication | Where-Object { $_.ApplicationIdentifier -like "*00000002-0000-0ff1*" } | Remove-PartnerApplication -Confirm:$false
- Confirm in Entra ID Sign-In logs that hybrid authentication requests are exclusively mapped to your dedicated application ID.