Multi-Tenancy Architecture
An environment is a deployment and operational boundary. A tenant is an identity and authorization boundary within it. A client represents an application in that tenant. A tenant is not the same thing as a database: several tenants can use shared capacity, while tenant-exclusive placement is also a Control Plane policy.
Environment, tenant, and client
Section titled “Environment, tenant, and client”| Object | Role |
|---|---|
| Environment | Setup-managed deployment, resource configuration, keys, and release state; keep production and evaluation resources separate |
| Tenant | Tenant-scoped accounts, clients, policies, and runtime context |
| Client | Registered application with its own protocol configuration, redirect URIs, and authentication method |
| Organization | A domain object used for membership/authorization; do not equate every organization with a separate deployment or tenant |
Register applications in their intended tenant. Reusing a secret across applications or environments weakens that boundary; copying an environment configuration is not a migration plan.
Resolving tenant context
Section titled “Resolving tenant context”Request processing resolves the host and the applicable request class, then validates tenant context. Supported paths include configured domain parsing and registered vanity-host resolution. Platform administration, tenant-scoped administration, discovery/UI, and protocol requests have different context requirements.
tenant_hint is a user-experience hint, not authority to select another tenant’s data. Forwarded hosts and administrative tenant selectors are subject to their respective checks; an arbitrary header does not grant cross-tenant access.
Domains and issuers
Section titled “Domains and issuers”BASE_DOMAIN, the configured default/primary tenant, domain parsing settings, and issuer configuration work together. A simple subdomain pattern can use acme.auth.example.com, but the hostname must resolve through the configured mapping; do not assume a label is always the canonical tenant ID.
Naked-domain handling and the issuer URL are related but separate. NAKED_DOMAIN_AS_ISSUER affects issuer construction. Registered vanity domains are supported through their own resolver, so “only hosts under BASE_DOMAIN are ever accepted” is not an accurate description.
Use Setup’s generated URLs and the tenant’s Discovery document. Invalid or unrecognized domains must not be used to bypass tenant validation. Changing DNS alone neither creates a tenant nor changes its issuer and application trust configuration safely.
Data placement
Section titled “Data placement”Control manages shared-pool and tenant-exclusive placement. The signed runtime registry records actual stores and route generations. Tenant metadata can have a different Core destination from an account’s Core/PII pair; Lookup resolves the account’s location.
Runtime database resolution validates the tenant, role, binding, shard, residency partition, and generation. A tenant-exclusive policy concerns resource placement; tenant-scoped access checks are still needed. Conversely, logical tenant isolation does not imply a dedicated physical database for every tenant.
Adding a tenant
Section titled “Adding a tenant”- Use the tenant-management surface with the required administrative authority; do not use the obsolete
/admin/tenantsexample. - Choose the supported placement and domain settings and allow provisioning/registry publication to complete.
- Confirm the tenant is ready, its domain resolves correctly, and Discovery returns the intended issuer.
- Register clients and identity providers in that tenant.
- Verify authentication, token validation, and rejection of cross-tenant access.
Consult the current Admin API for request bodies and permissions. Creating a tenant record is not by itself evidence that all routes and databases are ready.
Operating multiple tenants
Section titled “Operating multiple tenants”Keep administrative permissions, token issuer/audience checks, sessions, caches, and database access scoped to the appropriate context. The implementation provides tenant-aware helpers, but custom SQL and integrations must use them correctly; queries are not magically tenant-scoped by the database adapter.
Federation and token exchange are explicitly configured trust relationships. They do not remove tenant boundaries or authorize arbitrary cross-tenant data access.
When changing deployment or data topology, use the supported setup/control operation and verify completion. Setting BASE_DOMAIN alone does not migrate existing data into a new multi-tenant layout.
See Architecture, PII Separation, and Installation.