The Kong plugin

authzen-pdp checks Kong requests against an AuthZEN PDP. Set coaz_url to delegate decisions to coaz-pep. This is required for MCP routes. REST routes can also run directly in Lua using claims verified by an authentication plugin. Configure the plugin on a route or service through Kong Manager or declarative configuration. Version 0.4.2 requires Kong Gateway 3.4 or later. Kong 3.9 or later supports reading request bodies buffered to disk.

Install

DB-less: mount the plugin directory and tell Kong about it. The module path Kong looks for is kong.plugins.authzen-pdp.handler. Or install the rock the v0.4.2 release carries: luarocks install kong-plugin-authzen-pdp-0.4.2-1.all.rock. Kong's Enterprise images (kong/kong-gateway) ship without unzip, which luarocks needs to open a rock: apt-get install -y unzip first, as root.

# kong.conf, or environment
KONG_PLUGINS=bundled,authzen-pdp
KONG_LUA_PACKAGE_PATH=/opt/?.lua;;

# compose: the demo's Kong, complete
kong:
  image: kong:3.9
  environment:
    KONG_DATABASE: "off"
    KONG_DECLARATIVE_CONFIG: /kong/kong.yml
    KONG_PLUGINS: bundled,authzen-pdp
    KONG_LUA_PACKAGE_PATH: /opt/?.lua;;
    KONG_PROXY_LISTEN: 0.0.0.0:8000
    KONG_ADMIN_LISTEN: "off"
    KONG_LOG_LEVEL: notice
    KONG_PROXY_ERROR_LOG: /dev/stderr
  volumes:
    - ./kong/kong.yml:/kong/kong.yml:ro
    - ../gateways/kong/authzen-pdp:/opt/kong/plugins/authzen-pdp:ro
  ports:
    - "8000:8000"

Before Kong 3.9, kong.request.get_raw_body cannot read back a body Kong buffered to disk, so a request body larger than client_body_buffer_size (8 KiB by default) is refused with a 413 rather than authorised unread; raise nginx_http_client_body_buffer_size on those releases. A PDP with a private or self-signed certificate is trusted through KONG_LUA_SSL_TRUSTED_CERTIFICATE=system,/path/to/ca.pem, not by turning verification off.

How a route is decided

On an MCP route every request goes to coaz-pep - every JSON-RPC method, the SSE GET, the session DELETE - once its body has been read whole and parsed as exactly one JSON-RPC object. What the plugin refuses before asking is in the wire table.

The plugin in Kong Manager

Kong Manager draws the plugin's form from schema.lua, so every field below appears here with its default pre-filled, and the required ones marked. Captured from the demo's Kong with Kong Manager OSS turned on (KONG_ADMIN_GUI_LISTEN), against the 0.3.0 schema: 0.4.0 adds access_token_verified_upstream, allow_insecure, max_request_body_size and user_token_subject to the same form, 0.4.2 the three timeouts and decision_deadline_ms, and a configuration the schema refuses is refused there with the messages below.

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/authzen-url} instead of a literal, and enc one Kong encrypts at rest where it has a keyring.

The PDP

The route

Delegation to coaz-pep

PDP discovery

On a route decided in Lua. With coaz_url set, coaz-pep discovers under its own settings and these fields play no part.

Layers and fail mode

Safety and compatibility

What the schema refuses

A configuration the plugin must not run with fails at load time, in Kong Manager, the Admin API and a DB-less file alike. allow_insecure relaxes the last five; the first four are things the plugin cannot do at all.

Complete configurations

A REST API decided in Lua, behind Kong's jwt plugin, with discovery and layers

_format_version: "3.0"
services:
  - name: bank-api
    url: http://bank-api:8070
    routes:
      - name: bank
        paths: ["/bank"]
        strip_path: true
    plugins:
      - name: jwt                                              # priority 1450: runs first
        config:
          claims_to_verify: ["exp"]
      - name: authzen-pdp
        config:
          authzen_url:     "{vault://env/authzen-url}"        # the static PDP, always permitted
          authzen_api_key: "{vault://env/authzen-api-key}"
          pep_label: "PEP#2 (Bank API edge)"
          style: rest
          require_token: true
          access_token_verified_upstream: true               # the jwt plugin validated Authorization
          stepup_scope: "banking:payments:transfer"
          pdp_discovery: resource
          resource: https://api.bank.example
          pdp_allowlist: ["https://pdp.bank.example", "https://estate-pdp.bank.example"]
          resource_metadata_allowlist: ["https://api.bank.example"]
          pdp_metadata_ttl: 300
          forward_access_token: true
          pdp_layers: ["https://estate-pdp.bank.example fail-open", "resource"]
          fail_mode: closed
          federation_entity_url: http://coaz-pep:9192       # the two well-known documents, relayed
          legacy_subject_identity: false

A REST API coaz-pep decides, with DPoP and a logged-in user

      - name: authzen-pdp
        config:
          authzen_url:     "{vault://env/authzen-url}"
          authzen_api_key: "{vault://env/authzen-api-key}"
          pep_label: "PEP#2 (Bank API edge)"
          style: rest
          require_token: true
          require_dpop: true                                  # coaz-pep checks the proof
          require_user_login: true                            # coaz-pep verifies X-User-Token
          stepup_scope: "banking:payments:transfer"
          coaz_url: https://coaz-pep.internal:9192
          coaz_api_key: "{vault://env/coaz-api-key}"
          resource: https://api.bank.example                  # coaz-pep keys discovery off it
          pdp_layers: ["https://estate-pdp.bank.example fail-open", "resource"]

An MCP edge

  - name: bank-mcp
    url: http://bank-mcp:8090
    routes:
      - name: mcp-edge
        paths: ["/mcp"]
        strip_path: false
    plugins:
      - name: authzen-pdp
        config:
          authzen_url:     "{vault://env/authzen-url}"
          authzen_api_key: "{vault://env/authzen-api-key}"
          pep_label: "PEP#1 (MCP edge)"
          style: mcp
          require_token: true
          require_user_login: true
          coaz_url: https://coaz-pep.internal:9192            # every request of the route is decided there
          coaz_api_key: "{vault://env/coaz-api-key}"
          mcp_upstream_url: http://bank-mcp:8090/mcp
          max_request_body_size: 1048576

The demo's Kong, as it runs

The whole of demo/kong/kong.yml: one route in front of the plain stub, discovering the PDP from that resource's RFC 9728 document. It decides natively on the demo's unsigned tokens and discovers over plain http, so it sets allow_insecure, and Kong logs as much at startup.

_format_version: "3.0"

services:
  - name: plain-resource
    url: http://stubs:9004
    routes:
      - name: bank
        paths: ["/bank"]
        strip_path: true
    plugins:
      - name: authzen-pdp
        config:
          authzen_url: http://stubs:9002
          authzen_api_key: static-pdp-key
          pep_label: "Kong (resource discovery)"
          style: rest
          require_token: true
          pdp_discovery: resource
          resource: http://stubs:9004
          pdp_discovery_insecure: true
          resource_metadata_allowlist: ["http://stubs:9004"]
          pdp_allowlist: ["http://stubs:9002", "http://stubs:9008"]
          forward_access_token: true
          allow_insecure: true

Plugin order

Priority 1000. Kong runs a higher number first, so its authentication plugins - jwt 1450, oauth2 1400, key-auth 1250, openid-connect 1050 - run before this one, which is what access_token_verified_upstream relies on. ip-restriction 990, request-size-limiting 951, acl 950, rate-limiting 910 and request-transformer 801 run after: a request they would refuse still costs a PDP call, and a burst reaches the PDP before any limit is counted. On Kong Enterprise, dynamic ordering puts a plugin in front - ordering: { before: { access: ["authzen-pdp"] } } on the rate-limiting plugin.

What it puts on the wire

A step-up, from a PDP that permits with step_up_required, step_up_scope: "payments:approve" and the reason Payment over the threshold. (one of the shared vectors, on a route with the default pep_label and no resource):

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="payments:approve"
Content-Type: application/json

{"status":403,"error":"insufficient_scope","error_description":"Payment over the threshold.",
 "scope":"payments:approve",
 "authz_challenge":{"type":"resource_authorisation","scope":"payments:approve",
                    "reason":"Payment over the threshold.","pep":"kong-pep"}}

An RFC 9470 refusal, a deny with context.error: "insufficient_user_authentication", acr_values: "urn:bank:acr:strong" and max_age: 300, is a 401 with WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="urn:bank:acr:strong", max_age="300", and both parameters in the body and in authz_challenge (type authn). max_age is a whole number of seconds from 0 to 2³¹-1, 0 included; anything else is left out.

What is delegated, and why

• Token verification. A Kong plugin has no JOSE verifier, and reading a JWT's claims without checking its signature proves nothing about who sent it. With coaz_url, coaz-pep verifies the access token and X-User-Token; without it, an auth plugin in front must, and the route says so.
• DPoP. Comparing the proof's JWK thumbprint to cnf.jkt without checking the proof's signature proves nothing, because the proof carries the very JWK being compared. The proof travels in the check request; the separate /v1/dpop/verify call is gone.
• MCP. Mappings are CEL-shaped and discovered from tools/list; one implementation of the profile for every gateway, so two renderings of one decision cannot drift. The plugin parses the JSON-RPC strictly first and relays the engine's answer verbatim.
• Federation. Same reason as DPoP: no signature verification, no trust chain. With coaz_url, coaz-pep's discovery, federation included, decides where the PDP is.
• The metadata publisher. The plugin cannot sign, so it relays the two well-known documents from coaz-pep, which holds the key.

The plugin has busted tests against a mocked Kong in gateways/kong/spec/. The test suite enforces minimum coverage. Integration runs cover Kong 3.7, 3.9 and 3.15 in DB-less mode against stub PDP and coaz-pep services.

Upgrading from 0.3

• An MCP route needs coaz_url, and every request on it now goes to coaz-pep. Upgrade coaz-pep with the plugin.
• coaz_defaults defaults to true; false keeps the old pass-through.
• With coaz_url set, coaz-pep decides the whole request, REST routes included, and the route's own discovery settings no longer apply there.
• Without coaz_url, set access_token_verified_upstream (with an openid-connect or jwt plugin in front) or allow_insecure. X-User-Token is no longer read there, so context.user_scope is no longer sent.
• coaz_url needs coaz_api_key; discovery needs pdp_allowlist; the weakening flags need allow_insecure.
• A 3xx or 4xx from a PDP is a refusal, closed even on a fail-open layer; a metadata outage serves the last good document for up to one more TTL, then fails the layer under its rule.
• REST patterns are anchored to the routed path, and an unreadable payment or account body is refused.
• X-PDP-Fail-Open names identifiers only.
• The rock is kong-plugin-authzen-pdp-0.4.2-1, from the v0.4.2 tag.