ASP.NET Core integration
View as MarkdownTenantry.AspNetCore turns an incoming HTTP request into a resolved tenant. It adds, to the builder of
AddTenantry<TKey>(...):
- tenant resolvers (header, subdomain, host, route, claim, query string, your own): see Tenant resolution;
- access validation and endpoint metadata: see Access control;
ConfigureResolution(...): whether endpoints need a tenant, the status codes of rejections, and the events raised when a request's tenant is made current or a request is rejected;
and app.UseTenantry(), the resolution middleware, which also checks the registration when the application starts.
Its logs, traces and metrics are described in Diagnostics.
Registration
using Tenantry;
builder.Services.AddTenantry<Guid>(tenant => tenant
.ResolveFromHeader("X-Tenant-Id") // resolution (at least one required)
.UseInMemoryStore(tenants) // storage (exactly one required)
.RequireTenantByDefault() // policy (optional)
.ValidateTenantAccessByClaim("tenant_id")); // access control (optional)Tenantry.AspNetCore adds these methods to the AddTenantry builder. The first one you call registers the
middleware's services. See Registration for the rules every builder method follows.
Startup validation
app.UseTenantry() throws InvalidOperationException when the pipeline is built if no resolver or no store is
registered. A web application that registers resolvers but never calls app.UseTenantry() fails to start, because
no request would have a tenant. A host that serves no requests (a worker) is not checked. Registering a second store,
or a second key type, throws at once.
The middleware
var app = builder.Build();
app.UseTenantry();For each request, the middleware:
- Tries each registered resolver in registration order and takes the first identifier one returns (
null, an empty string or whitespace counts as none, and the next resolver runs). - If no resolver produced an identifier:
- if a tenant is required for this request (see Access control), rejects it
(
400 Bad Request) and stops; - otherwise continues the pipeline with no tenant.
- if a tenant is required for this request (see Access control), rejects it
(
- Finds the tenant the identifier names, with
ITenantLookup<TKey>.FindByIdentifierAsync, which calls your store'sFindByIdentifierAsync(by default: parse the identifier asTKeyand look the id up) and serves it from the cache withCacheTenants. If none, a request that requires a tenant is rejected (see Status codes). - Runs the access validators in the order they were added, then checks the tenant is active. If either refuses, a request that requires a tenant is rejected (see Status codes). A caller the validators refuse is denied access whether or not the tenant is active, so only a caller they allow can learn that a tenant is suspended.
- Makes the tenant current (
ITenantContextSetter.MakeCurrent) for the remainder of the request, tags the request's trace spantenant.idand opens a log scope withTenantId, and raisesOnResolved. The tenant is restored when the request ends.
A request to an endpoint that does not require a tenant is never rejected: when its identifier names no tenant, or
one that is refused, it continues without a tenant, as if it had no identifier. So a www. host or a stale header
does not break your login and health endpoints.
Resolvers and access validators added by type (UseResolver<TResolver>(), ValidateTenantAccess<TValidator>()) are
created in the request's service scope, so they can depend on a scoped DbContext. The store is read through
ITenantLookup<TKey> (lifetimes).
Status codes
| Situation (on an endpoint that requires a tenant) | Default status | Option |
|---|---|---|
| No resolver produced an identifier | 400 Bad Request | MissingTenantStatusCode |
| The identifier names no tenant (with the default lookup: it does not parse, is the key type's default, or is not in the store) | 404 Not Found | TenantNotFoundStatusCode |
| An access validator refused the tenant | 403 Forbidden | AccessDeniedStatusCode |
The tenant is not active (ValidateTenantActivity) | 403 Forbidden, with the access-denied response | InactiveTenantStatusCode |
| The identifier names no tenant, and access validators are configured | same as access denied | AccessDeniedStatusCode |
With access validators, a tenant that does not exist gets exactly the response of one the caller may not use,
so an authenticated user of one tenant cannot probe for others. A suspended tenant gets that response too, unless you
give InactiveTenantStatusCode another value, such as 402 Payment Required for a lapsed subscription; even then,
only callers the access validators allow get it. Change the
codes with ConfigureResolution:
builder.Services.AddTenantry<Guid>(tenant => tenant
.ResolveFromHeader("X-Tenant-Id")
.UseStore<EfCoreTenantStore>()
.ConfigureResolution(options =>
{
options.RequireTenantByDefault = true;
options.MissingTenantStatusCode = StatusCodes.Status401Unauthorized;
}));A rejection's body is empty unless an IProblemDetailsService is registered (builder.Services.AddProblemDetails()),
in which case it is application/problem+json with the status, a title (Tenant required, Tenant not found,
Tenant access denied) and a short detail. The body never repeats the identifier the request sent. Customise the
problem details as usual, with AddProblemDetails(options => options.CustomizeProblemDetails = …), or write a
response of your own in OnRejected.
Events
ConfigureResolution sets two handlers:
OnResolvedruns when a request's tenant has been made current, before the rest of the pipeline, with the request and the tenant: to add the tenant to your own telemetry, say. Changes it makes to ambient state, such asCultureInfo.CurrentCultureor anAsyncLocal, reach the rest of the pipeline only if the handler is not anasyncmethod (set them andreturn Task.CompletedTask;): anasynchandler's changes are undone when it returns, even those made before its firstawait. For a per-tenant culture, useUseRequestLocalizationwith a culture provider that readsITenantContext<TKey>. To refuse a tenant, use an access validator.OnRejectedruns when an endpoint that requires a tenant rejects a request, before Tenantry writes its response. It is told theReason(Missing,NotFound,AccessDeniedorInactive), theStatusCodeTenantry would send, theIdentifierthe request sent and, forAccessDeniedandInactive, the refusedTenant. ChangeStatusCode, or write your own response and callHandleResponse(), so Tenantry writes none:
using Tenantry.AspNetCore;
builder.Services.AddTenantry<Guid>(tenant => tenant
.ResolveFromSubdomain(o => o.BaseDomains.Add("example.com"))
.UseStore<EfCoreTenantStore>()
.RequireTenantByDefault()
.ConfigureResolution(o => o.OnRejected = context =>
{
// A browser that asks for a workspace that does not exist goes to the marketing site.
if (context.Reason == TenantRejectionReason.NotFound)
{
context.HttpContext.Response.Redirect("https://example.com/");
context.HandleResponse();
}
return Task.CompletedTask;
}));Reason is the real reason, for your logs; StatusCode hides it as described under Status codes.
Keep it hidden in a response of your own, and do not repeat Identifier, which is request input, without encoding
it.
Pipeline ordering
Call UseTenantry() after UseAuthentication(), so the access validators and ResolveFromClaim see the user, and
before anything that needs the tenant: your endpoints and EF Core work driven by the request. Without
UseTenantResolution(), put it after UseAuthorization() too, so an anonymous caller gets 401 rather than 403, unless
an authorization policy needs the tenant: then put it before UseAuthorization(). Either way it comes after routing,
so it sees endpoint metadata (WebApplication adds routing first; a custom pipeline must call UseRouting() before
UseTenantry()).
For authentication settings that differ per tenant, call UseTenantResolution() before UseAuthentication(), and
then UseAuthorization() always comes after UseTenantry(), so no policy sees a tenant the access validators have not
checked: see Authentication per tenant.
If the middleware runs before routing, a request without a tenant to an endpoint that requires one is still
rejected, but RequireTenantByDefault() then applies to AllowMissingTenant() endpoints too, and route values are
not there to resolve from. If the authentication middleware runs after it, ResolveFromClaim sees no user. The
middleware logs each mistake once (event ids 1007 and 1008). A user signed in by other code
after the middleware, such as authorization with a scheme that is not the default, is not seen by ResolveFromClaim
either, and is not warned about: make that scheme the default.
A typical order, without UseTenantResolution():
app.UseAuthentication();
app.UseAuthorization(); // first, so an anonymous caller gets 401 (not with UseTenantResolution())
app.UseTenantry(); // resolves the tenant (reads User if using claims; reads endpoint metadata)
app.MapControllers(); // or minimal API endpointsWith an authorization policy that reads the tenant, put app.UseTenantry() between the two instead.
Reading the tenant in your code
Inject ITenantContext<TKey> anywhere. On an endpoint that requires a tenant (RequireTenant(), or
RequireTenantByDefault()), a request without one is refused before the handler runs, so the handler need not
check:
app.MapGet("/me", (ITenantContext<Guid> ctx) => Results.Ok(ctx.CurrentTenant!.Name))
.RequireTenant();Check HasTenant only where the tenant is optional: on an endpoint that does not require one.
Read CurrentTenantId for work outside EF Core, which applies the tenant for you.
MVC / controllers
Everything above applies to controllers too. The endpoint metadata is [RequireTenant] and [AllowMissingTenant] on
controllers, and .RequireTenant() and .AllowMissingTenant() on minimal APIs. See Access control.
Owned and multi-table entities
Owned rows in a table of their own, the rows of an entity mapped to more than one table, and the join rows of a many-to-many relationship have no tenant check of their own.
Options per tenant
Settings that differ between tenants (a limit that follows the tenant's plan, a brand colour, an upstream endpoint) can stay in the options pattern.