Deploy dedicated Exchange hybrid app

Introduction

Microsoft has announced the retirement of Exchange Web Services (EWS) for Exchange Online, effective October 1, 2026. This change impacts Rich Coexistence features in Exchange Hybrid environments. To maintain functionality, organisations must transition to the Microsoft Graph API, the modern and supported method for accessing Exchange Online data.

In hybrid setups, Exchange Server will soon shift from using Exchange Online’s shared Service Principal to a dedicated application in Microsoft Entra ID. EWS API calls will be replaced with REST-based Graph API calls as part of this multi-step design change.

This article will provide a detailed guide on establishing a dedicated Exchange application within Entra ID for Exchange hybrid configurations, as part of the revised design framework.

Key points

• EWS Retirement: Microsoft will block EWS requests to Exchange Online starting October 1, 2026.
• Support: EWS will only receive security and select non-security updates—no new features.
• Action Required: Exchange Hybrid customers must migrate from legacy EWS calls to Microsoft Graph API to retain rich coexistence features.
• Only Exchange Online: This change applies exclusively to Microsoft 365 and Exchange Online across all environments; there will be no changes to EWS within Exchange Server.
• On-Premise Support: EWS will remain fully supported for on-premises Exchange mailboxes.

If you do not use rich coexistence features, no action is required.

Prerequisites

Ensure your on-premises Exchange servers are running one of the supported builds:

Also, verify connectivity to Microsoft Graph and Entra ID endpoints:

Test-NetConnection -ComputerName login.microsoftonline.com -Port 443
Test-NetConnection -ComputerName graph.microsoft.com -Port 443

Required Permissions

• Entra ID: Global Administrator or Application Administrator
• On-Premises Exchange: Organisation Management or equivalent roles

Implementation Steps

Microsoft provides a script to automate the deployment of the dedicated Exchange Hybrid application.

Step 1: Download the Script

Get the script from the official Microsoft GitHub repository.

Step 2: Choose Configuration Mode

• All-in-One Mode(used in this demo): Automates all steps.
• Split Execution Mode: Useful for environments with network restrictions.

Step 3: Run the Script

Log in to one of the Exchange Servers and Open the Exchange Management Shell with elevated permissions and run the script with the following syntax.

.\ConfigureExchangeHybridApplication.ps1 -FullyConfigureExchangeHybridApplication

• Sign in with Global Admin credentials when prompted.
• Type Y to grant consent and continue.

What the Script Does:

• Creates an Entra ID application
• Uploads and assigns the Auth Certificate
• Grants EWS full_access_as_app permission
• Configures Auth Server Object
• Sets up ConfigureTargetSharingEpr
• Enables CreateSettingOverride for hybrid app features

After completion, confirm that all Rich Coexistence features function properly.

Verification

• Test OAuth connectivity:

Use the following command to check the OAuth connectivity between Exchange and Exchange Online.

$OnPremisesMailbox = "userMailboxOnprem@contoso.com"
$result = Test-OAuthConnectivity -Service EWS -TargetUri https://outlook.office365.com -Mailbox $OnPremisesMailbox
Write-Host $result.ResultType

• Extract and verify the appId:

• Ensure that the appId matches the one generated by the script.

Auditing

Audit usage via Service Principal sign-in logs in Entra ID. Key details include:

• Application ID
• Service Principal ID
• Auth Certificate Thumbprint

Clean-Up Mode

Once all checks are complete, execute the script in “Service Principal Clean-Up Mode.” This process will remove all certificates associated with the Office 365 Exchange Online first-party application’s Service Principal. By performing this action, you help ensure that obsolete or unnecessary certificates are eliminated, thereby upholding the security and integrity of the application.

To remove legacy certificates:

.\ConfigureExchangeHybridApplication.ps1 -ResetFirstPartyServicePrincipalKeyCredentials

Troubleshooting

If you encounter network issues with All-in-One Mode, switch to Split Execution Mode using a domain-joined machine with proper connectivity.

For further details, please consult the referenced article.

Rollback Steps

• Rerun the Hybrid Configuration Wizard with OAuth and the necessary connectors.

• Remove Setting Override:

Get-SettingOverride | Where-Object {$_.ComponentName -eq "Global" -and $_.SectionName -eq "ExchangeOnpremAsThirdPartyAppId"} | Remove-SettingOverride
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh

• Revert Auth Server Changes:

# Replace this id with the id of your tenant
$tenantId = "123e4567-e89b-12d3-a456-426614174000"

(Get-AuthServer | Where-Object {$_.Name -like "*evoSTS*" -and $_.Realm -eq $tenantId}) | Set-AuthServer -ApplicationIdentifier $null -DomainName $null

• Delete Entra ID Application:

.\ConfigureExchangeHybridApplication.ps1 -DeleteApplication

Final Check

Ensure Rich Coexistence features are functioning as expected after deployment or rollback.

Reference Articles:

https://techcommunity.microsoft.com/blog/exchange/dedicated-hybrid-app-temporary-enforcements-new-hcw-and-possible-hybrid-function/4440682

https://techcommunity.microsoft.com/blog/exchange/retirement-of-exchange-web-services-in-exchange-online/3924440

https://techcommunity.microsoft.com/blog/exchange/ews-exchange-web-services-to-microsoft-graph-migration-guide-series/3957158

https://techcommunity.microsoft.com/blog/exchange/introducing-exchange-web-services-ews-usage-reports-in-microsoft-365-admin-cente/4411263