Security

This page describes what the gateway protects, what each service must protect itself, and how to harden a Router deployment. Read it before the first production deployment.

Trust model

BoundaryWho enforces itHow
Caller to gatewayThe gatewayJWT bearer authentication, then each endpoint’s required claims
Service to gateway (who may register endpoints)The transportNetwork placement, and mTLS on the TLS transport
Gateway to service (the frames on the wire)The transportTLS, or broker security with frame protection on queue transports
The caller’s identity inside a serviceThe serviceAn endpoint class validates the forwarded bearer token itself; a bridged ASP.NET Core endpoint takes the caller from the identity envelope the gateway signs (ASP.NET Core bridge)

The gateway is the authorization boundary for callers. A service receives only requests that passed the gateway’s checks, so a service may rely on the endpoint claims it published. It may not rely on anything else in the request without checking it.

Caller authentication

The gateway host refuses to start without JWT bearer authentication under Authentication:Schemes:Bearer. It requires all three:

SettingMeaning
Authority or MetadataAddress, or SigningKeysWhere the signing keys come from: an OpenID Connect provider, or keys in configuration
ValidIssuer or ValidIssuersThe issuers to accept
ValidAudience or ValidAudiencesThe audiences to accept

The gateway keeps the token’s claim names (scope, scp, roles), because endpoint claims are written with them; set MapInboundClaims only to change that. Every endpoint of an endpoint class requires an authenticated caller (401 without a valid token). A bridged ASP.NET Core endpoint with [AllowAnonymous] is public through the gateway: the gateway checks neither a token nor claims for it.

Endpoint claims

Each endpoint publishes the claims a caller needs (Microservice SDK):

A caller without a required claim gets 403. Publish a claim on every endpoint that changes data or returns data that not every authenticated caller may read.

A POST, PUT, PATCH or DELETE endpoint, or one that accepts any method, that publishes no claims takes the claims of the other endpoints of the same service on the same path. With GET /invoices/{id} requiring invoices:read, a DELETE /invoices/{id} without claims requires invoices:read as well, and a caller without it gets 403. Give every write endpoint its own claims, so the requirement is the one you chose.

The gateway’s own endpoints

PathMethod and access
/api/v1/router/instancesGET, scope router:routing:read
/api/v1/router/endpointsGET, scope router:routing:read
/api/v1/router/routing/weightsGET, scope router:routing:read; POST, scope router:routing:write
/api/v1/gateway/administration/router/resyncPOST, scope router:routing:write
/health, /health/live, /health/ready, /health/startup, /metricsGET, no token
The OpenAPI document (when Gateway:OpenApi:Enabled)GET, no token

Grant router:routing:write to operators only. The health, metrics and OpenAPI paths answer without a token: keep them off the public interface when they should not be public, for example with a reverse proxy rule (Running behind a reverse proxy).

Who may register endpoints

A process that connects to a transport port announces its endpoints, and the gateway routes matching requests to it. Treat the transport ports as privileged:

  1. Never expose a transport port to the network callers use.
  2. Use TLS with RequireClientCertificate, so that only services with a client certificate you issued can connect (Transports).
  3. On queue transports, give each side its own broker credentials, and turn on frame protection.

Transport security

The caller’s identity inside a service

The gateway forwards the caller’s request headers to the service, including Authorization. The gateway has validated that token, but a service that needs the caller’s identity (the subject, a tenant, a role) should validate the token again, with the same issuer and audience settings, before it trusts any claim.

Identity headers. The gateway removes every identity header a caller sends (X-StellaOps-Actor, X-StellaOps-TenantId, X-StellaOps-Scopes, X-StellaOps-Roles, X-StellaOps-Session, the identity envelope headers and the others listed in Router gateway host) and, when Gateway:IdentityEnvelope:SigningKey is set, signs the authenticated caller into an identity envelope. The ASP.NET Core bridge reads the caller only from that envelope, verified with the same key, and never from request headers. A custom gateway host gets this step from UseRouterGatewayHost; one that also removes every other X-StellaOps-* request header, as the sample does, adds a middleware before it:

// Optional hardening: the gateway host already removes the identity headers (X-StellaOps-Tenant,
// X-StellaOps-Scopes, the identity envelope and the rest) from every routed request. This middleware
// also removes every other X-StellaOps-* request header, so no caller-supplied one reaches a service.
app.Use((context, next) =>
{
    foreach (var name in context.Request.Headers.Keys
                 .Where(key => key.StartsWith("X-StellaOps-", StringComparison.OrdinalIgnoreCase))
                 .ToList())
    {
        context.Request.Headers.Remove(name);
    }

    return next(context);
});

The .NET tool host needs no such middleware. See ASP.NET Core bridge for what a bridged endpoint sees.

Errors and what they reveal

Hardening checklist