The Microsoft Hybrid Agent Public Preview
Published Feb 05 2019 08:00 AM 41.8K Views

Update 4/9/2019: to read about additional features released in the Hybrid Agent, please go here.

The moment you’ve all been waiting for has arrived! We are pleased to announce the Microsoft Hybrid Agent for Exchange Server is now available for preview! We talked in some depth about the Hybrid Agent back at Ignite 2018 in Orlando, if you want a refresher on what we covered there you can see that recording here. The Hybrid Agent was designed to remove some of the existing challenges customers face today when establishing a Hybrid Exchange environment. This includes, but is not limited to, adding external DNS entries, updating certificates, and allowing inbound network connections through the firewall. From today, when running the Hybrid Configuration Wizard, you are presented with a new option for establishing hybrid; “Modern Hybrid”. Modern Hybrid is offered for both Minimal and Full Hybrid Configurations. This new option will only be presented if you have never run the Hybrid Configuration Wizard. If you have successfully established Hybrid in either Minimal or Full config before this release, this new option will not be available. HybridAgent1 This feature will install an agent, built on the same technology as Azure Application Proxy, which will publish the Exchange on-premises environment to Exchange Online to support Free/busy and mailbox migrations without many of the challenges customers previously faced with external DNS, publishing of EWS and inbound connections ports having to be opened. The secret sauce here to explain how this works is that the Hybrid Agent registers a custom URL for only your tenant in the following format:

<guid>.resource.mailboxmigration.his.msappproxy.net

This URL is then used by the Organization Relationship or the Intra Organization Connector and the Mailbox Replication Service to route requests from your tenant to on premises. This URL is only accessible from Exchange Online. Free/busy requests from cloud users to on premises and mailbox migrations to/from the cloud are the two flows currently supported through the Hybrid Agent. HybridAgent2 Yes, this new feature offers some great new capabilities and we’re very proud of it, but the Hybrid Agent preview still has a few constraints:
  • MailTips, Message Tracking and Multi-mailbox search do not traverse the Hybrid Agent. These Hybrid features would require the classic connectivity model where EWS and Autodiscover are published on-premises and externally available to Office 365.
  • The public preview only supports a single Hybrid Agent install for the Exchange Organization. We are working to support multiple agent installs for redundancy, but this is not available yet. If the server running the Hybrid Agent goes offline, free/busy look ups from your tenant to on-premises and mailbox migrations to/from your tenant will no longer work. If the server hosting the agent is permanently offline, was rebuilt, or the agent was uninstalled, you can recover the original configuration by re-running the Hybrid Configuration Wizard to reinstall the Hybrid Agent directly on the new server. Do not attempt to install multiple active Hybrid Agents in your environment with this preview build, this could cause unexpected issues.
  • The Hybrid Agent registers the internal FQDN of the Client Access Server (CAS) selected when running Hybrid Configuration Wizard in Azure Application Proxy. If the registered CAS is offline, free/busy look ups from your tenant to on-premises and mailbox migrations to/from your tenant will no longer work. If the selected CAS is permanently offline, a new CAS must be registered. This can be done by re-running the Hybrid Configuration Wizard.
  • You can’t use the Hybrid Agent if you plan on enabling Hybrid Modern Auth, which you also need to get the most out of Outlook mobile. You need to publish AutoDiscover, EWS, MAPI and OAB the Classic way if you want to use HMA externally.
  • The Hybrid Agent preview comes with some support limitations which are called out in the Terms document that you must agree to before installing the feature.
We also want to point out that SMTP does not traverse the Hybrid Agent and will still require a public certificate for mail flow between Office 365 and on-premises. SMTP traffic is out of scope for the Hybrid Agent, both now and through General Availability. There are a few limitations with this preview build, but that’s why it’s a preview! We still think there’s a lot the agent can do today, and that’s why we’re making it available to you now! Once you are ready to move forward with Hybrid Agent for your deployment, there are a few deployment decisions to make. Please read this next section all the way through before downloading and installing the agent. Choosing the right location for installation of the Hybrid Agent is important. The agent install and subsequent run of configuring Hybrid via the Hybrid Configuration Wizard is supported on either a standalone machine designed as your “agent server”, or an Exchange 2010, 2013, 2016 or 2019 server with the Client Access role. The easiest way to deploy is accomplished by installing the Hybrid Agent directly on an Exchange CAS as it simplifies connectivity, but it is not required.

Here are the agent server requirements

  • The machine hosting the Hybrid Agent install must be able to establish outbound HTTPS connections to the internet, and HTTPS and Remote PowerShell (RPS) connections to the CAS chosen for hybrid configuration.
  • The machine hosting the Hybrid Agent should be running Windows Server 2012 R2 or 2016, with .NET Framework 4.6.2 (or later, as supported by the Exchange version you are installing on) installed.
  • The machine where the Hybrid Agent is installed must have either Edge or Internet Explorer installed and must support ClickOnce.
  • The machine where the Hybrid Agent is installed must be able to communicate with a Domain Controller to authenticate your on-premises Exchange Org admin credentials. This means that the machine must be domain joined.
  • Installation must be done using a local machine administrator account and will require tenant global administrator credentials for registering the connector.
  • TLS 1.2 must be enabled on the machine where the Hybrid Agent is installed.
Now, the smart people with a good memory reading this post might spot one interesting wrinkle in this list above: we support you installing the agent on an Exchange 2010 server, but we require you use Windows Server 2012 R2 or later... Hang on, that’s not possible. That’s not supported. You didn’t spot that? Shame on you. Well, for those that did, firstly, have a gold star and a pat on the back – and secondly, we’re announcing here that we will support Exchange Server 2010 installed on Windows Server 2012 R2 with the upcoming release of Update Rollup 26 for Exchange Server 2010 SP3. We’re doing that so if you really want to add another Exchange 2010 server to your org, on Windows Server 2012 R2, you can. You’re welcome.

Port and Protocol requirements for the agent server

  • Ports to be opened outbound are HTTPS (TCP) 443 and 80, as shown here.
  • The agent machine must be able to connect HTTPS (TCP) 443, 80, 5985 and 5986 to the target CAS selected in the Hybrid Configuration Wizard.

Important notes

  • All Client Access Servers must be able to reach outbound to Office 365 endpoints via HTTPS (TCP) 443 as free/busy request from on-premises users to Office 365 users do not traverse the Hybrid Agent. These requests still require your Exchange servers have outbound connectivity to Office 365 end points. Office 365 URLs and IP address ranges describes the required (and hybrid) ports and IPs outbound from on-premises to the service.
  • The specific Client Access Server selected in the Hybrid Configuration Wizard must be able to make a Remote PowerShell connection to Office 365.
  • The agent does support using an outbound proxy but doing so requires modifications to the configuration file after installation. Also, a proxy which prevents registration will result in the connector failing to install. It is recommended to install allowing the connectors to bypass the proxy until app config changes can be made.
“Wow”, you say, “I wish it was easier to confirm the required connectivity before installing…”. Well you are in luck! We have built a port and endpoint verification script helper just for you! We recommend you install this script on your designated agent machine, run it, and confirm all the port requirements have been met prior to installing. In our experience, it is likely your environment is thoroughly locked down and ensuring the required ports and endpoint are working as required will make your installation and configuration experience much better!

Verifying connectivity

  1. On the server where you will be running the Hybrid Configuration Wizard (Hybrid Agent install and subsequent hybrid configuration steps), download the following sample script and save it to any directory: http://aka.ms/hybridconnectivity.
  2. Open PowerShell and change directory to the location of the script.
  3. Import the cmdlets: Import-Module .\HybridManagement.psm1
  4. Next run Test-HybridConnectivity with the testO365Endpoints option to verify the machine you are installing on can reach out to all required endpoints for the Hybrid Agent installation and Hybrid Configuration Wizard setup.
  5. Sample run below:
HybridAgent3

Uninstalling the Hybrid Agent

To uninstall the Hybrid Agent, re-run Hybrid Configuration Wizard from the same machine you performed the installation against and select Classic Connectivity. This will uninstall and de-register the Hybrid Agent from the machine and Azure, and you can resume setup and configure hybrid in the Classic mode.

More information

Additional details on the installation requirements and steps can be found here. Now you are ready to run the Hybrid Configuration Wizard and install the new Hybrid Agent! Happy Hybriding and we look forward to reading your feedback, please do leave us comments below. The Hybrid Team
33 Comments
Version history
Last update:
‎Jul 01 2019 04:35 PM
Updated by: