The Kong sideband plugin

sideband-pdp is a Kong plugin that enforces through PingAuthorize's Sideband API — the request Kong will forward to /sideband/request in the access phase, the upstream's response to /sideband/response in the response phase — and finds the PDPs it calls from the resource it protects: the resource's RFC 9728 metadata, or, with the switch, a federation resolve endpoint. It is the Kong plugin's discovery, layers and failure rules from the modules the two share, in front of a PDP protocol where the policy owns the request mapping and the shape of a deny. Every knob is plugin configuration on a route or service. Version 0.4.0; Kong Gateway 3.4 or later, 3.9 or later recommended.

Install

DB-less: mount both plugin directories and enable this one. The discovery and contract modules are authzen-pdp's, required by name (kong.plugins.authzen-pdp.discovery, …contract), so that directory must be on the package path whether or not authzen-pdp is enabled. The rock, kong-plugin-sideband-pdp-0.4.0-1.all.rock on the release, depends on kong-plugin-authzen-pdp 0.4.0 for them: install that one first.

# kong.conf, or environment
KONG_PLUGINS=bundled,sideband-pdp
KONG_LUA_PACKAGE_PATH=/opt/?.lua;;
KONG_LUA_SSL_TRUSTED_CERTIFICATE=system,/etc/kong/pingauthorize.pem   # PingAuthorize's self-signed certificate

# compose
kong:
  image: kong:3.9
  environment:
    KONG_DATABASE: "off"
    KONG_DECLARATIVE_CONFIG: /kong/kong.yml
    KONG_PLUGINS: bundled,sideband-pdp
    KONG_LUA_PACKAGE_PATH: /opt/?.lua;;
    KONG_PROXY_LISTEN: 0.0.0.0:8000
    KONG_ADMIN_LISTEN: "off"
  volumes:
    - ./kong/kong.yml:/kong/kong.yml:ro
    - ../gateways/kong/authzen-pdp:/opt/kong/plugins/authzen-pdp:ro      # discovery.lua, contract.lua
    - ../gateways/kong/sideband-pdp:/opt/kong/plugins/sideband-pdp:ro
  ports:
    - "8000:8000"

The plugin in Kong Manager

Kong Manager draws the form from schema.lua exactly as it does for authzen-pdp — every field below, defaults pre-filled, the required ones marked: service_url, shared_secret and secret_header_name. The Kong page shows what that looks like; this plugin has not been captured separately.

Every field

Grouped as they are used, not as the schema lists them. Types are the schema's; ref marks a field that accepts a Kong vault reference such as {vault://env/paz-secret} instead of a literal, and enc one Kong encrypts at rest where it has a keyring. The first group is Ping's ping-auth plugin's configuration, names and defaults unchanged, so a route configured for that plugin ports over by changing the plugin name.

PingAuthorize and its secret

The route

PDP discovery

The resolver switch

What the switch is, and is not: the resolver's word, taken on transport. The resolve response is a JWT this plugin cannot verify — no JOSE verifier is available to a Kong plugin — so it is decoded, not verified. The plugin checks what it can: the response's typ is resolve-response+jwt, its sub is the resource asked about, it has not expired, and what it lists are PDP identifiers. The trust is TLS to a URL the operator configured, exactly the trust placed in service_url. That is a weaker claim than coaz-pep's federation mode, which walks the chain and verifies every signature to an anchor key it holds — which is why the mode, X-PDP-Source and context.resource_metadata_source all say federation-resolver, never federation. A route that needs the stronger claim belongs behind coaz-pep.

Layers and their rules

Credentials

Safety and compatibility

Refused at configuration time, each with a message saying which: pdp_discovery: federation-resolver without federation_resolve_url or without federation_trust_anchor; a service_url that is neither an http or https URL with a host nor a vault reference; and, unless allow_insecure, discovery without pdp_allowlist, pdp_discovery_insecure: true, verify_service_certificate: false, and an http federation_resolve_url. The old mode name, federation, is refused.

REST routes only. A plugin with a response phase makes Kong buffer the whole upstream response on every route it is on, filter_response on or off. That is incompatible with SSE, so an MCP route belongs behind authzen-pdp and coaz-pep. Kong also refuses to load a plugin that has both a response phase and a header filter, which is why the X-PDP-* headers are set in access and on the plugin's exits rather than in a later phase. Accept-Encoding is dropped from the proxied request so the body the response phase reads is one the policy provider can read.

Responses Kong would not show it. Kong runs the response phase only under buffered proxying, which it turns off for a websocket upgrade on every release and for HTTP/2 before 3.9. Where any layer filters responses, such a request is refused with a 400 before any PDP is asked; a route that filters nothing lets it through, marked. On Kong 3.9 and 3.15 an HTTP/2 request on a filtering route is served and filtered.

Plugin order. Priority 999, after Kong's authentication plugins and before ip-restriction (990), acl (950) and rate-limiting (910). See the Kong page for what that costs and the Enterprise ordering that changes it.

What PingAuthorize is sent

• The URL Kong routed on: its scheme, the Host, its own port and the normalised path its router matched, escaped for the wire, with the query normalised as Ping did. Never X-Forwarded-*, which Kong honours from any client in trusted_ips — one there could have DELETE /admin/users/1 judged as /public/status.
• The body, whole, up to max_request_body_size, or a 413.
• Every header and query argument, up to 1,000 of each, or a 431 or 414.
• No client X-Auth-*: those are removed from the payload and from the request to the upstream; a layer's rewrite may add them.

A permit must have the permit's shape — method and url strings, headers a list of single-pair objects, body a string when present. Anything that is neither that nor a relayable response, a 2xx {} included, is a refusal.

Complete configurations

A REST API with discovery, a published layer and per-PDP credentials

_format_version: "3.0"
services:
  - name: bank-api
    url: http://bank-api:8070
    routes:
      - name: bank
        paths: ["/bank"]
        strip_path: true
    plugins:
      - name: sideband-pdp
        config:
          service_url:        "{vault://env/paz-url}"          # the static PDP; the one PDP called with shared_secret
          shared_secret:      "{vault://env/paz-secret}"
          secret_header_name: CLIENT-TOKEN
          pep_label: "PEP#2 (Bank API edge)"
          pdp_discovery: resource
          resource: https://api.bank.example
          pdp_allowlist: ["https://pdp.bank.example", "https://pdp.estate.example"]
          resource_metadata_allowlist: ["https://api.bank.example"]
          pdp_credentials:
            - pdp: https://pdp.bank.example/tenants/bank
              shared_secret: "{vault://env/bank-pdp-secret}"
            - pdp: https://pdp.estate.example
              shared_secret: "{vault://env/estate-pdp-secret}"
              secret_header_name: X-Estate-Token
          pdp_layers: ["resource"]                              # what the document publishes, then its own PDP
          fail_mode: closed

A route that takes the federation resolver's word

      - name: sideband-pdp
        config:
          service_url:        "{vault://env/paz-url}"
          shared_secret:      "{vault://env/paz-secret}"
          secret_header_name: CLIENT-TOKEN
          pdp_discovery: federation-resolver
          resource: https://member.bank-federation.example
          federation_resolve_url: https://anchor.bank-federation.example/resolve
          federation_trust_anchor: https://anchor.bank-federation.example
          pdp_allowlist: ["https://pdp.bank-a.example", "https://pdp.estate.example"]
          pdp_credentials:
            - pdp: https://pdp.estate.example
              shared_secret: "{vault://env/estate-pdp-secret}"

An estate gate the route can live without

          pdp_layers: ["static fail-open request-only", "resource"]   # service_url first, as a gate; then the resource's stack
          fail_mode: closed

What it puts on the wire

What it does not do

• Shape a challenge. A deny is the policy's HTTP. If the policy answers a flat 403, the client gets a flat 403. The challenge vocabulary the other PEPs render in code is, on this route, a contract the policy honours.
• Verify a token, a DPoP proof, or a chain. No JOSE. The token reaches PingAuthorize in the authorization header, where policy can validate it; DPoP and COAZ are what authzen-pdp delegates to coaz-pep, and an MCP route belongs there.
• Read signed_metadata in an RFC 9728 document; coaz-pep does.
• Serve the resource's federation face. authzen-pdp's federation_entity_url relays the two well-known documents from coaz-pep; put that plugin on the route for them.

The plugin is tested with busted against a mocked Kong (gateways/kong/spec/sideband-pdp_spec.lua, with the discovery rules in discovery_spec.lua) under the same coverage floor as authzen-pdp, and was run through Kong 3.7, 3.9 and 3.15 DB-less with both plugin directories mounted, against a stub that plays the sideband endpoints and an echoing upstream: the forwarded-path, HTTP/2, Upgrade and withheld-response behaviour above is what those runs showed.

Upgrading from 0.1

• pdp_discovery: federation is now federation-resolver, and X-PDP-Source says so; the old name is refused.
• Discovery needs pdp_allowlist; pdp_discovery_insecure, verify_service_certificate: false and an http resolver need allow_insecure.
• A 401 or 403 from PingAuthorize is a refusal, closed even on a fail-open layer; a 429 no longer blocks the PDP for the worker.
• The URL sent is the one Kong routed on, not X-Forwarded-*.
• Oversized bodies, too many headers or query arguments, and Upgrade (or, before Kong 3.9, HTTP/2) on a filtering route are refused rather than judged in part or not filtered at all.
• A response-phase failure is a 502 with the upstream's headers withheld.
• The rock is kong-plugin-sideband-pdp-0.4.0-1, depending on kong-plugin-authzen-pdp 0.4.0.