Configure Tenant Domains and Routing

The configuration is different depending on the topology. Choose the one below that fits your setup best.

Deployment Topologies

The xorlab Security Platform supports several deployment options. If you’re unsure which to choose, we recommend starting with the Default Chain.

Default Chain: xorlab is located between your gateway and the internal mailbox server like Exchange.
Microsoft 365: xorlab is integrated directly with M365 via connectors.
Star: A central gateway integrates xorlab in a Star layout.
Front MTA: xorlab is the gateway (front MTA) and receives emails directly from the internet.
Full Chain: Same as Default Chain, but inter-tenant emails pass twice through xorlab.

Default Chain Topology

Guarded Tenants

Expand to read the instructions.

name: Define the name of the tenant. Also visible in the web interface.domains: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.tenantSelector: Reference the headerName and headerValue of a header that will be used to identify the tenant.

/shared/guarded_tenants.yml

# Config example for Default Chain Topology

## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant.
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"

### Begin Tenant Config
tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    domains:
      - tenantB.com
      - tenant-B.net

Transport Map

Expand to read the instructions.

The transport map is used to ensure that incoming emails are delivered to the appropriate next-hop destination (such as the front MTA) based on the recipient’s domain.

Define a rule for each guarded domain, specifying the correct next-hop destination.
Use the smtp command to specify the SMTP endpoint (e.g., the front MTA).
The last line should be a default route to handle outgoing email traffic.

/activeguard/mta/startup_cfg/postfix_custom/transport

# Route incoming emails to the SMTP endpoints of each tenant domains
tenantA.ch      smtp:<inbound-next-hop>
tenantA.com     smtp:<inbound-next-hop>
tenantB.com     smtp:<inbound-next-hop>
tenantB.net     smtp:<inbound-next-hop>

# Define a default route for all outgoing emails
*               smtp:<outbound-next-hop>

Client Access

Expand to read the instructions.

Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

Specify the IP address of the SMTP client, typically the Front MTA or Exchange Server, responsible for routing emails to xorlab.
Use the permit command to allow these connections to access xorlab and forward emails.

/activeguard/mta/startup_cfg/postfix_custom/client_access

## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each front MTA that receives emails and forward them to xorlab
<ip-address1>   permit
<ip-address2>   permit

Client Access Tenant

Expand to read the instructions.

This file defines which headers xorlab should add to incoming and outgoing emails.

Structure: <CIDRblock> PREPEND <headerName>: <headerValue>
The <CIDRblock> specifies the IP range of the SMTP client responsible for routing emails to xorlab
Add /32 to restrict to a single IP address.
The <headerName> and <headerValue> refer to the tenantSelector or the tenantSelectors.
The file should always end with an 0.0.0.0/0 entry to prevent header spoofing.

/activeguard/mta/startup_cfg/postfix_custom/client_access_tenant

# Allow-list specific SMTP clients for Multi-tenant deployments

198.51.100.1/32       PREPEND x-xor-trusted-client: trusted
192.0.2.1/32          PREPEND x-xor-trusted-client: trusted
203.0.113.1/32        PREPEND x-xor-trusted-client: trusted

# Always include a 0.0.0.0/0 entry in the end of this file to sanitize the headerValue
0.0.0.0/0             PREPEND x-xor-trusted-client: unknown

When you finish editing the files above, click Publish. The new configuration becomes active within about one minute.

M365 Topology

Guarded Tenants

Expand to read the instructions.

domains: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.tenantSelectors: Refer to the x-originatororg header of each accepted domain in your Microsoft Exchange environment.

Recommendation: List every 'Accepted Domain' as tenantSelector.

Go to admin.cloud.microsoft/exchange#/accepteddomains
For each domain listed, define a separate selector in guarded_tenants.yml
Use the following format for each selector:
- HeaderName: "x-originatororg"
- Header value: The domain listed in the “Accepted Domain” column, between double quotation marks.

/shared/guarded_tenants.yml

tenants:
  - name: tenantA
    domains:
     - tenantA.com
     - tenantA.ch
    tenantSelectors:
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenanta.com"
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenantaaa.onmicrosoft.com"

  - name: tenantB
    domains:
      - tenantB.com
      - tenantB.net
    tenantSelectors:
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenantb.com"
      - selector:
        - headerName:  "x-originatororg"
          headerValue: "tenantbbb.onmicrosoft.com"

Header Checks

Expand to read the instructions.

This config file contains the routing rules of your mail flow. It refers to the headers specified for each tenant in the previous step.

x-originatororg should correspond to the headerName of the tenantSelectors defined in guarded_tenants.
tenantA.com and tenantB.com should correspond to the headerValue of the tenantSelectors defined in guarded_tenants.
tenant a/b -com.mail.protection.outlook.com should correspond to the SMTP endpoint (MX server) of the headerValue of the tenantSelectors defined in guarded_tenants.

/activeguard/mta/startup_cfg/postfix_custom/header_checks_core

# Header-based routing
# Define mail routes as specified in the shared/guarded_tenants.yml 

/^x-originatororg: tenantA.com/                 FILTER smtp:tenanta-com.mail.protection.outlook.com
/^x-originatororg: tenantaaa.onmicrosoft.com/   FILTER smtp:tenantaaa.mail.protection.outlook.com
/^x-originatororg: tenantB.com/                 FILTER smtp:tenantb-com.mail.protection.outlook.com
/^x-originatororg: tenantbbb.onmicrosoft.com    FILTER smtp:tenantbbb-com.mail.protection.outlook.com

When you finish editing the files above, click Publish. The new configuration becomes active within about one minute.

Star Topology

Guarded Tenants

Expand to read the instructions.

name: Define the name of the tenant. Also visible in the web interface.domains: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.tenantSelector: Identifies the header that will be set when the email is coming from the trusted infrastructure.

/shared/guarded_tenants.yml

configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"

tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    domains:
      - tenantB.com
      - tenantB.net

Transport Rules

Expand to read the instructions.

The transport rules for a multi-tenancy star integration only require one route that redirects all traffic to the central email gateway.

The * wildcard matches all traffic.
<email-next-hop> should contain the domain of the central email gateway.

/activeguard/mta/startup_cfg/postfix_custom/transport

# Make sure a default route is defined.
*               smtp:<email-next-hop>

Client Access

Expand to read the instructions.

Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

Specify the IP address of central gateway that will send emails to xorlab.
Use the permit command to allow these connections to access xorlab and forward emails.

activeguard/mta/startup_cfg/postfix_custom/client_access

## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each front MTA that will send emails to xorlab
<ip-address1>   permit
<ip-address2>   permit

When you finish editing the files above, click Publish. The new configuration becomes active within about one minute.

Front MTA Topology

Guarded Tenants

Expand to read the instructions.

The headers referenced in tenantSelector need to match the entries in the client_access_tenant configuration.

/shared/guarded_tenants.yml

## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant.
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"


tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    domains:
      - tenantB.com
      - tenant-B.net

Client Access

Expand to read the instructions.

Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

Specify the IP address of the allowed SMTP client, typically the Exchange server.
Use the permit command to allow these connections to access xorlab and forward emails.

/activeguard/mta/startup_cfg/postfix_custom/client_access

## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each server that will send emails to xorlab
<ip-address1>   permit
<ip-address2>   permit

Client Access Tenant

Expand to read the instructions.

This file defines which headers xorlab should add to incoming and outgoing emails.

Structure: <CIDRblock> PREPEND <headerName>: <headerValue>
The <CIDRblock> specifies the IP range of each tenant’s mail server
Add /32 to restrict to a single IP address.
The <headerName> and <headerValue> refer to the tenantSelector or the tenantSelectors.
The file should always end with an 0.0.0.0/0 entry to prevent header spoofing.

/activeguard/mta/startup_cfg/postfix_custom/client_access_tenant

# Allow-list specific SMTP clients for Multi-tenant deployments

198.51.100.1/32       PREPEND x-xor-trusted-client: trusted
192.0.2.1/32          PREPEND x-xor-trusted-client: trusted
203.0.113.1/32        PREPEND x-xor-trusted-client: trusted

# Always include a 0.0.0.0/0 entry in the end of this file to sanitize the headerValue
0.0.0.0/0             PREPEND x-xor-trusted-client: unknown

Transport Map

Expand to read the instructions.

The transport map is used to ensure that incoming emails are delivered to the appropriate next-hop destination (such as the front MTA) based on the recipient’s domain.

Define a rule for each guarded domain, specifying the correct next-hop destination.
Use the smtp command to specify the SMTP endpoint (e.g., the front MTA).

/activeguard/mta/startup_cfg/postfix_custom/transport

# Route incoming emails to the SMTP endpoints of each tenant domains
tenantA.ch      smtp:<inbound-next-hop>
tenantA.com     smtp:<inbound-next-hop>
tenantB.com     smtp:<inbound-next-hop>
tenantB.net     smtp:<inbound-next-hop>

When you finish editing the files above, click Publish. The new configuration becomes active within about one minute.

Full Chain Topology

In the Full Chain Topology xorlab sits between a front MTA and the Exchange server. The difference to the default chain is that inter-tenant emails are routed to the front MTA and back. Important: the front MTA needs to strip away all x-xor-trusted-client headers from all emails to ensure proper routing.

Guarded Tenants

Expand to read the instructions.

domains: Specify the guarded domains of the tenant. Ensure the primary domain is listed first.tenantSelector: If needed, reference a unique trusted headerName and headerValue for specific tenants.interTenantMessageSplitting: Controls whether xorlab splits emails sent between tenants into separate incoming and outgoing messages. By default, this attribute is set to true but for the Full Chain Topology you are required to set it to false.configSets - tenantSelector: Reference the headerName and headerValue of a header that will be added by xorlab.

The headers referenced in tenantSelector and tenantSelectors need to match the entries in the client_access_tenant configuration.

/shared/guarded_tenants.yml

## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant
configSets:
  default:
    # This is required when inter-tenant emails are passing through xorlab twice
    interTenantMessageSplitting: false
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trusted"

tenants:
  - name: tenantA
    domains:
      - tenantA.com
      - tenantA.de

  - name: tenantB
    domains:
      - tenantB.com
      - tenantB.net
        

Header Checks

Expand to read the instructions.

This config file defines how messages are routed based on the headers assigned in guarded_tenants.yml.

Structure: /^<headerName>:<headerValue>/ FILTER smtp:[<SMTP endpoint>]
The <SMTP endpoint> should include the domain of either the frontMta or the guarded domain’s mail server.

/activeguard/mta/startup_cfg/postfix_custom/header_checks_core

# Header-based routing

/^x-xor-trusted-client: unknown/   FILTER smtp:<inbound-next-hop>
/^x-xor-trusted-client: trusted/   FILTER smtp:<outbound-next-hop>

Client Access

Expand to read the instructions.

Client access rules are used to ensure that incoming emails are correctly routed based on the IP addresses of the front MTA or other mail transfer systems.

Specify the IP address of the SMTP client, typically the Front MTA or Exchange Server, responsible for routing emails to xorlab.
Use the permit command to allow these connections to access xorlab and forward emails.

/activeguard/mta/startup_cfg/postfix_custom/client_access

## You can add one line per IP or specify ranges. Only the CIDR ranges 24, 16, and 8 are supported by using the following format:
# 1.2.3.4   permit
# 1.2.3     permit
# 1.2       permit
# 1         permit

## Add the IP address of each front MTA that receives emails and forward them to xorlab
<ip-address1>   permit
<ip-address2>   permit

Client Access Tenant

Expand to read the instructions.

This file defines which headers xorlab should add to incoming and outgoing emails.

Structure: <CIDRblock> PREPEND <headerName>: <headerValue>
The <CIDRblock> specifies the IP range of the Exchange Server.
Add /32 to restrict to a single IP address.
The <headerName> and <headerValue> refer to the tenantSelector or the tenantSelectors.
The file should always end with an 0.0.0.0/0 entry to prevent header spoofing.

/activeguard/mta/startup_cfg/postfix_custom/client_access_tenant

# Set the Exchange servers as trusted. Do not add the front MTA as trusted.
198.51.100.1/32       PREPEND x-xor-trusted-client: trusted
192.0.2.1/32          PREPEND x-xor-trusted-client: trusted

# Always include a 0.0.0.0/0 entry in the end of this file to prevent spoofing of the headerValue
0.0.0.0/0             PREPEND x-xor-trusted-client: unknown

When you finish editing the files above, click Publish. The new configuration becomes active within about one minute.

How to define tenant selectors

Tenant selectors are used to assign emails to the correct tenant by evaluating specific mail headers. There are two configuration options:

tenantSelector: Defines a single set of headers that must all match to assign the message to a tenant (AND logic).
tenantSelectors: One property that enables you to define more then one selector. A selector can reference one or more header sets. If multiple header sets are referenced, all need to match (AND-logic). The message matches a tenant if at least one Selector matches (OR logic).

Both options can be used for a specific tenant, as well as default within configSets.

Avoid External Header ManipulationOnly use sanitized and trusted mail headers for tenant identification. Never rely on headers that could be set or modified by external senders.

/shared/guarded_tenants.yml

## The 'default' config set is implicitly referenced by each tenant unless overwritten by a tenant.
## In this example, it applies to tenant C and D.
configSets:
  default:
    tenantSelector: 
    - headerName:  "x-xor-trusted-client"
      headerValue: "trustedMailRoute"

tenants:
  - name: tenantA
    domains:
      - tenantA.com
      # Assigned to tenantA only if both headers match (AND logic)
    tenantSelector:
      - headerName:  "x-xor-trusted-client"
        headerValue: "specialRoute"
      - headerName:  "another-trusted-header"
        headerValue: "i-know-this-is-tenantA"

  - name: tenantB
    domains:
      - tenantB.com
    
    # Assigned to tenantB if either of these selectors match (OR logic between selectors)
    tenantSelectors:
      - selector:
        - headerName:  "x-xor-trusted-client"
          headerValue: "specialRoute2"
      - selector:
        - headerName:  "x-xor-trusted-client"
          headerValue: "specialRoute3_part1"
        - headerName:  "another-trusted-header"
          headerValue: "specialRoute3_part2"

  - name: tenantC
    domains:
      - tenantC.com

  - name: tenantD
    domains:
      - tenantD.com

After updating shared/guarded_tenants.yml, click Publish. The new configuration becomes active within about one minute.

Explanation of tenant selection logic

When processing an email, the system determines which Tenant it belongs to based on the following rules. Step 1: Single Match: If exactly one Tenant Selector matches the email, the email is assigned to that Tenant. Step 2: No Match: If no Tenant Selector matches the email, choose the Tenant based on the recipient addresses. If no Tenant can be identified, assign the email to the special UNKNOWN Tenant. Step 3: Multiple Matches: If multiple Tenant Selectors match, the selection is resolved using the logic below in the specified order.

Assign Tenant based on sender address.
1. Prefer a match on the sender’s envelope-from address.
2. If no match, check the header-from address.
Assign Tenant based on recipient addresses. Choose only from the matched Tenant Selectors.
If no Tenant can be identified, assign the email to the special UNKNOWN Tenant.

Recipient address matchingFor step 2 and 3: If the Tenant is chosen based on the recipients, and the recipients belong to different Tenants, the email is split for each Tenant. Each split email is assigned a separate GGRID and will be shown as separate email in the web interface.

After the tenant is selected, the email is processed. Because the email can have multiple different recipients, even from different tenants, xorlab applies the following logic when delivering emails:

For all recipients of the email that do not match any tenants (outgoing email) or match the tenant of the email itself (internal or incoming email), deliver the email.
For all recipients of the email that match a different tenant than the one of the email itself (inter-tenant email):
- If interTenantMessageSplitting is active, re-process the email again with a separate GGRID and assigned to the recipient tenant. No email delivery at this point.
- Else deliver the email. We expect the email to pass again through xorlab.

​Deployment Topologies

​Default Chain Topology

​Guarded Tenants

​Transport Map

​Client Access

​Client Access Tenant

​M365 Topology

​Guarded Tenants

​Header Checks

​Star Topology

​Guarded Tenants

​Transport Rules

​Client Access

​Front MTA Topology

​Guarded Tenants

​Client Access

​Client Access Tenant

​Transport Map

​Full Chain Topology

​Guarded Tenants

​Header Checks

​Client Access

​Client Access Tenant

​How to define tenant selectors

​Explanation of tenant selection logic

Deployment Topologies

Default Chain Topology

Guarded Tenants

Transport Map

Client Access

Client Access Tenant

M365 Topology

Guarded Tenants

Header Checks

Star Topology

Guarded Tenants

Transport Rules

Client Access

Front MTA Topology

Guarded Tenants

Client Access

Client Access Tenant

Transport Map

Full Chain Topology

Guarded Tenants

Header Checks

Client Access

Client Access Tenant

How to define tenant selectors

Explanation of tenant selection logic