Skip to main content

Multi-tenancy and isolation

This page is written for security reviewers evaluating vastframe cloud, where one installation serves many organizations. Each organization is a tenant in the technical terms used on this page. A self-hosted installation runs the same code with exactly one tenant.

Summary​

  • One shared control plane serves many tenants. A copy of the stack per tenant was rejected because it puts a fixed cost on every trial, including idle ones.
  • Isolation of control-plane data is enforced by Postgres, not only by application code: every tenant table has forced row-level security, and the application connects as a role that can't bypass it.
  • Every per-tenant resource is named per tenant: containers, app databases and their roles, storage containers, token audiences and session cookies.
  • Every request is resolved to exactly one tenant before it touches data, and a request that can't be resolved is refused.

Control-plane data: forced row-level security​

ControlDetail
Tenant columnEvery tenant table has tenant_id, defaulting to the session's tc.tenant_id setting
Forced RLSRow-level security is enabled and forced on every tenant table, so it applies to the table owner too
Non-owner roleThe Hub API and worker query as tc_hub_app, which doesn't own the tables and has no BYPASSRLS
Tenant per queryThe database pool sets tc.tenant_id from the caller's tenant scope before every query. A query outside any tenant scope sees no rows
Owner connectionA separate owner connection is used only for migrations, the tenant registry and the installation API
Global tablesOnly tenants, tenant_domains, tenant_idps and signing_keys are global

A bug that forgets a where tenant_id = … clause still returns only the current tenant's rows, and a code path that runs without a tenant scope returns nothing.

Resolving the tenant​

A request's tenant comes from, in order:

  1. The host name. Each tenant has one or more domains, matched by longest suffix: console.acme.vastframe.app, auth.acme…, <app>.acme….
  2. X-TC-Tenant, used by the CLI and MCP when they call the API directly, and by internal callers.
  3. The installation default. It is empty on the SaaS installation, so a request that names no tenant is refused.

Background jobs carry their tenant id and run inside it. Installation-wide sweeps (resync, cost, lifecycle, the cron scheduler) loop over tenants, entering each tenant's scope in turn.

Per-tenant names​

ResourceSelf-hosted (default tenant)vastframe cloud tenant acme
Containers and imagestc-<project>-<id>tc-acme--<project>-<id>, labelled tc.tenant=acme
App database and rolesp_<project>p_acme__<project>
Storage containertc-<project>tcacme-<project>
Token audiencestc:hub, tc:app:<project>tc:hub:acme, tc:app:acme:<project>
Identity tokenscarry the tenant in tidcarry the tenant in tid
Edge session cookieon the installation's apps domainon .acme.<domain>, marked with the tenant, and ignored on other tenants

Tenant slugs are 2–20 lowercase letters and digits, starting with a letter and with no dashes, and the tenant prefix ends in a double separator (-- or __) that project names can't contain. So the default tenant's project acme-crm can never collide with tenant acme's project crm. Because audiences include the tenant, an identity token issued for an app in one tenant is rejected by every other tenant's apps and Data APIs.

Data plane​

  • App databases: each project has its own database with its own roles; there is no shared schema between projects or tenants. Row-level security inside an app database is the app's own (see Row-level security).
  • Integration Gateway and storage service: each request runs in the tenant of the caller's verified token.
  • Caches: every in-memory cache (authorization decisions, Studio connection pools, gateway and storage caches) is keyed by tenant.

Sign-in and membership​

  • Each tenant has its own sign-in configuration: email links, Microsoft Entra ID, any OIDC provider, or SAML/SCIM through WorkOS. The Edge keeps one OIDC client per tenant.
  • Members only: in a tenant whose people are managed in vastframe, only its members get in. Someone who authenticates with the tenant's identity provider but isn't a member sees "Not a member yet".
  • Verified domains: a DNS TXT record proves domain ownership, and a domain verified by one tenant can't be claimed by another.
  • Emergency access sends email links to the tenant's Org Admins only, so a broken identity provider never locks a tenant out.

The operator plane​

vastframe's operators manage tenants through an installation API on the Hub's internal listener (not exposed through the Edge), authenticated by a dedicated token. It creates, suspends, resumes and deletes tenants, reports usage and installs licences. Deleting a tenant marks it deleting; the worker then tears down every project and removes the tenant's rows. Operator actions are audited.

Known gaps​

We list these so reviewers don't have to find them:

  • Per-tenant wildcard certificates on Azure are still being designed (DNS-01, or on-demand TLS with an allow-list endpoint).
  • Edge email-link nonces are held in memory, so the Edge runs as a single replica for now.
  • Licence signing uses a key file; on Azure it moves to a non-exportable Key Vault key.
Was this page helpful?