git.stella-ops.org/docs/modules/router/IDENTITY_ENVELOPE_MIDDLEWARE.md

Identity Envelope Middleware

What

UseIdentityEnvelopeAuthentication() is a shared ASP.NET Core middleware that reads gateway-signed identity envelope headers and hydrates HttpContext.User with the enclosed claims. It lives in StellaOps.Router.AspNet and is consumed by every downstream microservice that receives proxied requests from the Router gateway.

Why

When the Router gateway forwards a request via YARP ReverseProxy, it strips the original Authorization: Bearer <jwt> header. Instead, it signs the authenticated user's identity into two custom headers:

• X-StellaOps-Identity-Envelope -- Base64URL-encoded JSON payload
• X-StellaOps-Identity-Envelope-Signature -- HMAC-SHA256 signature

Downstream services need a way to recover the caller's identity from these headers without each service re-implementing the same verification logic. The shared middleware eliminates duplication and ensures consistent claim mapping everywhere.

How to use

In the service's Program.cs, register the middleware before UseAuthentication():

using StellaOps.Router.AspNet;

// ...

app.UseIdentityEnvelopeAuthentication();   // <-- must come first
app.UseAuthentication();
app.UseAuthorization();

The service's .csproj must reference StellaOps.Router.AspNet (which transitively brings in StellaOps.Router.Common containing the codec).

Configuration

The middleware reads the HMAC-SHA256 signing key from one of two sources (first wins):

Source	Key
IConfiguration	Router:IdentityEnvelopeSigningKey
Environment variable	STELLAOPS_IDENTITY_ENVELOPE_SIGNING_KEY

In the docker-compose environment the key is injected via x-router-microservice-defaults so all services share the same value automatically.

Claim mapping

When a valid, non-expired envelope is verified, the middleware creates a ClaimsPrincipal with authentication type StellaRouterEnvelope and the following claims:

Claim type	Source
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier	envelope.Subject
sub	envelope.Subject
stellaops:tenant	envelope.Tenant
tenant	envelope.Tenant
stellaops:project	envelope.Project
project	envelope.Project
scope (one per scope)	envelope.Scopes
http://schemas.microsoft.com/ws/2008/06/identity/claims/role (one per role)	envelope.Roles

Architecture flow

Browser
  |
  |  Authorization: Bearer <jwt>
  v
Gateway (StellaOps.Gateway.WebService)
  |  1. Validates JWT
  |  2. Signs identity into envelope headers (HMAC-SHA256)
  |  3. Strips Authorization header
  |  4. Forwards via YARP ReverseProxy
  v
Downstream Service (Scanner, JobEngine, Timeline, Integrations, Concelier, ...)
  |  UseIdentityEnvelopeAuthentication()
  |  1. Reads X-StellaOps-Identity-Envelope + Signature headers
  |  2. Verifies HMAC-SHA256 signature
  |  3. Checks clock skew (5 min tolerance)
  |  4. Hydrates HttpContext.User
  v
  UseAuthentication() / UseAuthorization()
  (standard ASP.NET pipeline continues with the hydrated principal)

Error handling

The middleware never throws. All failures (missing headers, missing key, bad signature, expired envelope) are logged at Warning level under the StellaOps.IdentityEnvelope logger category. The request continues unauthenticated, allowing the standard JWT bearer handler to attempt authentication normally.

Adopted services

Service	File
Concelier	src/Concelier/StellaOps.Concelier.WebService/Program.cs
Scanner	src/Scanner/StellaOps.Scanner.WebService/Program.cs
JobEngine	src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Program.cs
Timeline	src/Timeline/StellaOps.Timeline.WebService/Program.cs
Integrations	src/Integrations/StellaOps.Integrations.WebService/Program.cs

Source

• Middleware extension: src/Router/__Libraries/StellaOps.Router.AspNet/IdentityEnvelopeMiddlewareExtensions.cs
• Envelope model and codec: src/Router/__Libraries/StellaOps.Router.Common/Identity/GatewayIdentityEnvelope.cs