Skip to content
Cratis

Tenant resolvers

Where does the tenant come from: a header your gateway sets, a claim in the user’s token, or the acme in acme.example.com? Pick the source, or an ordered list of sources, that matches how your callers arrive.

Set tenancy.resolverType for one .NET-compatible source, or tenancy.sources for an ordered list. The first nonempty result wins. Do not set both. A header or query-string value is a selection, not proof of authority.

Sources

Section titled “Sources”
SourceConfigurationReads
headertenancy.httpHeader (default x-cratis-tenant-id)Request header
queryqueryParameter (default tenantId)Request query string
claimclaimType (default tenant_id)An own string claim on an authenticated principal
fixedfixedTenantId (default development)A configured deployment value
developmentfixedTenantId (default development)The same fixed source as in .NET; it does not check your environment
subdomainRequired baseDomainThe verified adapter native.authority, not the raw Host or X-Forwarded-Host header

Import TenantResolverType from @cratis/arc.core. For a single-tenant application, resolverType: TenantResolverType.Fixed, fixedTenantId: 'default' gives every request the default tenant.

Options

Section titled “Options”
OptionEffect
resolverType / sourcesOne source (defaults to header when tenancy is supplied) / an ordered list; they cannot be combined
requiredAn unresolved tenant answers 400
membershipClaimA selected tenant requires an authenticated principal whose own claim of this name, a comma-separated list, includes it; otherwise 403
queryParameter, claimType, fixedTenantId, baseDomainPer-source settings

Validation rules

Section titled “Validation rules”
  • Nonempty IDs are lowercased and must be DNS labels: letters, digits, and hyphens, at most 63 characters. An invalid selected ID answers 400.
  • A nonstring selected tenant claim answers 400; a nonstring membership claim answers 403. Strategies read only own string values from the claim object.
  • subdomain requires an ASCII baseDomain of at least two labels and a host-verified authority from the adapter callback. Only a single subdomain label matches; IP addresses, unrelated or multi-label hosts, and raw Host or forwarded headers never do.
  • The header is the default source when tenancy is supplied; no development or fixed strategy is installed implicitly. Write sources: [TenantResolverType.Subdomain, TenantResolverType.Header] to fall back explicitly.
  • Other strategy errors and unsafe startup options fail closed.

Never use development or fixed to accept a browser-supplied tenant without validating access. tenancy.resolve overrides these sources, and the legacy header behavior applies when tenancy is absent; see Tenancy.

Section titled “Related”