Tenant Isolation

Identify tenants and define tenant-aware policy, quotas, routing, residency, and dedicated-pool behavior.

Always confirm availability in the release bundle selected for deployment.

At a glance

Property	Value
Pipeline phase	Router
Category	Routing
Canonical minimum tier	Business
Canonical entitlement	Yes
Supported deployment contract	Yes
Release status	Catalog component; confirm a bundle that executes router-phase components.

Release accuracy

• Current documentation: Catalog component; confirm a bundle that executes router-phase components.

Where any detail below conflicts with the release status above, the release status is authoritative. Field names and examples describe the current dashboard and CRD surface; always confirm behavior against the selected release bundle before relying on it operationally.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Unverified performance figures

These figures are illustrative only. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Reported figure
P50	0.10ms
P95	0.28ms
P99	0.55ms

Note: Identity lookup and local policy evaluation are in-memory. Enterprise routing, residency checks, and quotas add modest overhead but remain sub-millisecond on typical configs.

Overview

The Tenant Isolation step establishes a hard tenant boundary before MongoDB ever sees the request. Nexo identifies the tenant, verifies that the request belongs to that tenant, enforces per-tenant quotas and policy lists, and can then route the request to a tenant-specific backend or region.

The feature is intentionally tiered:

• Free: field-path or header extraction, fail-closed handling for missing tenant context, and basic violation logging.
• Pro: JWT/connection-metadata extraction, audit-or-block cross-tenant detection, per-tenant quotas, allow/deny controls, and tenant-level audit evidence.
• Enterprise: premium routing rules, region-aware data residency, dedicated pools per tenant, real-time breach alerting, and the foundations needed for tenant chargeback and performance isolation.

Use it when you operate a shared MongoDB proxy tier for many customers and need stronger guarantees than application code alone can provide.

When to use

• Enforcing a single tenant context on every query before it reaches MongoDB
• Giving premium tenants dedicated backends, regions, or warm connection pools
• Protecting shared proxy capacity with per-tenant request and connection quotas
• Blocking or auditing cross-tenant access attempts for compliance programs
• Keeping tenant traffic inside approved regions for sovereignty or residency requirements

How it works

1. Identification: the proxy extracts tenant identity from a field path, request header, JWT claim, or connection metadata.
2. Admission control: unidentified requests are rejected, warned, or routed to a default backend based on policy. Allowlist/denylist checks run before forwarding.
3. Isolation enforcement: Pro cross-tenant inspection can run in strict mode (hard block) or audit mode (log and continue). Per-tenant quotas throttle noisy tenants before they affect neighbors.
4. Routing & placement: Enterprise rules map tenant ids or patterns to backend targets, regions, and dedicated pools so premium or regulated tenants can be isolated from the shared fleet.
5. Breach handling: violations are logged, optionally emitted to an audit trail, and can trigger enterprise alerting hooks for real-time response.

Configuration

“Not specified” means required semantics were not declared for that field.

Field	Type	Default	Required	Description
identificationStrategy	select	header	Yes	How the tenant is identified: field, header, jwt, or connection
fieldPath	string	tenantId	No	MongoDB field path used when identificationStrategy is field
headerName	string	X-Tenant-ID	No	HTTP or proxy header used when identificationStrategy is header
jwtClaimPath	string	claims.tenant_id	No	Dot-path into verified JWT/OIDC claims when identificationStrategy is jwt
connectionMetadataKey	string	auth.user	No	Connection metadata key used when identificationStrategy is connection
unidentifiedRequestBehavior	select	reject	No	What to do when tenant context is missing: reject, allow_warning, or route_default
rejectUnidentified	bool	true	No	Boolean fail-closed switch for environments that always reject missing tenant context
logViolations	bool	true	No	Emit isolation violations to logs / audit pipelines
crossTenantBlocking	select	strict	No	Cross-tenant enforcement mode: strict, audit, or disabled
perTenantRateLimit	object	{"requestsPerSecond":250,"maxConnections":100}	No	{ requestsPerSecond, maxConnections } tenant quota object (Pro)
allowlist	string[]	—	No	Explicit list of tenant ids or patterns allowed to execute through the proxy (Pro)
denylist	string[]	—	No	Tenant ids or patterns denied immediately (Pro)
tenantRouting	object[]	—	No	Array of { tenantId, target } mappings for enterprise tenant-aware routing
defaultTarget	string	—	No	Fallback backend used when unidentifiedRequestBehavior is route_default
dedicatedPools	object	{"enabled":false,"poolSize":25}	No	{ enabled, poolSize } to reserve warm connections per tenant (Enterprise)
dataResidency	object[]	—	No	Array of { tenantPattern, allowedRegions[] } rules for residency enforcement (Enterprise)
breachAlerting	object	—	No	{ enabled, webhookUrl } real-time isolation alerting configuration (Enterprise)

Settings reference

No additional settings reference is documented for this component.

Examples

Free tier: header-based fail-closed isolation

router:
  name: builtin:tenant-isolation
  config:
    identificationStrategy: header
    headerName: X-Tenant-ID
    unidentifiedRequestBehavior: reject
    rejectUnidentified: true
    logViolations: true

Pro tier: JWT-based isolation with quotas and audit-only cross-tenant detection

router:
  name: builtin:tenant-isolation
  config:
    identificationStrategy: jwt
    jwtClaimPath: claims.tenant_id
    crossTenantBlocking: audit
    perTenantRateLimit:
      requestsPerSecond: 500
      maxConnections: 150
    allowlist: [acme, globex, premium-*]
    denylist: [suspended-*]
    logViolations: true

Enterprise tier: premium routing, residency, dedicated pools, and alerts

router:
  name: builtin:tenant-isolation
  config:
    identificationStrategy: connection
    connectionMetadataKey: auth.user
    unidentifiedRequestBehavior: route_default
    defaultTarget: shared-mongo.internal:27017
    tenantRouting:
      - tenantId: acme-enterprise
        target: mongo-acme-us.internal:27017
      - tenantId: globex-eu
        target: mongo-globex-eu.internal:27017
    dedicatedPools:
      enabled: true
      poolSize: 40
    dataResidency:
      - tenantPattern: globex-*
        allowedRegions: [westeurope, northeurope]
    breachAlerting:
      enabled: true
      webhookUrl: https://hooks.example.net/tenant-isolation

Best practices

• Fail closed (unidentifiedRequestBehavior: reject) unless you have a well-defined shared fallback backend.
• Prefer header or JWT extraction for deterministic identity; use field-path extraction only when tenant identity truly lives inside the query payload.
• Use audit mode first for cross-tenant detection to learn your workload, then switch to strict mode once false positives are understood.
• Pair dedicated pools with per-tenant quotas so premium isolation does not become an unbounded cost center.
• Treat denylist, residency, and breach alerting rules as part of your compliance change-management process.

Limitations

• Field-path extraction depends on tenant identity being present in the query payload; malformed or encrypted payloads reduce visibility.
• Rate limits are evaluated per proxy instance unless backed by a shared limiter implementation.
• Residency enforcement validates configured targets/regions — it does not automatically move tenant data between regions.
• Enterprise analytics and chargeback require downstream metric collection even though this step emits the right tenant context.

Security and operational guidance

• Use authenticated, non-spoofable identity
• Fail closed when tenant identity is required
• The pinned Proxy controller does not watch NexoTenantIsolation directly
• Do not claim 0.2.0 data-path isolation

Related steps

• rate-limiting
• access-control
• traffic-split

Release availability

• Current documentation: Catalog component; confirm a bundle that executes router-phase components.

See the component catalog for the complete comparison matrix.