Skip to content

Protect Upstreams

Gateway is the protected-resource ingress. It validates inbound Caracal authority, checks replay and revocation, exchanges with STS, and forwards to configured upstreams only after safety checks pass.

Runtime

Property	Value
Port	`8081`
Health/readiness	`/health`, `/ready`
Metrics	`/metrics`, `/metrics.json`
Revocation reload	`POST /internal/revocations/reload`

Request Path

sequenceDiagram
  participant Client
  participant Gateway
  participant STS
  participant Upstream
  participant Audit
  Client->>Gateway: bearer token + X-Caracal-Resource
  Gateway->>Gateway: verify JWT, jti, revocation, binding, path, upstream safety
  Gateway->>STS: signed per-request exchange
  STS-->>Gateway: resource mandate
  Gateway->>Upstream: proxied request
  Gateway->>Audit: audit event or replay file

Deny-Before-Upstream Checks

Missing, malformed, oversized, expiring, replayed, revoked, or signature-invalid bearer token.
Missing X-Caracal-Resource.
No binding for (zone_id, resource).
Client-supplied X-Caracal-Client-ID.
Path traversal.
Operation (method and path) not declared on an enforced resource, or missing the operation’s required scope.
STS exchange failure or open STS circuit.
Unsafe upstream destination.

Configuration Highlights

Variable	Purpose
`STS_URL`	STS endpoint for exchange and JWKS.
`GATEWAY_STS_HMAC_KEY`	Signs Gateway exchange requests.
`MAX_REQUEST_BYTES`	Request body limit, default 10 MiB.
`UPSTREAM_HOST_ALLOWLIST`	Optional egress allowlist pinning upstreams to named hosts.
`JTI_FAIL_OPEN`	Forbidden in published modes.
`AUDIT_REPLAY_DIR`	Replay directory for audit events.

Next Step

Use Ingest Audit Evidence to understand how Gateway, STS, API, Coordinator, and Control evidence becomes searchable audit state.