Multi-Tenancy Configuration

On this page, we explain how to configure your xorlab platform to protect the domains of multiple tenants. It includes step-by-step instructions on how to add new tenants, configure various topologies, and ensure proper routing.

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: XSP sits between the front MTA and the internal mailbox server. Emails between tenants take a shorter route within XSP, bypassing external systems. Ideal for setups with multiple tenants.
Microsoft 365: Connectors route emails from M365 to XSP for analysis. Non-quarantined emails are returned via connectors to M365, which is responsible for final delivery.
Star: A central gateway (typically the front MTA) manages all email traffic, with emails passing through the gateway twice—first for analysis, then for final delivery.
Front MTA: XSP functions as the front MTA, analyzing incoming messages and routing them to tenants. Outgoing tenant emails are processed by XSP before final delivery.
Full Chain: XSP sits between the front MTA and the internal mailbox server. Emails between tenants go through XSP to the front MTA, following standard email routing.

For all topologies, whenever you add a new tenant in guarded_tenants.yml and publish the changes, xorlab will add a unique uid to that tenant. The uid does not need to be set by hand, and it will be left out in config examples below.

Default Chain Topology

Guarded Tenants

Expand to read the instructions.

name: Define the name of the tenant. Also visible in the GUI.bccFallbackDomain: Set this attribute to the primary domain of the tenant.domains: Specify the guarded domains of the tenant including the bccFallbackDomain.tenantSelector: Reference the headerName and headerValue of a header that will be used to identify the tenant.

Expert Editor: /activeguard/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
    authenticationBackend: usernamePassword
    bccFallbackDomain: tenantA.com
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    authenticationBackend: SamlAD
    bccFallbackDomain: tenantB.com
    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 tenant 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.

Expert Editor: /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 XSP.
Use the permit command to allow these connections to access XSP and forward emails.

Expert Editor: 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 XSP
<ip-address1>   permit
<ip-address2>   permit

Client Access Tenant

Expand to read the instructions.

This file defines which headers XSP 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 XSP
Add /32 to restrict to a single IP address.
The <headerName> and <headerValue> refers to the tenantSelector or the tenantSelectors.
The file should always end with an 0.0.0.0/0 entry to prevent header spoofing.

Expert Editor: /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

M365 Topology

Guarded Tenants

Expand to read the instructions.

Recommendation: List every 'Accepted Domain' as tenantSelector.

Go to admin.cloud.microsoft/exchange#/accepteddomains
For each domain listed, define a seperate 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.

Expert Editor: /activeguard/shared/guarded_tenants.yml

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

  - name: tenantB
    bccFallbackDomain: tenantB.com
    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.

Expert Editor: /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

Star Topology

Guarded Tenants

Expand to read the instructions.

name: Define the name of the tenant. Also visible in the GUI.bccFallbackDomain: Set this attribute to the primary domain of the tenant.domains: Specify the guarded domains of the tenant including the bccFallbackDomain.tenantSelector: Identifies the header that will be set when the email is coming from the trusted infrastructure.

Expert Editor: /activeguard/shared/guarded_tenants.yml

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

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

  - name: tenantB
    bccFallbackDomain: tenantB.com
    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.

Expert Editor: /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 XSP and forward emails.

Expert Editor: 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

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.

Expert Editor: /activeguard/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
    bccFallbackDomain: tenantA.com
    domains:
      - tenantA.com
      - tenantA.ch

  - name: tenantB
    bccFallbackDomain: tenantB.com
    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 XSP and forward emails.

Expert Editor: 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 XSP 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.

Expert Editor: /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 tenant domain, specifying the correct next-hop destination.
Use the smtp command to specify the SMTP endpoint (e.g., the front MTA).

Expert Editor: /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>

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.

bccFallbackDomain: Set this attribute to the primary domain of the tenant.domains: Specify the guarded domains of the tenant including the bccFallbackDomain.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 XSP.

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

Expert Editor: /activeguard/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
    bccFallbackDomain: tenantA.com
    domains:
      - tenantA.com
      - tenantA.de

  - name: tenantB
    bccFallbackDomain: tenantB.com
    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.

Expert Editor: /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 XSP.
Use the permit command to allow these connections to access XSP and forward emails.

Expert Editor: 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 XSP
<ip-address1>   permit
<ip-address2>   permit

Client Access Tenant

Expand to read the instructions.

This file defines which headers XSP 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> refers to the tenantSelector or the tenantSelectors.
The file should always end with an 0.0.0.0/0 entry to prevent header spoofing.

Expert Editor: /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

Tenant Selector

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.

Expert Editor: /activeguard/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
    bccFallbackDomain: tenantA.com
    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
    bccFallbackDomain: tenantB.com
    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
    bccFallbackDomain: tenantC.com
    domains:
      - tenantC.com

  - name: tenantD
    bccFallbackDomain: tenantD.com
    domains:
      - tenantD.com

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 UI.

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 itsef (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.

Config Sets

configSets allow you to define some configuration that can be re-used for multiple tenants. A config set supports the following parameters. All those parameters can also be set directly on a tenant.

configSets:
  default:
    interTenantMessageSplitting: true
    tenantSelector: {}
    tenantSelectors: []
    autoLoginLink: {}
    quarantine: {}
    dataRetention: {}
    emailTemplateStyle: default
    #authenticationBackend: # empty by default

Checkout the guarded_tenants.yml for more attribute-specific documentation.

You can overwrite single parameters of the default set without having to specify all other parameters.

You can create new config sets and reference them in some tenants. The default set is always applied to all tenants with the least precedence.

configSets:
  allowPhishingRequest:
    quarantine:
      quarantines:
          - name: Phishing
            canRelease: true

tenants:
    name: xorlab
    ## Applied config sets, notice that later occurrences will override earlier config set occurrences.
    ## Further, the "default" set is implicitly referenced with least precedence.
    configSets:
        - allowPhishingRequest

​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

​Tenant Selector

​Tenant Selection Logic

​Config Sets

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

Tenant Selector

Tenant Selection Logic

Config Sets