Who Are You?

One address, many doors

Dana’s request leaves the browser. The very first program it meets is the Gateway — and it never gets past the lobby without showing a badge.

Think of an office building with one staffed lobby. There are dozens of rooms inside, but everyone enters through the same desk. The Gateway is a reverse proxy (built on a library called YARP): the only program exposed to the outside world. Everything else hides safely behind it.

The bouncer at the door

Before anything else happens, the Gateway looks at one thing: does your badge carry gateway.access? If it does not, you are turned away on the spot — no database lookup needed. The answer is already written on the badge by Keycloak (the one mapper kept from Module 3).

else if (!CallerHasGatewayAccess(httpContext.User, authorizationHeader))
{
    await VsAuthProblems.WriteProblemAsync(
        httpContext,
        StatusCodes.Status403Forbidden,
        "Forbidden",
        "The caller does not have gateway.access.",
        "missing-gateway-access");
    return;
}

Reading the company, then the badge-swap

Once the badge passes, the Gateway figures out which company Dana is acting in by reading it straight from the web address (/orgs/{org}/Departments). Then comes the clever part: it performs a token exchange — trading Dana’s login badge for a fresh capability ticket — before handing the request to the backend. Watch it happen.

And here is the actual swap. Each forwarded request runs through a small transform that clears the incoming header and attaches the new ticket instead.

transformContext.AddRequestTransform(requestContext =>
{
    requestContext.ProxyRequest.Headers.Authorization = null;
    if (requestContext.HttpContext.Items[ExchangedTokenItemKey] is string accessToken &&
        !string.IsNullOrWhiteSpace(accessToken))
    {
        requestContext.ProxyRequest.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    }
    return ValueTask.CompletedTask;
});

Self-updating map vs printed map

How does the Gateway know which backend to forward each request to? It keeps a map of routes. The big design change in this platform is where that map comes from.

Here is the route map being loaded from configuration — and validated — before the Gateway serves a single request.

public static IReadOnlyList<GatewayRoute> LoadRoutes(IConfiguration configuration)
{
    var configured = configuration.GetSection("Gateway:Routes").Get<GatewayRoute[]>();
    if (configured is not { Length: > 0 })
    {
        throw new InvalidOperationException("Gateway:Routes must define at least one route.");
    }
    return Validate(configured.Select(route => route.Normalize()).ToArray());
}

A single route in that map is just a small, readable entry — for example:

A verdict, not a crash

Things go wrong: a missing gateway.access, a route that cannot be resolved, a token exchange that fails. A good front door does not collapse in a heap when that happens.

Check your understanding

No memorizing — just think through what you would actually do.

The keys on the wristband

Think of a theme park. The turnstile out front proves you bought a ticket — but it never decides which rides you can go on. Each ride checks your wristband for the exact band-color it needs.

In our platform, that band-color is a capability: a precise service.action string. The old design used coarse roles and permissions like "manager." The new design replaces them with many small, exact keys.

How a ride checks your wristband

Before any endpoint runs, the Business API runs a small gatekeeper that asks one question: does this ticket allow the capability this ride requires? This gatekeeper is written as an attribute on the endpoint.

public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
{
    var authorization = context.HttpContext.RequestServices.GetRequiredService<IVsAuthorization>();
    var resource = VsResource.FromHttpContext(context.HttpContext, CapabilityId);
    var decision = await authorization.AuthorizeAsync(CapabilityId, resource, context.HttpContext.RequestAborted);
    if (!decision.IsAllowed)
    {
        await decision.ToProblem().ExecuteAsync(context.HttpContext);
        return;
    }
    await next();
}

Every service also publishes its own catalog — the list of capabilities it understands. It is the menu of band-colors that this part of the park even knows how to check.

public static readonly ICapabilityCatalog Catalog = CapabilityCatalog.FromDescriptors([
    new CapabilityDescriptor(EmployeesRead, "employees", "read", null, "Read employee records."),
    new CapabilityDescriptor(EmployeesWrite, "employees", "write", null, "Create, update, and delete employee records."),
    new CapabilityDescriptor(DepartmentsRead, "departments", "read", null, "Read department records."),
    new CapabilityDescriptor(DepartmentsWrite, "departments", "write", null, "Create, update, and delete department records.")
]);

The negotiation

The booth that prints your wristband is CTS — the Capability Token Service. Before it stamps a ticket, it phones the rulebook (Authz) to ask which bands Dana has earned for this park. Watch the whole conversation unfold.

Where the yes/no really comes from

The rest of the platform asks the rulebook exactly one question, through a single door. Notice how narrow the contract is — there is just one way to ask "what may this person do here?"

v1.MapPost("/capabilities/resolve", async (
    CapabilityResolveRequest request,
    ICapabilityResolver resolver,
    CancellationToken cancellationToken) =>
{
    var response = await resolver.ResolveAsync(request, cancellationToken);
    return Results.Ok(response);
})

Behind that door, the rulebook does the real lookup. People are placed into groups; groups hold capabilities. To find what Dana can do, it gathers every capability granted by every group she belongs to.

var capabilityIds = await orgDb.UserGroups.AsNoTracking()
    .Where(row => row.Subject == membership.Subject)
    .Join(
        orgDb.GroupCapabilities.AsNoTracking(),
        userGroup => userGroup.GroupCode,
        groupCapability => groupCapability.GroupCode,
        (_, groupCapability) => groupCapability.CapabilityId)
    .Distinct()
    .ToArrayAsync(cancellationToken);

Claimed vs Authorized

Here is the lesson that matters most. CTS mints a signed token and only includes the capabilities the rulebook actually returned. If the rulebook returns none, the answer is simply "forbidden" — there is no ticket to carry.

foreach (var capability in capabilities)
{
    claims.Add(new Claim("capabilities", capability));
}

A small piece of history: an old capability_version idea was removed in favor of a passthrough authz_version that is currently inert — it rides along but does nothing yet.

Think it through

No memorizing — just reason about how capabilities, the rulebook, and the ticket fit together.

One vault, many locked boxes

Picture a bank vault full of safe-deposit boxes. There is one vault — one big steel room — but every customer has their own locked box inside it. The same teller serves everyone, yet can only open the box whose key it was handed for that visit.

That is exactly how the platform stores data. There is one database, but each company gets its own private schema to keep its data sealed off from everyone else's. This design is called being multi-tenant, and each company is a tenant.

Here is the layout: one shared platform drawer that holds the master catalog and the company directory, plus one private org_<id> drawer per company.

The directory and the private drawers

When the database is first built, a startup script carves out the shared platform area and one drawer per company. Here is the real code that creates them.

CREATE SCHEMA IF NOT EXISTS platform;
CREATE SCHEMA IF NOT EXISTS template_default;
CREATE SCHEMA IF NOT EXISTS "org_11111111-1111-4111-8111-111111111111";
CREATE SCHEMA IF NOT EXISTS "org_22222222-2222-4222-8222-222222222222";
          

Inside the shared area sits the directory itself — the org_registry table — which says "company X lives in drawer X."

CREATE TABLE IF NOT EXISTS platform.org_registry (
    org_id text PRIMARY KEY,
    org_name text NOT NULL,
    schema_name text NOT NULL UNIQUE,
    status text NOT NULL,
    authz_version text NOT NULL,
    primary_route_prefix text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    updated_at timestamptz NOT NULL DEFAULT now()
);
          

So the shared area is small but crucial: a master catalog of capabilities, plus this lookup table. Everything else lives in the private per-company drawers.

How a query stays in the right drawer

Here is the magic that ties it together. Before the platform runs any read or write, it hands the database one short instruction: "for this operation, look in THIS company's drawer first." That instruction is a setting called the search_path. This single line is the heart of the whole isolation story.

private string SearchPathSql => "SET LOCAL search_path TO " + QuoteSchema(SchemaName!) + ", platform";
          

The word transaction matters here: SET LOCAL applies only inside the current bundle of work and is forgotten the instant it ends. One request can never poison the next.

Setting it all up: the Reconciler

📖 The Auth Reconciler is a one-shot tool — not an always-on service. You run it, it builds the database to match what it should look like, and then it stops. Its superpower is being safe to run again and again. Here is what one run does.

In code, that run is almost as readable as the steps above. Each line is one phase.

await ReferenceOrgMigrationOrchestrator.MigratePlatformSchemaAsync(connectionString, cts.Token);
await SeedPlatformDataAsync(connectionString, logger, cts.Token);
var schemaNames = await ReferenceOrgMigrationOrchestrator.ResolveOrgSchemaNamesAsync(connectionString, bootstrapNames, cts.Token);
await SampleTenantSchemaMigrator.MigrateOrgSchemasAsync(connectionString, schemaNames, logger, cts.Token);
await SeedOrgDataAsync(connectionString, schemaNames, logger, cts.Token);
          

The sticky-note memory

⚡ Some questions get asked over and over — like "what are this company's departments?" Rather than open the drawer every single time, the Business API jots the answer on a sticky note (a cache, held in Redis) and reads the note next time. But there is a catch: when the underlying data changes, the note is now wrong.

This snippet — the "create a department" path from the controller you saw in Module 1 — shows the fix: after writing, throw the stale note away.

await using var dbContext = await dbFactory.CreateWriteAsync(orgId);
var department = new Department { DepartmentName = input.DepartmentName };
dbContext.Departments.Add(department);
await dbContext.SaveChangesAsync();
await listCache.RemoveAsync(ListCacheKey(orgId));
          

Notice the note is filed under ListCacheKey(orgId) — a cache key that includes the company id. That way one company's notes can never answer another company's question. And tearing up the note after a change is called cache invalidation.

Think it through

No definitions to recite — just put the pieces together.