The Kong sideband plugin

sideband-pdp enforces decisions from PingAuthorize's Sideband API. It sends requests to /sideband/request and upstream responses to /sideband/response. PDP discovery uses resource metadata or a federation resolver endpoint. The plugin shares discovery and policy-layer code with authzen-pdp. PingAuthorize policy controls request mapping and denial responses. Version 0.4.2 requires Kong Gateway 3.4 or later; 3.9 or later is 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.2-1.all.rock on the release, depends on kong-plugin-authzen-pdp 0.4.2 for them: install that one first. On Kong's Enterprise images, apt-get install -y unzip before either: they ship without it, and luarocks needs it to open a rock.

# 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

Fields are grouped by function. Types match the schema. 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

The plugin trusts the configured resolver through TLS. It decodes the resolve-response JWT without verifying its signature. It checks typ, sub, expiry and the listed PDP identifiers. The mode and source fields use federation-resolver to identify this behaviour. Use coaz-pep's federation mode when the enforcement point must verify the full trust chain against configured anchor keys.

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 path is the client's, or with policy_path: resource the upstream's less the resource's.
• The body, whole, up to max_request_body_size, or a 413 request_too_large.
• Every header and query argument, up to 1,000 of each, or a 413 request_too_large for headers and a 400 invalid_request for arguments.
• No client X-Auth-*: those are removed from the payload and from the request to the upstream; a layer's rewrite may add them.
• Two headers the plugin asserts: X-PEP-Method, and X-AuthZEN-Resource when the route names a resource. A client's copies are dropped from the payload and from the request to the upstream; a layer's answer cannot change them for the next layer, and they never reach the upstream.

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 using a federation resolver

      - 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

Component responsibilities

• PingAuthorize policy supplies the denial response. Configure it to return the required status and headers, including any authorisation challenge.
• PingAuthorize receives the token in the authorization header, where policy can validate it. This plugin provides no JOSE verification. Use authzen-pdp with coaz-pep for MCP request authorisation and DPoP verification.
• Use coaz-pep to verify signed_metadata in RFC 9728 documents.
• Use authzen-pdp with federation_entity_url on the metadata routes to relay the resource's well-known documents from coaz-pep.

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.2-1, depending on kong-plugin-authzen-pdp 0.4.2.