Domain Rewrite Requirements
Domain Rewrite (Email Rewrite)
To deploy Domain Rewrite between tenants the following will need to be ready prior to the configuration of the service.
Domain Rewrite Deployment Checklist:
The following checklist provides a quick reference to the items or decisions required to begin configuration of Domain Rewrite.
- Procure one (1) SSL single domain certificate for each tenant environment using one (1) of the accepted domains.
- The password associated with the SSL certificate will be required when uploading each certificate.
- Choose which domains will particulate in Domain Rewrite.
- Deploy DKIM DNS TXT records for each tenant environment during project set up.
SSL Certificates
To successfully configure the Email Rewrite Service, a valid SSL certificate must be procured for each source and target tenant. Each certificate must contain a single accepted domain, one (1) for each tenant. The selected certificate cannot contain subject alternative names (SAN). The common name (Subject Name) must match one (1) of the Exchange Online accepted domains configured within the tenant.
This certificate is utilized to secure the Exchange Online connectors over TLS that will be used to transfer message between the Email Rewrite service and each tenant. The new certificates will be uploaded to the project using a PFX formatted certificate. PFX files contain the public key file (SSL Certificate file) and the associated private key file (password).
The requirements for the certificate are as follows: (Names are for example purposes only.)
- Common Name: contoso.com
- Cryptographic service provider: Microsoft RSA SChannel Cryptographic Provider
- Bit length: 2048 or higher
- Must be valid for Server Authentication and Client Authentication.
- Must be signed by a trusted public root CA.
- Must contain a private key (password).
- Must not expire before the end of the project.
- Must have a Friendly Name defined.
DKIM (Email Signatures)
Domain Rewrite ensures email authenticity after rewrites by signing messages using a Domain Keys Identified Mail (DKIM) certificate. To properly sign emails, a DKIM certificate will automatically be generated and assigned to each participating domain(s) in the source and target tenants.
Each participating Accepted SMTP Domain from the source and target tenants will require a DKIM TXT record be created in your public DNS. During project configuration, Domain Rewrite will generate all the required parameters to easily and quickly publish your TXT records for each domain.
Each participating Accepted SMTP Domain from the source and target tenants will require to enable DKIM at the tenant level, additional information can be found at this Microsoft Link How to use DKIM for email in your custom domain - Office 365 | Microsoft Learn
DNS
To complete set up of Domain Rewrite the DKIM/Email Signatures DNS txt record must be published in the source and target public DNS. Once the records are published, Domain Rewrite will automatically verify the records. Once verified you will be able to complete the project’s Domain Rewrite configurations.
The following is an example of the TXT record parameters required to publish the record. Your key will be unique to your project.
- Name: selector1._domainkey
- Type: TXT
- TTL: 10
- Value: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCmvFUb+TkozfdnA0dA3AHOwAUYdfNVlBkR72+gqp2GxwK8yYPRI/E1/zp5DDZ/i8epWTR/F9u4jDJxjLqYF9d8m7qhJFjXxzWH2TbMQC4VgUfRtq5WAJmPUrCBdxxvMoOAKQ+aYagtXpv9HlH7PAKXsUFbqGGZ0GQFSvM0GKC7hQIZZQAB
SPF
When planning the deployment of Domain Rewrite Service we recommend the following regarding Sender Policy Framework (SPF) records:
Update your existing SPF record to include the On Demand Migration Domain Rewrite list of acceptable domains. This will prevent any hard failures when routing mail through the Rewrite Relay Service.
Include the following domains with your SPF record from all source and target domains participating in Domain Rewrite:
spf.odmad.quest-on-demand.com
spf.us.odmad.quest-on-demand.com
spf.ca.odmad.quest-on-demand.com
spf.eu.odmad.quest-on-demand.com
spf.uk.odmad.quest-on-demand.com
spf.au.odmad.quest-on-demand.com
DMARC
If your organization utilizes Domain-based Message Authentication, Reporting and Conformance (DMARC) to prevent email spoofing, then Domain Rewrite is DMARC ready.
There are no additional requirements to support DMARC with Domain Rewrite, however it is highly recommended that the following related topics be reviewed prior to execution.
DKIM
What is DKIM?
DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in emails, a technique often used in phishing and email spam. DKIM allows the receiver to check that an email claimed to have come from a specific domain was indeed authorized by the owner of that domain. Wikipedia
Why is DKIM required for Domain Rewrite (ERS)?
A DKIM or commonly known as an Email Signature, is required for Email Rewrite Services (ERS) to ensure Domain Alignment and Authenticity. Without the proper email signature, DMARC would fail if quarantine or reject are enabled. For more information about DMARC and ERS, see this article.
When is DKIM required for Domain Rewrite (ERS)?
When emails are rewritten by ERS, receiving servers must be able to validate and trust the authenticity of the sender. To do this ERS will sign each email with a DKIM signature. This signature contains a public and private key that must be compared using public DNS to verify ownership of the domain(s).
By default, all your accepted domains are eligible for a DKIM signature. If you wish to exclude a domain from ERS because you know it is not-in-use, then you may uncheck the domain to exclude it. Microsoft domains are automatically excluded.
When do I choose my DKIM domains for ERS?
During project setup of the ERS components.
The project wizard will walk you through the configurations of ERS. During this process you will be asked to choose which domains will require email signatures. It is recommended any accepted domain being used by any mail-enabled object within your tenant environments be published. If the accepted domain is not in use by anyone, then it is not required. If in doubt, enable it.
How do I publish my DKIM DNS records?
It’s simple if you have access to your public DNS. In most cases, even as IT administrators we may not have direct access to update public DNS. In those cases, you’ll need to submit a change control to publish DNS TXT records for all the accepted domains. And each record must contain the public key provided in the “Copy DNS Information” action in the project wizard.
On Demand Migration will present a unique public key associated with the domains. That key is to be published as a DNS TXT record for the selected domain. Here is an example of such a record.
Example TXT Record:
Name: selector1._domainkey.contoso.com
Type: TXT
Value: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUXA4GNADCBiQKBgQC0uekhrGKBUmlvPXcy2XxEBG 7Hn+64l505xl0vwk3cnHwWaVw1LTFcsFxUCf2tXpNE02ap5EhCCTjGGOyEJ/ZX1ScptyDP3 X/eJDn4jq5sQQruK3F9KdU9kLTmkALK+ySz+lpX40DLXWw2BauOEzpVD65XZUwiN5DJUc 37/RcozRwIDAQAB
The Project implementer will copy this information and provide it to the team that manages DNS for this domain. On Demand Migration will immediately begin monitoring DNS for this record. Once the DNS TXT record has been validated by On Demand Migration, the Project implementer may select the desired domains to complete the setup.
TLS/SSL
What is TLS?
Transport Layer Security (TLS), and its now-deprecated predecessor, Secure Sockets Layer, are cryptographic protocols designed to provide communications security over a computer network. Several versions of the protocols find widespread use in applications such as web browsing, email, instant messaging, and voice over IP. Wikipedia
Why is TLS required for Domain Rewrite (ERS)?
To ensure encrypted, secure mail routing, TLS is enforced for all connections.
To successfully implement the Domain Rewrite, a valid SSL certificate is required for all source and target tenants in scope for this service.
When the Email Rewrite Service is enabled for the first time, Connectors will be automatically created in Exchange Online to provide secure (TLS) email routing between the tenants and the Domain Rewrite relays.
When is TLS required for Domain Rewrite (ERS)?
It is always required. An SSL certificate is always required to ensure a secure connection between ERS and Exchange Online.
What is required to setup TLS for Domain Rewrite (ERS)?
Each tenant configured within the Domain Rewrite project will require 1 SSL certificate in the PFX format. The SSL certificate can only be uploaded to Domain Rewrite in the required PFX file format. PFX files contain the public key file (SSL Certificate file) and the associated private key file (password).
The requirements for the certificate are as follows (names are for example only):
- Common Name: contoso.com
- Cryptographic service provider: Microsoft RSA SChannel Cryptographic Provider
- Bit length: 2048 or higher
- Must be valid for Server Authentication and Client Authentication.
- Must be signed by a trusted public root CA.
- Must contain a private key (password).
- Must not expire before the end of the project.
- Must have a Friendly Name defined.
- No Wildcards Certificates
- No SAN (Subject Alternate Name) Certificates
- PFX file format with Password
- Paired with Email Signatures (DKIM) Domain
How do I upload the PFX certificate?
During project setup, the wizard will ask you to upload your pfx file and enter in the password.
When the SSL certificates are successfully uploaded and activated in On Demand Migration, an email notification will be sent to the project administrators. And, as with most Project settings, you can always return to the Dashboard to upload new certificates or make changes.
Rules, Connectors, and Groups
I’ve finished project setup for Domain Rewrite, what’s next?
After Domain Rewrite is configured in your project, each tenant will have a series of configurations automatically deployed through our orchestration engine. The following FAQs will help you get acquainted with the Domain Rewrite configuration components.
What is setup when I enable Domain Rewrite?
When Domain Rewrite is enabled, the following configuration items are created and managed. If Domain Rewrite is disabled, the same configurations will be removed.
- Exchange Online Transport Rules to redirect mail flow for Domain Rewrite eligible users
- Exchange Online Connectors to manage encrypted mail flow between Domain Rewrite and Exchange Online
- Mail-Enabled Groups to managed user’s eligibility for Domain Rewrite
All configurations can be reviewed for any tenant from the Exchange Online portal. You may also view all configurations using PowerShell.
How can I confirm everything was created?
You may verify the configurations from the Microsoft 365 admin portal or by using PowerShell.
To verify by portal, simply login to the Exchange Online Admin Portal. Then navigate to Mail Flow. Under Mail Flow you will find the rules and connectors. To view the groups, navigate to recipients then groups.
The simplest way is to use a PowerShell query to get a list of all rules, connectors and groups. Follow these easy steps to do just that.
- Launch PowerShell.
Connect to your tenant, if you don’t know how, here is a quick article from MS:
Once authenticated, run these example commands:
Get-TransportRule BT-* -ErrorAction SilentlyContinue | select @{Name='Identity'; Expression={'Rule: '+$_.Identity }}
Get-InboundConnector BT-* -ErrorAction SilentlyContinue | select @{Name='Identity'; Expression={'Inbound: '+$_.Identity }}
Get-OutboundConnector BT-* -ErrorAction SilentlyContinue |select @{Name='Identity'; Expression={'Outbound: '+$_.Identity }}
Get-DistributionGroup BT-* -ErrorAction SilentlyContinue | select @{Name='Identity'; Expression={'Group: '+$_.Identity }}
- Repeat these steps for each tenant.
How are Transport Rules & Send Connectors used?
Exchange Online transport rules and send connectors are the way in which mail is routed 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 Domain Rewrite and messages that do not are immediately sent to the recipients.
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 updates 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 are Connectors used?
Domain Rewrite adds an inbound and outbound connector to all Microsoft 365 tenants defined on a project. The purpose of these connectors is to ensure mail flow from an Microsoft 365 tenant to Domain Rewrite is encrypted with the assigned TLS/SSL certificate. This outbound connector contains the FQDN of the Domain Rewrite ERS Relay used to receive mail for the tenant. Some versions of ERS include connectors for each Client/Project combination.
- BT-IntegrationPro-In – inbound connector
- BT-IntegrationPro-Out – outbound connector
How are groups used?
When an Email Address Rewrite mode is selected for a user, the user is added to either the ERS Day One group (Rewrite with Target Address) or the ERS Day Two group (Rewrite with Source Address).
The ERS day One and day Two groups are cloud-only Exchange Online distribution groups. ERS Day One is used to control which (not migrated) source users should be presented to external recipients using their target address. ERS Day Two is used to control which (migrated) target users should be presented to external recipients with their source address. Some versions of ERS include groups for each Client/Project combination.
Administration Groups
Domain Rewrite automatically adds the following two (2) groups in the source tenant(s) of a project. These groups are managed by the administrator(s) of the tenant.
- BT-IntegrationPro-[DayOne/DayTwo] – day one or day two mailbox users. E.g. BT-IntegrationPro-DayOne.
Internal Groups
Domain Rewrite automatically adds several groups in the source and target tenant(s) for internal use. These groups should not be changed or deleted by administrators and are managed by Domain Rewrite.
Source Tenants – Domain Rewrite adds the following groups in the source tenant(s) of a project.
- BT-IntegrationPro-[DayOne/DayTwo]-[Guid] – target addresses (contacts) of day one or day two users in target tenant [Guid]. E.g. BT-IntegrationPro-DayOne-15d82781-e5e8-4691-a77f-0f5fb10b6482
Target Tenants – Domain Rewrite creates the following groups in the target tenant(s) of a proj
- BT-IntegrationPro-[DayOne/DayTwo] – source addresses (contacts) of day one or day two users from all source tenants. E.g. BT-IntegrationPro-DayOne.
- BT-IntegrationPro-[DayOne/DayTwo]-[Guid] – source addresses (contacts) of day one or day two users from source tenant [Guid]. E.g. BT-IntegrationPro-DayOne-15d82781-e5e8-4691-a77f-0f5fb10b6482.
- BT-IntegrationPro-NC-[Guid] – source addresses (contacts) of users from source tenant [Guid] that have not been cutover. E.g. BT-IntegrationPro-NC-15d82781-e5e8-4691-a77f-0f5fb10b6482.
How does Mail Flow work with Domain Rewrite?
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.
When the Quest 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 Quest Rewrite Service signs 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 create 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, it is securely redirected to the Quest Rewrite Service using the Outbound Connector in the Target Tenant
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 Rewrite Service enabled), the message will be bifurcated and:
Copy of the message sent to external recipient (recipients in the source tenant with Rewrite Service enabled) 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 target tenant with unchanged addresses.
When the Quest 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 Quest Rewrite Service signs 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, it is securely redirected to the Quest Rewrite Service using the Outbound Connector in the Target Tenant
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 Quest 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 Quest 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 Quest Rewrite Service signs 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 create 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, it is securely redirected to the Quest Rewrite Service using the Outbound Connector in the Source Tenant
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 Rewrite Service enabled), the message will be bifurcated and:
Copy of the message sent to external recipient (recipients in the target tenant with Rewrite Service enabled) 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.
When the Quest 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 Quest Rewrite Service signs 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
When is it safe to remove Domain Rewrite ERS configurations?
You may disable Domain Rewrite when production services are no longer required. Upon disabling, the related configurations will automatically be removed.