Skip to main content

Gateway Integration Patterns

The current v0.1 gateway pattern keeps TrustPlane Auth simple:

TrustPlane Auth can protect an API directly through the adapter. Existing gateways can route protected traffic through that adapter, but the adapter remains the verifier and enforcement component. The upstream API remains unchanged and still owns business authorization and RBAC.

One adapter can protect many routes using --route-policy-mode=request. Route policy decides which sources may call which routes; replay state decides whether the proof has already been consumed; signed trust and policy bundles decide which issuers, keys, sources, and freshness rules are trusted.

The protected upstream must not be reachable directly by untrusted callers. If callers can bypass the adapter and hit the upstream, the gateway pattern is not enforcing the boundary.

Kubernetes Gateway API / HTTPRoute​

Use Gateway API or ingress routing to send protected paths to the adapter Service. The adapter's upstream points to the internal upstream Service.

Typical shape:

  • Protected HTTPRoute paths route to the trustplane-adapter Service.
  • The adapter verifies TrustPlane headers, route policy, replay, and source policy.
  • The adapter forwards verified requests to the internal upstream Service.
  • NetworkPolicy prevents untrusted callers from reaching the upstream Service directly.
  • Signed trust and policy bundles are mounted into the adapter, and replay storage matches the adapter replica topology.

This keeps Kubernetes routing responsible for traffic placement while TrustPlane Auth remains responsible for proof-bound request enforcement.

Envoy​

For Envoy-fronted APIs, route the protected virtual host or path cluster to the adapter. The adapter forwards to the upstream after local verification.

Typical shape:

  • Envoy receives external traffic and matches the protected host or path.
  • Envoy routes that traffic to a cluster that points at the adapter.
  • The adapter verifies the request and proxies only verified traffic to the upstream cluster or service.
  • Direct network access to the upstream is restricted so callers cannot skip the adapter.

Native Envoy ext_authz verify mode is future work, not the current v0.1 model.

NGINX​

For NGINX-fronted APIs, configure the protected location blocks to proxy to the adapter. The adapter proxies to the upstream after verification.

Typical shape:

  • NGINX matches protected locations.
  • NGINX proxies those locations to the adapter endpoint.
  • The adapter verifies TrustPlane proof, route policy, replay, and source policy.
  • The adapter forwards verified requests to the upstream.

NGINX auth_request verify endpoint mode is future work, not the current v0.1 model.

Kong​

For Kong-fronted APIs, route the protected Service or Route path to the adapter. The adapter then forwards verified requests to the upstream.

Typical shape:

  • Kong matches protected routes.
  • The route or service target sends protected traffic to the adapter.
  • The adapter verifies locally and forwards to the upstream after enforcement.
  • The upstream is not exposed as a separate direct route for untrusted callers.

A native Kong plugin or serverless pre-function verify mode is future work, not the current v0.1 model.

Use The Current Adapter Contract​

Gateway examples should use the current adapter contract:

  • Protected traffic routes through trustplane-adapter.
  • The adapter verifies proof-bound requests locally.
  • Signed trust and policy bundles define trusted issuers, sources, routes, and freshness.
  • Replay protection prevents the same proof from being accepted twice.
  • The upstream is reachable only through the protected boundary.
  • The upstream keeps business authorization and RBAC.

If a gateway pattern preserves those properties, it fits the TrustPlane Auth v0.1 deployment model.

Advanced Integration Options​

Some teams may eventually want the gateway itself to call a TrustPlane verification service or run a gateway-native extension. Examples include Envoy ext_authz, NGINX auth_request, Kong plugins, backend token exchange, or Control-managed provider onboarding.

Those are useful future integration options, especially for large gateway fleets. The current preview path stays simpler: route protected traffic through the adapter and keep the adapter as the verifier.