Match Email Domain

The Match Email Domain (matchEmailDomain) access rule acts as a corporate identity gate. It restricts operations based on the domain suffix of the authenticated user’s email address (e.g., @acme.com or *.acme.com).

This rule is ideal for internal company APIs, partner portals, and enterprise SaaS features that should be accessible only to employees or designated partner organizations.

---

1. How It Works

• Semantic Email Detection: The engine automatically locates the field tagged with the Email semantic module in your session configuration.
• Domain Parsing & Normalization: Splits the authenticated user’s email address at @, normalizes the domain to lowercase, and compares it against your configured domain patterns.
• Inclusion & Negative Exclusion Patterns: Supports broad positive domain patterns (such as *.acme.com) alongside explicit exclusions prefixed with an exclamation mark (such as !contractors.acme.com).
• Deny-First Evaluation: If an email matches an exclusion pattern, access is immediately blocked, even if it would have otherwise matched a broader wildcard pattern.
• Email Verification Enforcement: By default, verifies that the user’s email address has been confirmed before granting access.
• Zero Database Overhead: Evaluates purely in-memory during the PRE_FETCH phase before any database queries execute.

Property	Specification
Rule Type	matchEmailDomain
Supported Strategies	All strategies (RBAC, OrganizationRBAC, EnterpriseRBAC)
Allowed Placement Levels	Global API Model Level (api), Exposed Entity Level (exposure), Action Level (action)
Execution Phase	PRE_FETCH across all action kinds (list, read, create, update, delete, link, unlink)

---

2. Prerequisites in the Data Domain & Session Configuration

To use Match Email Domain, your model must meet the following requirements:

1. Email Semantic Module: An email property on your User entity must be tagged with the Email semantic module.
2. Session Definition Properties: In the API Modeler’s Session Configuration tab, the email property must be included in Session Definition Properties.
3. Verification Compatibility: If requireVerified is set to true (the default), the Email semantic configuration in your Data Domain must not have requireVerification: false.

---

3. Configuration Options, Wildcards & Exclusions

When configuring Match Email Domain, you define:

1. Domain Patterns (domains)

A list of allowed domain strings, wildcard patterns, and negative exclusion patterns:

Domain Pattern	Matches	Does NOT Match	Description
acme.com	alice@acme.com ALICE@ACME.COM	alice@sub.acme.com alice@other.com	Exact domain match (case-insensitive)
*.acme.com	alice@acme.com bob@eng.acme.com carol@dev.eng.acme.com	alice@notacme.com alice@acme.org	Wildcard match (matches the main domain and all subdomains)
!contractors.acme.com	(Exclusion)	dave@contractors.acme.com	Explicit exclusion (blocks this specific subdomain even if permitted by *.acme.com)

Wildcard Matching Rule

The *. prefix matches both the apex domain (acme.com) and any subdomain (sub.acme.com). Trailing wildcards (e.g. acme.*) are not supported.

Negative Domain Matching (Exclusion Patterns)

In large organizations, corporate email addresses often span multiple departments and subdomains (like eng.acme.com or sales.acme.com). However, companies routinely provision dedicated subdomains for temporary personnel, vendors, or test accounts (such as contractors.acme.com or guests.acme.com).

Instead of having to manually list dozens of individual department subdomains, you can combine a broad wildcard with negative exclusions using the ! prefix:

[
  "*.corp.example.com",
  "!contractors.corp.example.com",
  "!guests.corp.example.com"
]

How Exclusions Are Evaluated (Deny-First)

The evaluation always follows a strict deny-first security rule, regardless of the order in which patterns appear in the list:

1. Check Exclusions: If the caller’s email domain matches any exclusion pattern (prefixed with !), access is immediately denied (403 Forbidden).
2. Check Inclusions: If the domain is not excluded, the system checks whether it matches at least one allowed domain or wildcard pattern. If it matches, access is allowed.
3. Default: Any email domain that does not match an allowed pattern is denied (403 Forbidden).

Validation Rules for Domain Exclusions

• At Least One Allowed Domain Required: A rule cannot consist only of exclusions (such as ['!contractors.example.com']). You must provide at least one allowed domain (such as *.example.com) alongside your exclusions.
• Exact Domains for Exclusions: Exclusion patterns match exact domain names. Wildcards in exclusions (such as !*.example.com) are not permitted. If you want to block a specific subdomain, specify its exact name (e.g. !contractors.example.com).
• Clean Formatting: Do not include @ symbols (write !contractors.com, not !@contractors.com) or web protocols (such as https://).

2. Require Verified Email (requireVerified)

• true (Default): Requires that the user’s email address is marked as verified. Unverified accounts are denied access.
• false: Permits access even if the user has not yet completed email verification.

---

4. Recommended Modeling Patterns

Pattern 1: Corporate Access with Contractor Exclusion

To secure an internal workspace for employees while automatically locking out contractor and guest accounts:

graph TD
    User["Authenticated User Email"] --> Rule{"Match Email Domain"}
    Rule -->|"jane@contractors.corp.com"| Exclude["Matches !contractors.corp.com: Denied (403)"]
    Rule -->|"john@eng.corp.com"| Include["Matches *.corp.com: Allowed (200 OK)"]
    Rule -->|"guest@gmail.com"| Default["No match: Denied (403)"]

• Configuration: domains: ['*.corp.example.com', '!contractors.corp.example.com', '!guests.corp.example.com']
• An engineer (john@eng.corp.example.com) is granted access.
• A contractor (jane@contractors.corp.example.com) is blocked with 403 Forbidden.

---

Pattern 2: Partner Portal Partitioning

Expose partner-specific endpoints (such as beta integrations or partner webhooks) only to verified partner domains:

• On PartnerIntegration Entity:
  • Scenario: [Allow Authenticated, Match Email Domain: ['partner-alpha.com', '*.partner-beta.io']]
• Any standard user with @gmail.com or @competitor.com will receive a 403 Forbidden when attempting to access partner resources.

---

Pattern 3: Internal Platform Staff Override

Combine Match Email Domain with standard tenant access in separate scenarios to allow internal platform engineers to view system metrics across customer tenants:

InternalMetric.list Scenarios:
├── Scenario 1 (Internal Platform Staff):
│   └── Match Email Domain: ['platform.dev']         <- Internal engineers can view all telemetry
└── Scenario 2 (Tenant Customer Admin):
    └── Match Organization Role: ['admin', 'owner']   <- Customer admins can only view their own org

---

5. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint requires Match Email Domain	401 Unauthorized
Allowed Domain + Verified	Email matches an allowed domain and is verified	200 OK / 201 Created
Excluded Domain	Email matches a negative exclusion pattern (e.g. !contractors.acme.com)	403 Forbidden
Unverified Email	Email matches domain, but user has not verified their email (requireVerified: true)	403 Forbidden
Unrecognized Domain	Email domain does not match any allowed pattern	403 Forbidden
Missing Email in Session	Email semantic was not included in Session Definition Properties	500 Internal Server Error

---

Next Steps

• Match User Property: Generic attribute matching for departments, regions, or tiers.
• Email Semantic Module: Data modeling reference for email validation and verification.
• Session Configuration Guide: How to configure session definition properties in the API Modeler.