Docs
Tenantry Core

ASP.NET Core integration

View as Markdown

Tenantry.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:

  1. 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).
  2. 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.
  3. Finds the tenant the identifier names, with ITenantLookup<TKey>.FindByIdentifierAsync, which calls your store's FindByIdentifierAsync (by default: parse the identifier as TKey and look the id up) and serves it from the cache with CacheTenants. If none, a request that requires a tenant is rejected (see Status codes).
  4. 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.
  5. Makes the tenant current (ITenantContextSetter.MakeCurrent) for the remainder of the request, tags the request's trace span tenant.id and opens a log scope with TenantId, and raises OnResolved. 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 statusOption
No resolver produced an identifier400 Bad RequestMissingTenantStatusCode
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 FoundTenantNotFoundStatusCode
An access validator refused the tenant403 ForbiddenAccessDeniedStatusCode
The tenant is not active (ValidateTenantActivity)403 Forbidden, with the access-denied responseInactiveTenantStatusCode
The identifier names no tenant, and access validators are configuredsame as access deniedAccessDeniedStatusCode

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:

  • OnResolved runs 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 as CultureInfo.CurrentCulture or an AsyncLocal, reach the rest of the pipeline only if the handler is not an async method (set them and return Task.CompletedTask;): an async handler's changes are undone when it returns, even those made before its first await. For a per-tenant culture, use UseRequestLocalization with a culture provider that reads ITenantContext<TKey>. To refuse a tenant, use an access validator.
  • OnRejected runs when an endpoint that requires a tenant rejects a request, before Tenantry writes its response. It is told the Reason (Missing, NotFound, AccessDenied or Inactive), the StatusCode Tenantry would send, the Identifier the request sent and, for AccessDenied and Inactive, the refused Tenant. Change StatusCode, or write your own response and call HandleResponse(), 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 endpoints

With 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.

On this page