On Demand Migration Current - Active Directory Domain Rewrite Quick Start Guide

How are Transport Rules & Send Connectors used?

How are Transport Rules & Send Connectors used?  

Exchange Online transport rules and send connectors are used to route mail from an Microsoft 365 tenant to On Demand Migration Domain Rewrite Service. Transport Rules examine a message to determine if it should be rewritten and the connectors route the message to On Demand Migration Domain Rewrite Service. This ensures that only messages that need to be rewritten are routed to On Demand Migration Domain Rewrite Service and messages that do not are immediately sent to the recipients.

Important Tip: Support for the Domain Rewrite Service is limited to mail flow configurations that use Microsoft 365 for message ingress and egress. Centralized mail flow configurations that use the on-premises Exchange environment for inbound and outbound message delivery may require custom configuration with Support.

There are 3 categories of transport rules. The following section outlines each category and describes the naming convention used for the rules.

Sorting Rules

For outbound messages, a sorting rule examines each recipient on an SMTP message and adds an SMTP header to identify if the recipient is internal or external.

• BT-IntegrationPro-Out-S-Internet – rule for external recipients.

• BT-IntegrationPro-Out-S-[Guid]-[#] – rules for internal recipients in target tenant [Guid] where [#] indicates a block of SMTP domains. E.g. BT-IntegrationPro-Out-S-15d82781-e5e8-4691-a77f-0f5fb10b6482-1

From, To, CC Rules

For outbound messages, these rules determine if any of the From, To or CC addresses on an SMTP message include an internal or external recipient that should be rewritten and update the SMTP header added above appropriately.

• BT-IntegrationPro-Out-[From/ToCc] – rules for external recipients.

• BT-IntegrationPro-Out-[Guid]-[From/ToCc] – rules for internal recipients in target tenant [Guid]. E.g. BT-IntegrationPro-Out-15d82781-e5e8-4691-a77f-0f5fb10b6482-From.

Inbound Rules

The outbound rules ensure that Microsoft 365 routes only the messages that need to be rewritten to On Demand Migration Domain Rewrite Service. The inbound rules have two functions.

• BT-IntegrationPro-In - rule for messages returning from On Demand Migration Domain Rewrite Service.

  After a message is rewritten, it is returned to the original tenant for delivery to external recipients.

  This rule removes the header added by the outbound rules so that a message is only processed by On Demand Migration Domain Rewrite Service once.

• BT-IntegrationPro-In-DKIM - rule for messages returning from On Demand Migration Domain Rewrite Service.

  When an external recipient replies to an ERS user, the message is rewritten back to the original domain. After which, the message is redirected to the original tenant.

  This rule removes the secret key added to the header by the sending tenant to ensure the message was securely delivered before and after being rewritten.

How does Mail Flow work with Domain Rewrite?

Important Tip: Microsoft 365 Advanced Threat Protection default settings may cause issues with Domain Rewrite for inbound messages.  Please ensure that "Automatic forwarding" is set to "On" in the "Outbound spam filter policy" for your source or target tenant depending on the rewriting scenario you choose.

Rewrite with Target Address – Outbound Mail Flow

• When a user sends an email as user@source.com, the Transport Rules in the Source Tenant check whether the message is in scope for Domain Rewrite

• At least one external recipient in “To” or “Cc”

• Sender and/or at least one recipient in “To” or “Cc” is Domain Rewrite Enabled

• If the message is in scope for Domain Rewrite and there are multiple internal and external recipients, the message will be bifurcated and:

• Copy of the message sent to external recipient will be securely redirected to the Quest Rewrite Service using the Outbound Connector in the Source Tenant.

• Copy of the message sent to internal recipient is delivered by Exchange Online at the Source  tenant with unchanged addresses.

  Important Tip: Messages directed to internal recipient(s) will not be processed by Quest Rewrite Service.

   

• When the Domain Rewrite Service receives the message from user@source.com, it processes it by rewriting @source.com to @target.com for every user that has Domain Rewrite enabled. The addresses in "From", "To", and "Cc" of the email message are rewritten for all external recipients.

• The Domain Rewrite Service adds a new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Source Tenant using the Inbound Connector.

• Exchange Online at the Source sends the message to external recipients as if it was sent by user@target.com, and all addresses of message recipients in "To" and "Cc" that have Domain Rewrite enabled appear as @target.com for external recipients

  

Rewrite with Target Address – Inbound Mail Flow

• External recipient is not aware about @source.com and replies (or creates a new email) to user@target.com

• When the reply or a new mail arrives to the Target mail domain, the Transport Rules in the Target Tenant check whether any recipients in the “To” or “Cc” are in scope for Domain Rewrite

• If the message is in scope for Domain Rewrite and there are multiple internal (recipients in the Target Tenant) and external recipients (recipients in the Source Tenant with Domain Rewrite enabled), the message will be bifurcated and:

• Copy of the message sent to external recipient (recipients in the Source Tenant with Domain Rewrite enabled) will be securely redirected to the Domain Rewrite Service using the Outbound Connector in the Target Tenant

• Copy of the message sent to internal recipient is delivered by Exchange Online at the Target tenant with unchanged addresses

• When the Domain Rewrite Service receives the message addressed to user@target.com, it processes it by rewriting @target.com back to @source.com for every user that has Domain Rewrite enabled

• The Domain Rewrite Service new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Target Tenant using the Inbound Connector

• Exchange Online at the Target forwards the message to the Source

• Source recipient gets the message as if it was addressed to user@source.com

Rewrite with Source Address – Outbound Mail Flow

• When a user sends an email as user@target.com, the Transport Rules in the Target Tenant check whether the message is in scope for Domain Rewrite

• At least one external recipient in “To” or “Cc”

• Sender and/or at least one recipient in “To” or “Cc” is Domain Rewrite Enabled

• If the message is in scope for Domain Rewrite and there are multiple internal (recipients in the Target Tenant) and external recipients, the message will be bifurcated and:

• Copy of the message sent to external recipient will be securely redirected to the Domain Rewrite Service using the Outbound Connector in the Target Tenant

• Copy of the message sent to internal recipient is delivered by Exchange Online at the Target Tenant with unchanged addresses

• When the Domain Rewrite Service receives the message from user@target.com, it processes it by rewriting @target.com to @source.com for every user that has Domain Rewrite enabled. The addresses in "From", "To", and "Cc" of the email message are rewritten for all external recipients

• The Domain Rewrite Service a new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Target Tenant using the Inbound Connector

• Exchange Online at the Target sends the message to external recipients as if it was sent by user@source.com, and all addresses of message recipients in "To" and "Cc" that have Domain Rewrite enabled appear as @source.com for external recipients

Rewrite with Source Address – Inbound Mail Flow

• External recipient is not aware about @target.com and replies (or creates a new email) to user@source.com

• When the reply or a new mail arrives to the Source mail domain, the Transport Rules in the Source Tenant check whether any recipients in the “To” or “Cc” are in scope for Domain Rewrite

• If the message is in scope for Domain Rewrite and there are multiple internal (recipients in the Source Tenant) and external recipients (recipients in the Target Tenant with Domain Rewrite enabled), the message will be bifurcated and:

• Copy of the message sent to external recipient (recipients in the Target Tenant with Domain Rewrite enabled) will be securely redirected to the Domain Rewrite Service using the Outbound Connector in the Source Tenant

• Copy of the message sent to internal recipient is delivered by Exchange Online at the Source Tenant with unchanged addresses

• When the Domain Rewrite Service receives the message addressed to user@source.com, it processes it by rewriting @source.com back to @target.com for every user that has Domain Rewrite enabled

• The Domain Rewrite Service a new DKIM-Signature to the message and securely (via the certificate uploaded during project setup) redirects it back to the Source Tenant using the Inbound Connector

• Exchange Online at the Source forwards the message to the Target

• Target recipient gets the message as if it was addressed to user@target.com

Can I exclude Domain Rewrite for specific recipients?

Some external applications process workflows and approvals with automated emails and require the sender’s email address to match what is configured in the application.  For these applications, you can add an exclusion to the transport rules created by On Demand to prevent Domain Rewrite from occurring on these messages.

Important Tip: When adding exclusions to an On Demand Domain Rewrite transport rule, do not delete any of the pre-configured parameters. Disabling, changing priority, or modifying transport rules incorrectly can cause Domain Rewrite to stop working.

Add exclusion to On Demand Rewrite transport rule

• Log in to Exchange Online Admin Center and view the Transport Rules

• Select the Rule “BT-IntegrationPro-Out-S-Internet” and click the Edit icon

  

• Click “Add Exception”
  

• Hover over “The recipient…”
  

• Select “domain is”
  

How do I install and configure Directory Sync agents?

A Directory Sync agent must be installed in every forest that is attached to a tenant used in a Domain Rewrite project.

Manage Agents in On Demand Domain Rewrite Project

• Log in to On Demand

• Navigate to Migration, select the project and click on Domain Rewrite.

• Select the Domain Rewrite project previously configured.

• Click on the Settings icon in the upper right.

• Click the Directory Integration tab

Download and install the agent 

From this page, you can download the agent installer, check the status of your current agents, add new agents, archive old agents, and view the run history for each agent. The Registration URL and the Registration Key are displayed so that you can copy and paste them during the install of the agent.

Important Tip: The downloadable executable is the same for all projects, the Registration URL is unique to each On Demand region, and the Registration Key is unique to each local environment.

When installing the agent on a server that meets the On Demand requirements, you will enter the credentials of the Domain Account that has read/write access to the domain along with the Registration URL and Registration Key copied previously.