Router Authority Enforcement Runbook

This runbook documents operational semantics for gateway-enforced authorization and signed user-identity propagation in Stella Router deployments.

Scope

Router gateway as centralized policy decision point (PDP).
Authority-driven effective claims.
Signed identity envelope propagation to webservices using Router trust mode.

Required Configuration

Gateway-side:

Gateway__Auth__Authority__Issuer
Gateway__Auth__Authority__RequireHttpsMetadata
Router__OnMissingAuthorization

Service-side (per service Router section):

Router__Enabled
Router__AuthorizationTrustMode
Router__IdentityEnvelopeSigningKey
Router__IdentityEnvelopeClockSkewSeconds

Identity transport headers emitted by gateway:

X-StellaOps-Identity-Envelope
X-StellaOps-Identity-Envelope-Signature
X-StellaOps-Identity-Envelope-Alg
X-StellaOps-Identity-Envelope-Kid
X-StellaOps-Identity-Envelope-Iat
X-StellaOps-Identity-Envelope-Exp

Trust Modes

ServiceEnforced

Service enforces its local policies.
Gateway envelope is optional for service authorization.

Hybrid

Service accepts gateway envelope when present.
Service can fall back to local checks for compatibility.

GatewayEnforced

Service requires valid signed gateway envelope.
Missing/invalid envelope is fail-closed (403/401 based on service policy).
Use for centralized authorization rollout after verification.

Key Rotation Procedure

Rotate Authority/gateway signing material using the Authority key-rotation SOP:

docs/modules/authority/operations/key-rotation.md

Update Router__IdentityEnvelopeSigningKey for gateway and services.
Restart gateway and services in wave order (gateway first).
Validate with targeted tests and route smoke.

Authority Outage and Fallback

If Authority is degraded/unreachable:

Keep gateway running with last known effective claim cache.
For critical service continuity, temporarily switch affected services:

Router__AuthorizationTrustMode=Hybrid

If envelope verification is disrupted by key mismatch, switch to ServiceEnforced only as emergency fallback.
Record incident window and restore target mode (GatewayEnforced or Hybrid) after recovery.

Compose Toggle Examples

Global gateway mode:

$env:ROUTER_GATEWAY_CONFIG = "./router-gateway-local.json"
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d

Emergency compatibility fallback (example service):

$env:SCANNER_ROUTER_ENABLED = "true"
$env:Router__AuthorizationTrustMode = "Hybrid"
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d scanner-web

Verification Checklist

Gateway route smoke has 500=0.
OpenAPI operations expose x-stellaops-gateway-auth.
Envelope spoofing tests pass (IdentityHeaderPolicyMiddlewareTests).
Authority refresh tests pass (AuthorityClaimsRefreshServiceTests).

2.9 KiB Raw Blame History