Choose Exchange Hybrid Configuration
Overview
With the new release of the Hybrid Configuration Wizard (HCW), administrators can explicitly select the hybrid configurations that should be done during an HCW run. This helps administrators to preserve their customized configurations and prevent HCW from resetting them by selecting and deselecting configurations.
We revised the permissions that are required to run the HCW. The permissions that are required to run the HCW can be found in the Hybrid Configuration wizard documentation.
What is the benefit of the new "Choose Exchange Hybrid Configuration" feature
During a rerun of the HCW, administrators don't require many first-time configurations that HCW does. HCW doesn't allow skipping of any configurations, which resets many custom configurations done after previous HCW run. This behavior sometimes leads to a bad Exchange Server hybrid configuration state. You can skip many of the steps, which are not needed for existing hybrid configurations by using the newly introduced Choose Exchange Hybrid Configuration feature.
Administrators sometimes need to do HCW reruns for Organization Configuration Transfer (OCT) or to perform a TLS certificate update, which isn't available through any other tool. If an HCW rerun is done in addition to OCT and TLS certificate update, HCW resets all hybrid configurations (for example, modification in connectors, migration endpoints etc.) which may not be desired. These changes cause extra configuration overhead as administrators have to adjust the configuration again afterwards. You can avoid this behavior now by using the newly introduced Choose Exchange Hybrid Configuration feature.
Granular configuration options
This section explains the configuration options available when using the Choose Exchange Hybrid Configuration feature. You can choose from these options to configure your hybrid deployment according to your needs. We have covered some scenarios of when which option can be used in the FAQ section of this article.
Regardless of the selected option, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-OnPremisesOrganization or Set-OnPremisesOrganization
[-Name '<guid>']
[-HybridDomains <AcceptedTrustedDomains>]
[-InboundConnector 'Inbound from <guid>']
[-OutboundConnector 'Outbound to <guid>']
[-OrganizationRelationship 'O365 to On-premises - <guid>']
[-OrganizationName '<NameOfTheOrganization>']
[-OrganizationGuid '<guid>']
[-Comment '<ConfigurationHash>']
New-HybridConfiguration or Set-HybridConfiguration
[-ClientAccessServers $null]
[-ExternalIPAddresses $null]
[-Domains <AcceptedTrustedDomains>]
[-OnPremisesSmartHost <OnPremisesEntryPointDomain>]
[-TLSCertificateName '<I>X.500Issuer<S>X.500Subject']
[-SendingTransportServers <TransportServers>]
[-ReceivingTransportServers <TransportServers>]
[-EdgeTransportServers <EdgeTransportServers> or $null]
[-Features FreeBusy,MoveMailbox,Mailtips,MessageTracking,OwaRedirection,OnlineArchive,SecureMail,Photos]
Configure Hybrid Features
The Configure Hybrid Features section contains settings that can be used to configure hybrid features in general, such as free/busy, MailTips, or migration endpoints. Additionally, this section includes the Organization Configuration Transfer feature.
Oauth, Intra Organization Connector and Organization Relationship
Selecting this option configures (or re-configures) Intra-Organization Connectors, Organization Relationships and creates the OAuth trust between Exchange Server on-premises and Exchange Online. These configurations are needed for free/busy sharing, MailTips, Online Archiving and more.
Important
Make sure that the OAuth certificate, which is used by Exchange Server on-premises, is valid before running this configuration. You can find more information about the required steps in the Maintain the Exchange Server OAuth certificate documentation.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-OrganizationRelationship
[-Name 'On-premises to O365 - <guid>']
[-TargetApplicationUri $null]
[-TargetAutodiscoverEpr $null]
[-Enabled $true]
[-DomainNames <domain>.mail.onmicrosoft.com]
New-OrganizationRelationship
[-Name 'O365 to On-premises - <guid>']
[-TargetApplicationUri $null]
[-TargetAutodiscoverEpr $null]
[-Enabled $true]
[-DomainNames <OnPremisesEntryPointDomain>]
Set-OrganizationRelationship
[-Identity 'On-premises to O365 - <guid>']
[-MailboxMoveEnabled $true]
[-FreeBusyAccessEnabled $true]
[-FreeBusyAccessLevel LimitedDetails]
[-ArchiveAccessEnabled $true]
[-MailTipsAccessEnabled $true]
[-MailTipsAccessLevel All]
[-DeliveryReportEnabled $true]
[-PhotosEnabled $true]
[-TargetOwaURL 'https://outlook.office.com/mail']
Set-OrganizationRelationship
[-Identity 'O365 to On-premises - <guid>']
[-FreeBusyAccessEnabled $true]
[-FreeBusyAccessLevel LimitedDetails]
[-TargetSharingEpr $null]
[-MailTipsAccessEnabled $true]
[-MailTipsAccessLevel All]
[-DeliveryReportEnabled $true]
[-PhotosEnabled $true]
[-TargetOwaURL $null]
New-IntraOrganizationConnector or Set-IntraOrganizationConnector
[-Name 'HybridIOC - <guid>']
[-DiscoveryEndpoint 'https://autodiscover-s.outlook.com/autodiscover/autodiscover.svc']
[-TargetAddressDomains <domain>.mail.onmicrosoft.com]
[-Enabled $true]
New-IntraOrganizationConnector or Set-IntraOrganizationConnector
[-Name 'HybridIOC - <guid>']
[-DiscoveryEndpoint 'https://<OnPremisesEntryPointDomain>/autodiscover/autodiscover.svc']
[-TargetAddressDomains <OnPremisesEntryPointDomain>]
[-Enabled $true]
Set-PartnerApplication
[-Identity 'Exchange Online']
[-Enabled $true]
New-AuthServer or Set-AuthServer
[-Name 'ACS - <guid>']
[-AuthMetadataUrl 'https://accounts.accesscontrol.windows.net/<guid>/metadata/json/1']
[-DomainName '<AcceptedDomains>','<domain>.mail.onmicrosoft.com']
New-AuthServer or Set-AuthServer
[-Name 'EvoSts - <guid>']
[-AuthMetadataUrl 'https://login.windows.net/<domain>.onmicrosoft.com/federationmetadata/2007-06/federationmetadata.xml']
[-Type AzureAD]
Add-AvailabilityAddressSpace
[-ForestName <domain>.mail.onmicrosoft.com]
[-AccessMethod InternalProxy]
[-UseServiceAccount $true]
[-ProxyUrl <OnPremisesEwsUrl>]
Update Coexistence Domain in Exchange Server Accepted domain and Email Address Policy
Selecting this option adds Exchange Online co-existence domain (<domain>.mail.onmicrosoft.com) as accepted domain to Exchange Server on-premises for hybrid mail flow and AutoDiscover requests. The coexistence domain is used for secondary email addresses (also known as proxy addresses) in any email address policies that contain the domains you specified in the Hybrid Configuration Wizard.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-RemoteDomain or Set-RemoteDomain
[-Name 'Hybrid Domain - <domain>.mail.onmicrosoft.com']
[-DomainName <domain>.mail.onmicrosoft.com]
[-TargetDeliveryDomain $true]
New-RemoteDomain or Set-RemoteDomain
[-Name 'Hybrid Domain - <domain>.onmicrosoft.com']
[-DomainName <domain>.onmicrosoft.com]
[-TrustedMailInboundEnabled $true]
New-AcceptedDomain or Set-AcceptedDomain
[-Name <domain>.mail.onmicrosoft.com]
[-DomainName <domain>.mail.onmicrosoft.com]
Set-EmailAddressPolicy
[-Identity 'Default Policy']
[-ForceUpgrade $true]
[-EnabledEmailAddressTemplates 'smtp:@<domain>.onmicrosoft.com','smtp:@<AdditionalAcceptedDomains>','SMTP:@<DefaultAcceptedDomain>','smtp:%m@<domain>.mail.onmicrosoft.com']
Migration Endpoint
Selecting this option creates a migration endpoint in the Exchange Online tenant. The migration endpoint is needed to move (migrate) mailboxes from Exchange Server on-premises to Exchange Online.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-MigrationEndpoint or Set-MigrationEndpoint
[-Name 'Hybrid Migration Endpoint - EWS (Default Web Site)']
[-ExchangeRemoteMove $true]
[-RemoteServer <OnPremisesEntryPointDomain>]
[-Credentials (Get-Credential -UserName <ADDomain>\<Username>)]
Organization Configuration Transfer
Selecting this option copies the organization policy objects and values from Exchange Server on-premises to Exchange Online.
See Organization configuration transfer attributes for a list of attributes that are copied from an on-premises Exchange organization to Exchange Online.
Configure Mail Flow
The Configure Mail Flow section provides settings that can be used to configure hybrid mail flow related features, such as connectors in Microsoft 365 and Exchange Server on-premises, and Centralized Mail Transport. It also includes a configuration action that can be used to replace the certificate used to secure the email flow between Exchange Server on-premises and Exchange Online.
Outbound Connector in M365 Organization
Selecting this option configures either a new or modifies an existing Outbound Connector in Microsoft 365 organization.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-OutboundConnector or Set-OutboundConnector
[-Name 'Outbound to <guid>']
[-RecipientDomains <RecipientDomains>]
[-SmartHosts <OnPremisesSmartHost>]
[-ConnectorSource HybridWizard]
[-ConnectorType OnPremises]
[-TLSSettings DomainValidation]
[-TLSDomain <TLSCertificateDomain>]
[-CloudServicesMailEnabled $true]
[-RouteAllMessagesViaOnPremises $false]
[-UseMxRecord $false]
[-IsTransportRuleScoped $false]
Inbound Connector in M365 Organization
Selecting this option configures either a new or modifies an existing Inbound Connector within the Microsoft 365 organization.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-InboundConnector or Set-InboundConnector
[-Name 'Inbound from <guid>']
[-CloudServicesMailEnabled $true]
[-ConnectorSource HybridWizard]
[-ConnectorType OnPremises]
[-RequireTLS $true]
[-SenderDomains '']
[-SenderIPAddresses $null]
[-RestrictDomainsToIPAddresses $false]
[-TLSSenderCertificateName <TLSCertificateDomain>]
[-AssociatedAcceptedDomains $null]
Receive Connector on Exchange Hybrid Server
Selecting this option configures either a new and or modifies an existing Receive Connector in Exchange Server on-premises organization.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-ReceiveConnector or Set-ReceiveConnector
[-Identity '<ServerName>\Default Frontend <ServerName>']
[-AuthMechanism 'Tls, Integrated, BasicAuth, BasicAuthRequireTLS, ExchangeServer']
[-Bindings '[::]:25','0.0.0.0:25']
[-Fqdn <ServerFqdn>]
[-PermissionGroups 'AnonymousUsers, ExchangeServers, ExchangeLegacyServers']
[-RemoteIPRanges '::-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff','0.0.0.0-255.255.255.255']
[-RequireTLS $false]
[-TLSDomainCapabilities mail.protection.outlook.com:AcceptCloudServicesMail]
[-TLSCertificateName '<I>X.500Issuer<S>X.500Subject']
[-TransportRole FrontendTransport]
Send Connector on Exchange Hybrid Server
Selecting this option configures either a new or modifies an existing Send Connector in Exchange Server on-premises organization.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-SendConnector or Set-SendConnector
[-Name 'Outbound to Office 365 - <guid>']
[-AddressSpaces 'smtp:<domain>.mail.onmicrosoft.com;1']
[-DNSRoutingEnabled $true]
[-ErrorPolicies Default]
[-Fqdn <OnPremisesEntryPointDomain>]
[-RequireTLS $true]
[-IgnoreSTARTTLS $false]
[-SourceTransportServers <TransportServers>]
[-SmartHosts $null]
[-TLSAuthLevel DomainValidation]
[-DomainSecureEnabled $false]
[-TLSDomain mail.protection.outlook.com]
[-CloudServicesMailEnabled $true]
[-TLSCertificateName '<I>X.500Issuer<S>X.500Subject']
Enable Centralized Mail Transport
Selecting this option routes outbound messages, sent from your Exchange Online organization through your Exchange Server on-premises organization. In Centralized Mail Transport (CMT) configurations, actual changes are done in Inbound and Outbound Connectors. Hence whenever CMT is selected, the Inbound and Outbound Connectors are automatically selected. Deselecting an Inbound or Outbound Connector does automatically deselect the Enable Centralized Mail Transport option.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
New-InboundConnector or Set-InboundConnector
[-Name 'Inbound from <guid>']
[-CloudServicesMailEnabled $true]
[-ConnectorSource HybridWizard]
[-ConnectorType OnPremises]
[-RequireTLS $true]
[-SenderDomains '']
[-SenderIPAddresses $null]
[-RestrictDomainsToIPAddresses $false]
[-TLSSenderCertificateName <TLSCertificateDomain>]
[-AssociatedAcceptedDomains $null]
New-OutboundConnector or Set-OutboundConnector
[-Name 'Outbound to <guid>']
[-RecipientDomains '*']
[-SmartHosts <OnPremisesSmartHost>]
[-ConnectorSource HybridWizard]
[-ConnectorType OnPremises]
[-TLSSettings DomainValidation]
[-TLSDomain <TLSCertificateDomain>]
[-CloudServicesMailEnabled $true]
[-RouteAllMessagesViaOnPremises $true]
[-UseMxRecord $false]
[-IsTransportRuleScoped $false]
Update Secure Mail Certificate for connectors
Tip
The Update Secure Mail Certificate for connectors configuration is a new option, which was introduced to simplify the reoccurring transport certificate renewal process in hybrid scenarios.
If you only need to update the TLS certificate used by all four connectors while keeping other connector configurations the same, select this option.
When selecting this option, you don't need to select any other connector configuration, if you want to preserve the existing connector configuration. If any other connector configuration option was also selected, along with the TLS certificate update, other configuration changes occur for the connector.
If this option is selected, HCW executes the specified cmdlets and parameters:
Show cmdlets
Set-InboundConnector
[-Name 'Inbound from <guid>']
[-TLSSenderCertificateName <TLSCertificateDomain>]
Set-OutboundConnector
[-Name 'Outbound to <guid>']
[-TLSDomain <TLSCertificateDomain>]
Set-ReceiveConnector
[-Identity '<ServerName>\Default Frontend <ServerName>']
[-TLSCertificateName '<I>X.500Issuer<S>X.500Subject']
Set-SendConnector
[-Name 'Outbound to Office 365 - <guid>']
[-TLSCertificateName '<I>X.500Issuer<S>X.500Subject']
How to use the new "Choose Exchange Hybrid Configuration" feature
In the latest version of HCW, administrators can use the Choose Exchange Hybrid Configuration feature as follows:
On the
Hybrid Topologypage, based on the topology that you want to configure, you can select betweenClassic HybridandModern Hybrid. This page is also the point at which you can decide whether you want to use the newChoose Exchange Hybrid Configurationfeature or not. If you want to update only specific hybrid configurations without altering any other configurations, selectChoose Exchange Hybrid Configurationand clickNext.
If
Choose Exchange Hybrid Configurationwas selected, a newChoose what HCW configuressection is shown on which administrators can select from the following hybrid configurations. You can find a description of each configuration in the Granular configuration options section of this article.
Note
If you've selected
Minimal Hybrid Configurationon the previous page, theChoose what HCW configuressection isn't shown. This is becauseChoose Exchange Hybrid Configurationis not supported in this scenario.Based on your selection, the required configuration sections will be shown after clicking on
Next. If, for example, onlyOrganization Configuration Transferwas selected, HCW will only show the OCT configuration page in the next step.Administrators shouldn't change the default hybrid configuration by deselecting existing configuration, unless it's an HCW rerun and the intention is, to preserve existing hybrid configurations, which would have been modified after last run. If, by mistake, some options were selected or deselected, click on the
Reset Choicesbutton to revert the selection back to the preselected default.You can always come back to the
Choose what HCW configuresoverview and make adjustments to the selection. That is possible until you clicked onUpdateon the last page.Click on
Nextand continue with the configuration as usual (for example, selecting the transport certificate).Once you've click on
Update, HCW performs the selected actions. On the final page, it shows you all the hybrid configurations that were excluded viaChoose Exchange Hybrid Configurationfeature.
Other changes made to the HCW
With the introduction of the Choose Exchange Hybrid Configuration feature, we made several other adjustments to the Hybrid Configuration Wizard to comply with the new feature.
Centralized Mail Transport (CMT) configuration is moved to the Choose what HCW configures page:
Old experience:
New experience:
On the Hybrid Features page, the option to select Organization Config Transfer was removed for Full Hybrid Configuration. This option can now be accessed via the Choose what HCW configures page:
Old experience:
New experience:
FAQs
This section discusses various questions that can come up while using this new feature.
Q: Should I use the Choose Exchange Hybrid Configuration feature if I'm setting up Exchange Server Hybrid for the first time?
That isn't needed unless you also want to perform
Organization Configuration Transfer(OCT). If OCT is needed by you in your first HCW run, then selectChoose Exchange Hybrid Configuration, and on theChoose what HCW configurespage selectOrganization Configuration Transferadditionally to all the preselected configurations.
Q: We run HCW to configure Exchange Hybrid once already. We used the the Choose Exchange Hybrid Configuration feature but forgot to select Migration Endpoint to be configured. What should we do now?
It's no problem. You can rerun the HCW, deselect everything except
Migration Endpointand finish the run. HCW configures the migration endpoint for you without updating anything else.
Q: We run HCW to configure Exchange Hybrid once already. Today, we only need to update TLS certificate for all connectors. How should we do that?
Rerun the HCW, select
Choose Exchange Hybrid Configurationand on theChoose what HCW configurespage deselect everything exceptUpdate Secure Mail Certificate for connectors.
Q: We run HCW to configure Exchange Hybrid once already. Today, we only need to perform an Organization Configuration Transfer. How should we do that?
Rerun the HCW, select
Choose Exchange Hybrid Configurationand on theChoose what HCW configurespage deselect everything exceptOrganization Configuration Transfer.
Q: We're currently using Modern Hybrid but want to switch to Classic Hybrid. We don't want to change anything related to mail flow, which is working properly. How can we do that?
Rerun the HCW and select
Classic Hybrid Topology. On theChoose Exchange Hybrid Configurationpage, at least select,Oauth, Intra Organization Connector and Organization RelationshipandMigration Endpointconfiguration.
Q: We run HCW to configure Exchange Hybrid once already. After Exchange Server hybrid setup, we made many changes on either of the four connectors. We want to rerun HCW and update some other hybrid configurations but don't want to change anything related to mail flow, which is working properly. How can we do that?
Rerun the HCW, select
Choose Exchange Hybrid Configurationand on theChoose what HCW configurespage don't select the following four configurations:Outbound Connector,Inbound Connector,Receive ConnectorandSend Connector.
Q: We have many accepted domains in our organization and during a HCW rerun, HCW tries to create Service Principal Name (SPN) sets for each of the Accepted Domain. We hit a limit in Entra ID but are unsure what the limit is. The HCW log file contains the following exception:[Directory_ResourceSizeExceeded] The size of the object has exceeded its limit. Please reduce the number of values and retry your request.
What is the limit and how can we avoid it?
We don't have a specified limit for the number of SPNs that can be added, as it depends on how these values are stored. However, there is a limitation on the total number of entries an attribute can contain. This limit is considered a practical limit, meaning the size of each individual entry affects the overall limit. Our tests indicate that it's likely to reach this limit if more than 800 SPNs are added. Keep in mind that this is a practical limit, so you might reach it with fewer or more than 800 SPNs.
To workaround this, rerun the HCW, select
Choose Exchange Hybrid Configurationand on theChoose what HCW configurespage don't select the following configurations:Oauth, Intra Organization Connector and Organization Relationship. Deselecting this option prevents HCW from creating SPNs for all accepted domains.