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
| Boundary | Who enforces it | How |
|---|---|---|
| Caller to gateway | The gateway | JWT bearer authentication, then each endpoint’s required claims |
| Service to gateway (who may register endpoints) | The transport | Network placement, and mTLS on the TLS transport |
| Gateway to service (the frames on the wire) | The transport | TLS, or broker security with frame protection on queue transports |
| The caller’s identity inside a service | The service | An 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:
| Setting | Meaning |
|---|---|
Authority or MetadataAddress, or SigningKeys | Where the signing keys come from: an OpenID Connect provider, or keys in configuration |
ValidIssuer or ValidIssuers | The issuers to accept |
ValidAudience or ValidAudiences | The 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 requirement with a value matches a claim of that type and value;
- for
scopeandscp, a space-separated list in one claim also matches; - a requirement without a value matches any claim of that type.
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
| Path | Method and access |
|---|---|
/api/v1/router/instances | GET, scope router:routing:read |
/api/v1/router/endpoints | GET, scope router:routing:read |
/api/v1/router/routing/weights | GET, scope router:routing:read; POST, scope router:routing:write |
/api/v1/gateway/administration/router/resync | POST, scope router:routing:write |
/health, /health/live, /health/ready, /health/startup, /metrics | GET, 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:
- Never expose a transport port to the network callers use.
- Use TLS with
RequireClientCertificate, so that only services with a client certificate you issued can connect (Transports). - On queue transports, give each side its own broker credentials, and turn on frame protection.
Transport security
- TLS encrypts frames. Use TLS 1.3 where both sides allow it, pin the gateway certificate in the services, and require client certificates in the gateway.
- TCP and UDP are unencrypted. Both halves refuse them unless the process environment variable
STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTSistrue,yesor1. Keep that variable out of production configuration. - RabbitMQ and Messaging depend on the broker’s TLS and access control. Turn on frame protection (
Router:Frame:Envelope) on both sides.
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
- An unhandled exception in an endpoint returns
500 Internal Server Errorwithout the exception text, and the service logs the exception. 400responses for invalid JSON include the parser’s message. Do not echo request content in error messages of your own.- Every routed response carries
Server: stellaops/<service>/<version>, the name and version the service announced. Remove or replace the header in a reverse proxy when callers should not see it. - In the
Developmentenvironment, a502answer from the gateway includes the exception message of the failed dispatch. Run production gateways in another environment.
Hardening checklist
- [ ] Callers reach only the gateway’s HTTP port; transport ports are internal.
- [ ] The TLS transport, with
RequireClientCertificatein the gateway and a pinned gateway certificate in each service. - [ ]
STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTSis not set in production. - [ ]
Authentication:Schemes:Bearernames your provider, andValidIssuersandValidAudienceslist only your values. - [ ] Every endpoint that changes data publishes a scope.
- [ ]
router:routing:writeis held by operators only. - [ ] Optional: every
X-StellaOps-*request header is removed before the gateway forwards a request; the gateway host removes the identity headers itself. - [ ] Bridged endpoints with
[AllowAnonymous]are meant to be public. - [ ] Health, metrics and OpenAPI paths are reachable only where intended.
- [ ] Secrets (certificate passwords, broker credentials, frame protection keys) come from a secret store or environment, never from committed files.
- [ ] Each service’s
HeartbeatIntervalis below the gateway’s degraded threshold, so instances do not flap (Troubleshooting).
