Tenant resolution
View as MarkdownResolution turns an HTTP request into a tenant, in two steps:
-
A resolver reads an identifier from the request: a header, the subdomain, the host name, a route value, a claim. A resolver implements
ITenantResolver:public interface ITenantResolver { ValueTask<string?> ResolveAsync(HttpContext context, CancellationToken ct = default); }It returns the identifier as a string, or
null(or an empty string) if the request does not carry one. -
The tenant store finds the tenant the identifier names, with
ITenantStore<TKey>.FindByIdentifierAsync. By default an identifier is the tenant's id: it is parsed asTKey(with the invariant culture) and looked up withGetTenantAsync. A store can map other names to its tenants, such as a slug or a custom domain forGuid-keyed tenants: see Identifiers other than the id.
Resolution is part of Tenantry.AspNetCore. In console and worker apps there is no request: you make a tenant
current with ITenantScopeFactory (Non-HTTP hosts).
Built-in resolvers
| Method | Source | Notes |
|---|---|---|
ResolveFromHeader(name) | request header name | Trims whitespace. A repeated header names no tenant. e.g. X-Tenant-Id. |
ResolveFromSubdomain(options) | the subdomain of the host | Ignores www and IP addresses; takes base domains. See below. |
ResolveFromHost() | the host name | For tenants with domains of their own. See below. |
ResolveFromRouteValue(key = "tenant") | route value key | For routes like /api/{tenant}/…. Needs routing before the middleware. |
ResolveFromClaim(type = "tenant_id") | claim on HttpContext.User | Needs authentication before the middleware. |
ResolveFromQueryString(name = "tenantId") | query string parameter | Development and testing only: see Query string. |
ResolveFromPropagationHeader(isTrustedCaller) | the tenantry-tenant-id header another service sent | Only from a caller isTrustedCaller accepts, after authentication; read as a tenant id. See Calling other services. |
Header
tenant.ResolveFromHeader("X-Tenant-Id");The most common choice for APIs and service-to-service calls. The value is trimmed; an empty value, or a header sent more than once, names no tenant. A proxy that sets the header must replace the client's, not add a second one.
Subdomain
tenant.ResolveFromSubdomain(options =>
{
options.BaseDomains.Add("example.com"); // acme.example.com → "acme"
options.BaseDomains.Add("localhost"); // acme.localhost → "acme", in development
options.IgnoredSubdomains.Add("api"); // api.example.com serves the app itself; "www" is ignored by default
});With base domains set, only a host of exactly one label followed by a base domain resolves a tenant:
acme.example.com resolves to acme, while example.com, www.example.com, x.acme.example.com and
acme.other.org resolve nothing. Add localhost for development, so acme.localhost resolves to acme
(browsers send *.localhost to the local machine).
Without it (tenant.ResolveFromSubdomain()), the resolver takes the first label of any host that has at least
three, and resolves nothing for shorter hosts: acme.app.example.com and app.example.com resolve to acme
and app, while example.com, localhost and acme.localhost resolve nothing.
Either way, a subdomain in IgnoredSubdomains (www by default) and a host that is an IP address (a load
balancer's or Kubernetes' health probe) resolve nothing, and the subdomain is returned in lower case (host names are
compared without regard to case). A host that still names no tenant does not break an endpoint that does not require
one: the request continues without a tenant (see ASP.NET Core integration).
Host (custom domains)
tenant.ResolveFromSubdomain(options => options.BaseDomains.Add("example.com")); // acme.example.com → "acme"
tenant.ResolveFromHost(options => options.ExcludedDomains.Add("example.com")); // app.acme.com → "app.acme.com"ResolveFromHost() returns the request's host name, in lower case and without a port, for tenants that bring
their own domain; your store's FindByIdentifierAsync maps the host name to a tenant. A host that is an IP address,
or is or is under one of ExcludedDomains (localhost by default), resolves nothing.
Every other host resolves, so a resolver added after it never runs for those hosts: add it last. Exclude your own
domain, as above: otherwise its hosts that are not tenants (www.example.com, example.com, api.example.com) each
ask the store for a tenant on every request, since a lookup that finds none is not cached.
Both host resolvers compare and return an international domain name in its ASCII form (xn--…), as DNS and
certificates have it: ASP.NET Core decodes it to Unicode, and the resolvers encode it again.
Route value
tenant.ResolveFromRouteValue(); // default key "tenant": /api/{tenant}/orders
tenant.ResolveFromRouteValue("org"); // /api/{org}/ordersBecause this reads a route value, routing must have run before UseTenantry() (automatic with
WebApplication).
Claim
tenant.ResolveFromClaim(); // default claim type "tenant_id"
tenant.ResolveFromClaim("org_id");Reads the claim from HttpContext.User, so UseTenantry() must come after UseAuthentication(). The caller
cannot name a tenant its token does not carry.
Query string
tenant.ResolveFromQueryString(); // ?tenantId=acme
tenant.ResolveFromQueryString("tenant"); // ?tenant=acmeDo not use this resolver in production: query strings are logged, cached by CDNs and stored in browser history. It is for local development and tests.
Resolver ordering and fallback
You can register several resolvers. The middleware tries them in registration order and uses the
first identifier one returns (null, an empty string or whitespace counts as none):
tenant.ResolveFromClaim("tenant_id"); // 1. the tenant in the caller's token
tenant.ResolveFromHeader("X-Tenant-Id"); // 2. otherwise, the header
tenant.ValidateTenantAccessByClaim("tenant_id"); // the caller must be entitled to itPut the most trusted source first. If none match, the request proceeds without a tenant unless a tenant is required (see Access control).
ResolveFromClaimreads the first matching claim, so use it only for tokens that carry exactly one tenant. For tokens that list several, resolve from the header and validate against the claims.- A header fallback lets any caller without the claim, anonymous ones too, name a tenant. Pair it with an access
validator such as
ValidateTenantAccessByClaim.
At least one resolver must be registered, or app.UseTenantry() throws at startup.
Custom resolvers
Implement ITenantResolver for another source, such as a cookie, a gRPC metadata entry or a combination of
signals.
using Tenantry.AspNetCore;
public sealed class CookieTenantResolver : ITenantResolver
{
public ValueTask<string?> ResolveAsync(HttpContext context, CancellationToken ct = default)
{
var value = context.Request.Cookies["tenant"];
return new ValueTask<string?>(string.IsNullOrWhiteSpace(value) ? null : value.Trim());
}
}Register it by type, instance, or factory:
tenant.UseResolver(new CookieTenantResolver()); // a specific instance
tenant.UseResolver(sp => new CookieTenantResolver(/* deps */)); // by a factory, in each request's scope
tenant.UseResolver<CookieTenantResolver>(); // created in each request's scopeUseResolver<TResolver>() and the factory overload create the resolver in each request's scope, so it can depend on
scoped services such as a DbContext. Like ValidateTenantAccess<T>(), UseResolver<TResolver>() returns the
builder without its key type (Registration). The request's scope disposes a resolver
the factory returns, so return a new one. An instance is used for every request.
A custom resolver runs in the order it was added among the built-in ones.
Return only the identifier, not the tenant: the store looks it up. An identifier the store does not know is rejected
on an endpoint that requires a tenant (404, or 403 when access validators are configured).
Identifiers other than the id
With Guid or int keys, a subdomain, a slug in a route or a custom domain is not the tenant's id. Implement
FindByIdentifierAsync in your store to map it: the middleware, and ITenantLookup<TKey>, call it with the
identifier a resolver returned.
using Microsoft.EntityFrameworkCore;
using Tenantry;
public sealed class AppTenantStore(CatalogDbContext db) : ITenantStore<Guid>
{
public async ValueTask<ITenantDescriptor<Guid>?> GetTenantAsync(Guid tenantId, CancellationToken ct = default) =>
await db.Tenants.FindAsync([tenantId], ct);
public async ValueTask<IReadOnlyList<ITenantDescriptor<Guid>>> GetAllTenantsAsync(CancellationToken ct = default) =>
await db.Tenants.ToListAsync(ct);
// acme.example.com resolves "acme"; app.acme.com resolves "app.acme.com".
public async ValueTask<ITenantDescriptor<Guid>?> FindByIdentifierAsync(string identifier, CancellationToken ct = default) =>
await db.Tenants.SingleOrDefaultAsync(t => t.Slug == identifier || t.CustomDomain == identifier, ct);
}Without it, the default parses the identifier as the key type and looks it up by id, so a store keyed by the
identifier itself (a string slug as the id) needs nothing more. To serve every request without a database
round trip, cache the lookups with CacheTenants.
Core concepts
Everything in Tenantry is built on a small set of types in the Tenantry namespace (package Tenantry.Core).
Tenant stores
A tenant store finds a tenant by id (GetTenantAsync) or by the identifier a request carries (FindByIdentifierAsync), returning null when there is none, and lists every tenant, suspended ones included (GetAllTenantsAsync).