Deploy dedicated Exchange hybrid app

Overview

When Exchange Server is deployed in a hybrid configuration, features such as Free/Busy, MailTips, and Photos become available between Exchange Server and Exchange Online, providing a seamless experience for users. These features are automatically configured when you run the Hybrid Configuration Wizard (HCW) for the first time.

To enable hybrid feature use, Exchange Server utilizes a shared Service Principal with Exchange Online for secure communication. The HCW uploads the current Auth Certificate from your Exchange organization to the shared Service Principal to facilitate this process.

As announced in the Retirement of Exchange Web Services in Exchange Online blog post, Exchange Web Services (EWS) is set to be fully deprecated in Exchange Online in October 2026 for non-Microsoft (third-party) applications and services. In the Security Related Updates in Exchange Online blog post, we announced that we are also removing EWS dependencies from our own (first-party) apps and services, and this change is expected before October 2026.

Exchange Server, used in a hybrid configuration, is affected by this change as it uses the shared Service Principal from Exchange Online (first-party). To accommodate this change, Exchange Server replaces EWS API calls with REST-based Graph API calls in hybrid scenarios in near future. This design change involves multiple steps, with the first step being the use of a separate application in Microsoft Entra ID instead of the shared Service Principal.

This documentation outlines the steps required to create a dedicated Exchange application in Entra ID for Exchange hybrid configurations as part of the updated design. Exchange Server continues using EWS after the dedicated Exchange application is created and configured. The switch to REST-based Graph API as a replacement for EWS will be made with an update that is expected to be published in near future.

To learn more about this change and its implications, we recommend reading the Exchange Server Security Changes for Hybrid Deployments blog post, which provides detailed context and guidance.

Prerequisites

Before configuring and using the dedicated Exchange hybrid application, you must first set up either Classic Full or Modern Full hybrid using the Hybrid Configuration Wizard.

The dedicated Exchange hybrid application feature is supported starting with the following Exchange Server builds:

Microsoft provides a script to create the dedicated Exchange hybrid application in Entra ID and to configure the feature. There are two distinct scenarios in which the script can be executed, each with its own set of prerequisites. The modes are explained in the Configuration section of this documentation.

All-in-one Configuration Mode:

This mode is designed for simplicity and is suitable for most customers. It allows for a streamlined setup process, making it ideal for environments where ease of configuration is a priority.

Split Execution Configuration Mode:

This mode is intended for more advanced scenarios. It's useful if your Exchange server lacks outbound connectivity to the Graph API or Entra ID endpoints, or if the Exchange Server administrator doesn't have sufficient permissions to create and configure the application in Entra ID.

If you perform any of the steps on a non-Exchange Server, ensure that the computer is joined to the same forest where your Exchange organization resides.

Connectivity

The script utilizes the Microsoft Graph API to create and manage applications in Microsoft Entra ID. When running the script in All-in-one Configuration Mode, the system executing the script requires outbound connectivity to the specified endpoints. In Split Execution Configuration Mode, the system used to create or manage the application in Entra ID needs outbound access to these endpoints. You should choose the endpoint where your tenant resides, such as Global. For more information, see the National Microsoft Entra ID Endpoints and National Microsoft Graph Endpoints documentation.

To verify your server's ability to connect to the Graph and Entra ID endpoints, you can use the Test-NetConnection PowerShell cmdlet. This example demonstrates how to validate the connection to these endpoints using the Global endpoints:

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

Permissions

The account used for creating the application in Microsoft Entra ID must possess the following permissions:

For more details about the roles in Entra ID, see the Microsoft Entra built-in roles documentation.

The account used for configuring the Auth Server object and creating the Setting Override to enable the feature in Exchange Server must have the following permissions within the on-premises organization:

For detailed information about the various roles in Exchange Server, refer to the Organization Management documentation.

To configure the Auth Server and create the Setting Override, ensure that the script is executed on a server with the Mailbox role installed and a build that supports this feature.

To use the script for resetting the keyCredentials of the shared Service Principal, as detailed in the Service Principal Clean-Up Mode section, ensure that the account running the script has the following permissions:

Auth Certificate

The Auth Certificate is a key component in Microsoft Exchange Server, supporting various security and authentication scenarios. Proper management of the Auth Certificate is essential for maintaining the security and reliability of Exchange Server operations.

In the dedicated Exchange hybrid application use case, it facilitates JSON Web Token (JWT) assertion-based authentication for server-to-server (S2S) communication. This allows an Exchange Server to authenticate by presenting a signed JWT instead of relying on a password or interactive login. The JWT, issued and signed by a trusted authority, contains claims that verify the Exchange Server's identity and permissions, enabling secure, token-based access to resources.

In some scenarios described in this documentation, you need to export the Auth Certificate. Make sure not to export the private key of the certificate. To export the public key of the certificate, you can use the following PowerShell script.

In this example, the certificate is exported to C:\AuthCertExport. If you wish to export the certificate to a different location, modify the $exportFilePath variable to your desired path. Ensure you run the script from an elevated Exchange Management Shell (EMS):

# Change the path if you want to export the certificates to a different location
$exportFilePath = "C:\AuthCertExport"

$authConfig = Get-AuthConfig

New-Item -Type Directory -Path C:\AuthCertExport -Force | Out-Null

if (-not([System.String]::IsNullOrEmpty($authConfig.CurrentCertificateThumbprint))) {
    $thumbprint = $authConfig.CurrentCertificateThumbprint
    Write-Host "[+] Auth Certificate thumbprint: $thumbprint"

    try {
        $currentAuthCertificate = Get-ChildItem -Path Cert:\LocalMachine\My\$thumbprint
        Export-Certificate -Cert $currentAuthCertificate -FilePath "$exportFilePath\$thumbprint.cer" -Type CERT | Out-Null
        Write-Host "[+] Certificate was successfully exported to: $exportFilePath"
    } catch {
        Write-Host "[+] We hit the following exception: $_" -ForegroundColor Red
    }
}

if (-not([System.String]::IsNullOrEmpty($authConfig.NextCertificateThumbprint))) {
    $thumbprint = $authConfig.NextCertificateThumbprint
    Write-Host "[+] Next Auth Certificate thumbprint: $thumbprint"

    try {
        $currentAuthCertificate = Get-ChildItem -Path Cert:\LocalMachine\My\$thumbprint
        Export-Certificate -Cert $currentAuthCertificate -FilePath "$exportFilePath\$thumbprint.cer" -Type CERT | Out-Null
        Write-Host "[+] Certificate was successfully exported to: $exportFilePath"
    } catch {
        Write-Host "[+] We hit the following exception: $_" -ForegroundColor Red
    }
}

Changes made by the script

The ConfigureExchangeHybridApplication.ps1 script performs various operations based on the selected option. These operations include configuring and enabling the dedicated Exchange hybrid application feature, or deleting or modifying the existing Exchange Online Service Principal. This section outlines the specific operations executed by the script.

CreateApplication

• Create a new application with name ExchangeServerApp-{Guid of the organization} in Entra ID
• Assign the user who was used to run the script as an owner of the application in Entra ID
• Assign the full_access_as_app EWS API permissions (to be replaced with Graph API permission in near future)
• Grant tenant-wide admin consent
  • This change needs to be confirmed during the runtime of the script
  • The script doesn't enable the feature via Setting Override if tenant-wide admin consent hasn't been granted

UpdateCertificate

• Upload the current Auth Certificate to the application in Entra ID
• Upload the new next Auth Certificate (if it exists) to the application in Entra ID
• Delete any certificate from the application, which has expired

ConfigureAuthServer

• Update the EvoSTS or EvoSTS - {Guid} Auth Server object
  • Set the ApplicationIdentifier to the appId of the application in Entra ID
  • Add the SMTP Remote Routing Domain to the DomainName property

ConfigureTargetSharingEpr

• Identify any enabled OrganizationRelationship configured between Exchange Server and Exchange Online
• Use AutoDiscover to query the Exchange Web Services (EWS) endpoint
• Set the TargetSharingEpr to the EWS endpoint returned by AutoDiscover

EnableExchangeHybridApplicationOverride

• If the script runs in All-in-one Configuration Mode
  • Validate if the application in Entra ID has the correct API permissions and tenant-wide admin consent granted
• Create a new Setting Override to enable the feature on-premises by using the following parameters / values:
  • Name: EnableExchangeHybrid3PAppFeature
  • Component: Global
  • Section: ExchangeOnpremAsThirdPartyAppId
  • Parameters: Enabled=true
  • Reason: "Created by {Name of the Script} on {timestamp}"

DeleteApplication

• Delete the dedicated Exchange application in Entra ID

ResetFirstPartyServicePrincipalKeyCredentials

• Remove all existing keyCredentials from the Office 365 Exchange Online first-party application Service Principal
• If a thumbprint was provided via CertificateInformation parameter, purge only the certificate that matches the thumbprint and all certificates, which are already expired

Configuration using the script

Microsoft provides the ConfigureExchangeHybridApplication.ps1 script to configure the dedicated Exchange hybrid application feature. This section explains the most common scenarios covered by the script. Detailed documentation for the script and its parameters can be found in the ConfigureExchangeHybridApplication.ps1 script documentation.

If your on-premises organization has hybrid relationships with multiple tenants (1:N), you need to run the script multiple times. Each time, use an account from the tenant you want to configure the dedicated Exchange hybrid application feature for. Doing so ensures that the script creates and configures the application in each of your tenants.

Depending on the size of your organization, it may take up to 60 minutes for the dedicated Exchange hybrid application configuration to be recognized by the responsible Exchange Server processes. During this time, you might notice that features such as Free/Busy, MailTips, and Photos are temporarily unavailable.

All-in-one Configuration Mode

For most customers, the All-in-one Configuration Mode is the recommended way to configure this feature. To use this mode, run the script on a Mailbox server with outbound connectivity, as described in the Connectivity section. The server must be running an Exchange Server build that supports the dedicated Exchange hybrid application feature. Additionally, ensure you have the required permissions.

.\ConfigureExchangeHybridApplication.ps1 -FullyConfigureExchangeHybridApplication

By default, the script runs against the Microsoft 365 Worldwide cloud. If your Microsoft 365 tenant is in a different cloud, use the AzureEnvironment parameter. In the following example, the application is created in the Microsoft 365 operated by 21Vianet cloud:

.\ConfigureExchangeHybridApplication.ps1 -FullyConfigureExchangeHybridApplication -AzureEnvironment "ChinaCloud"

Split Execution Configuration Mode

If your Mailbox server, for example, doesn't have outbound Connectivity to Microsoft Graph or Entra ID, you can run the script in multiple steps. Some of these steps don't need to be performed on an Exchange server.

First, export the Auth Certificate (and, if available, the next Auth Certificate) with its public key. Use the script provided in the Auth Certificate section to perform the export. Don't export the private key of the certificate.

Next, copy the exported certificates to a machine with outbound connectivity, as described in the Connectivity section. On that machine, run the script to create the application in Entra ID. The script displays your Tenant ID and the appId of the newly created application. Be sure to make a note of both values, as you need them in a later step:

.\ConfigureExchangeHybridApplication.ps1 -CreateApplication -UpdateCertificate -CertificateMethod "File" -CertificateInformation "C:\Certificates\CurrentAuthCertificate.cer"

If multiple Auth Certificates were exported in the previous step, you must run the script twice. The CreateApplication step isn't required for the second run:

.\ConfigureExchangeHybridApplication.ps1 -UpdateCertificate -CertificateMethod "File" -CertificateInformation "C:\Certificates\NewNextAuthCertificate.cer"

This step must be performed on a Mailbox server. During this process, the Auth Server is configured, existing organization relationships between Exchange Server and Exchange Online are updated, and the dedicated Exchange hybrid application feature is enabled. You need to provide the ID of your tenant, the appId of the newly created application in Entra ID, and the remote routing domain:

.\ConfigureExchangeHybridApplication.ps1 -ConfigureAuthServer -ConfigureTargetSharingEpr -EnableExchangeHybridApplicationOverride -CustomAppId "<appId>" -TenantId "<tenantId>" -RemoteRoutingDomain "<organization>.mail.onmicrosoft.com"

Update Certificate Mode

The steps in this section aren't required when configuring and enabling the dedicated Exchange hybrid application feature for the first time. The steps can be used to update the certificate if the Auth Certificate expired or was replaced. For more information about maintaining the Auth Certificate, see the Maintain the Exchange Server OAuth certificate documentation.

If your Mailbox server has outbound connectivity, as described in the Connectivity section, run the script as follows:

.\ConfigureExchangeHybridApplication.ps1 -UpdateCertificate

If your Mailbox server doesn't have outbound connectivity to Microsoft Graph and Entra ID, follow the instructions in the Split Execution Configuration Mode section to export the new Auth Certificate. Copy the certificate to a machine with outbound connectivity (which doesn't have to be an Exchange server), as described in the Connectivity section. Then, run the script as follows:

.\ConfigureExchangeHybridApplication.ps1 -UpdateCertificate -CertificateMethod "File" -CertificateInformation "C:\Certificates\NewAuthCertificate.cer"

Delete Application Mode

This step isn't required when configuring and enabling the dedicated Exchange hybrid application feature. However, if needed, you can use the following command to delete the application created in Entra ID. This command can be executed on a non-Exchange server.

Deleting the application via the ConfigureExchangeHybridApplication.ps1 script doesn't revert the Exchange hybrid application configuration in your environment. If you need to switch back, follow the steps in the How to roll back from dedicated Exchange hybrid application section of this documentation.

To delete the application in Entra ID (you'd do this action only when rolling back the change or troubleshooting the creation of a new application in Entra ID), run the script as follows:

.\ConfigureExchangeHybridApplication.ps1 -DeleteApplication

Service Principal Clean-Up Mode

As part of the previous Exchange hybrid design, the Hybrid Configuration Wizard (HCW) uploaded the current Auth Certificate from your Exchange organization to the first-party Service Principal. This practice is no longer recommended and should not be performed. The Auth Certificate must now be uploaded exclusively to the dedicated Exchange hybrid application.

After enabling the dedicated Exchange hybrid application feature and ensuring all your Exchange servers are running an Exchange build that supports this feature, it's strongly recommended to clean up the certificates that were previously uploaded to the first-party Service Principal. The commands outlined in this section can be executed on any computer with outbound internet connectivity.

Purging the keyCredentials of the first-party Service Principal while any Exchange servers are still running builds older than those listed in the Exchange build that supports this feature section breaks rich coexistence hybrid features for those servers.

To purge all keyCredentials of the first-party Service Principal, run the script as follows:

.\ConfigureExchangeHybridApplication.ps1 -ResetFirstPartyServicePrincipalKeyCredentials

To purge a specific certificate and all expired certificates from the keyCredentials, run the script as follows and provide the thumbprint of the certificate to be deleted:

.\ConfigureExchangeHybridApplication.ps1 -ResetFirstPartyServicePrincipalKeyCredentials -CertificateInformation "1234567890ABCDEF1234567890ABCDEF12345678"

Validate OAuth Connectivity Status

To verify that OAuth authentication is functioning correctly between Exchange Server and Exchange Online, use the Test-OAuthConnectivity cmdlet:

Test-OAuthConnectivity -Service EWS -TargetUri https://outlook.office365.com -Mailbox "<OnPremisesMailboxSmtpAddress>" | Format-List

If the ResultType is Success and the Detail section includes the appId of your dedicated Exchange hybrid application, it indicates that Exchange Server successfully acquired an OAuth token. The OAuth request is initiated by the server where the Exchange Management Shell (EMS) session is running. If the mailbox specified via the -Mailbox parameter resides on a different server that does not support the dedicated Exchange hybrid app - but the EMS host server does - the ResultType still shows Success. This behavior is by design.

Auditing Exchange hybrid application usage in Entra ID

After configuring the dedicated Exchange hybrid application and enabling the feature on the Exchange Server, you can audit its usage through the Entra ID Sign-in logs. Follow these steps:

1. Log in to the Entra ID portal:

   Navigate to the Entra ID portal and log in with your credentials.

2. Access Microsoft Entra ID:

   In the portal, select or search for Microsoft Entra ID.

3. Navigate to Sign-in Logs:

   In the navigation pane, go to Monitoring and select Sign-in logs.

4. View Service Principal Sign-ins:

   Next, select Service principal sign-ins to view detailed logs.

The following picture illustrates a successful sign-in request:

When you click on the entry, the Activity Details: Sign-ins flyout opens, providing more information about the sign-in activity:

Restrict access to dedicated Exchange hybrid application service principal

Some organizations may want to restrict access to the dedicated Exchange hybrid application service principal to a subset of public IP ranges used by Exchange Server. This can be achieved by utilizing Conditional Access for workload identities. This feature extends support for Conditional Access policies to service principals owned by the organization. Workload Identities Premium licenses are required to create or modify Conditional Access policies scoped to service principals. For more information, visit Microsoft Entra Workload ID.

How to enable the dedicated Exchange hybrid application feature via setting override

If you used the Hybrid Configuration Wizard (HCW) to configure the dedicated Exchange Hybrid application, you must run the New-SettingOverride cmdlet to enable the feature for your on-premises Exchange Server organization. Execute the following command from an elevated Exchange Management Shell (EMS):

New-SettingOverride -Name "EnableExchangeHybrid3PAppFeature" -Component "Global" -Section "ExchangeOnpremAsThirdPartyAppId" -Parameters @("Enabled=true") -Reason "Enable dedicated Exchange hybrid app feature"
Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh

How to roll back from dedicated Exchange hybrid application

Until the dedicated Exchange hybrid application becomes the default in HCW and EWS is deprecated for first-party applications, you can roll back the configuration applied by the ConfigureExchangeHybridApplication.ps1 script. A rollback should only be performed if you encounter issues after configuring the feature.

As a first step, run HCW to reconfigure the first-party Service Principal. Make sure to select the Oauth, Intra Organization Connector and Organization Relationship option, as this setting executes the necessary steps to reconfigure the first-party Service Principal.

Next, remove the Setting Override that enables the dedicated Exchange hybrid application feature. To do this, run the following command from an elevated Exchange Management Shell (EMS):

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

To revert the Auth Server change applied by the script, run the following command from an elevated Exchange Management Shell (EMS):

# 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

As a final step, you can use the ConfigureExchangeHybridApplication.ps1 script to delete the application that was created in Entra ID:

.\ConfigureExchangeHybridApplication.ps1 -DeleteApplication

Frequently Asked Questions