Reference

Configuring the AuthZEN enforcement points

Each component page lists configuration options with their types and defaults. Complete examples show how to run the component. Screenshots cover Kong Manager and the PingAccess console.

The components

core/ · Gocoaz-pep

The shared authorisation service. Provides Envoy ext_authz and an HTTP check API. Handles federation resolution and token verification. Configure it through environment variables and per-route settings.

gateways/envoy/ · YAMLEnvoy · Istio · agentgateway

Connect coaz-pep through ext_authz. Pass per-route settings as context_extensions.

gateways/kong/ · LuaKong plugin

authzen-pdp delegates decisions to coaz-pep when coaz_url is set. REST routes can also run directly in Lua behind an authentication plugin. Configure it in Kong Manager or declarative configuration.

gateways/kong/sideband-pdp/ · LuaKong sideband plugin

sideband-pdp connects Kong to PingAuthorize's Sideband API. PingAuthorize policy controls request mapping and denial responses. Configure it in Kong Manager or declarative configuration.

gateways/pingaccess/ · JavaPingAccess rule

AuthZEN PDP: an Add-on SDK rule with the same settings, configured in the PingAccess console or admin API.

sdk/node/ · TypeScriptNode SDK

@id-partners/authzen-pep: an AuthZEN client, Express middleware, an MCP guard and a federation entity, configured as options in code.

demo/ · composeThe demo

Compare discovery modes against a stub federation and PDPs. The console shows metadata and decisions. Controls change the demo state without restarting the enforcement points.

Where each setting lives

The components share configuration concepts. Each component accepts settings through the mechanism listed below.

Component	Service-wide settings	Per-route settings	Screen
coaz-pep	environment variables	ext_authz `context_extensions`, or the `config` object of an HTTP check	none; its effects show in the demo console and in the documents it serves
Envoy · Istio · agentgateway	the coaz-pep deployment's environment	`context_extensions` in the filter, the EnvoyFilter, or the agentgateway policy `context`	none
Kong plugin	—	plugin `config` on a route or service	Kong Manager
Kong sideband plugin	—	plugin `config` on a route or service	Kong Manager
PingAccess rule	—	the rule's configuration, attached to an application's API policy	the PingAccess console
Node SDK	client options	middleware, guard and per-call options	none

Settings every PEP shares

These settings control shared enforcement behaviour. Each component page gives its supported settings and defaults.

Setting	What it decides
`authzen_url` / `AUTHZEN_URL`	The static PDP. It decides when discovery is off or a resource publishes nothing, it is always permitted, and it is the one PDP that receives the configured API key.
`style`	`rest` maps an HTTP request to an evaluation; `mcp` treats the route as an MCP edge and authorises JSON-RPC.
`require_token`	Deny a request that carries no readable access token.
`require_dpop`	Enforce the RFC 9449 sender constraint. Kong and PingAccess delegate the proof check to coaz-pep.
`require_user_login`, `stepup_scope`, `stepup_action`	Login and access-scope challenges: require an authenticated end user and an approved scope for a named action.
`mcp_upstream_url`	The MCP server whose `tools/list` declares the COAZ mappings. Setting it enables per-tool-call authorisation.
`pdp_discovery` / `PDP_DISCOVERY`	`off`, `authzen`, `resource`, or (coaz-pep only) `federation`. How the PDP is found.
`resource`	The protected resource's identifier, RFC 8707. The key discovery starts from.
`pdp_allowlist`, `resource_metadata_allowlist`	What discovery may reach: which PDPs a document may name, which resources may be looked up.
`forward_access_token`	Hand the PDP the raw token as `context.access_token`. Only over a TLS, authenticated PDP connection.
`pdp_layers`, `fail_mode`	The ordered PDPs to ask, every one of which must permit, and what a layer does when its PDP cannot be reached.
`federation_entity_url` / `FEDERATION_ENTITY_ID`	Serve the resource's two well-known documents: coaz-pep holds the key; Kong and PingAccess relay from it.
`coaz_defaults`, `legacy_subject_identity`	Decide every MCP method with the COAZ binding's default mappings where nothing is declared - on by default, `false` opts out; keep sending the pre-AuthZEN `subject.identity` field.
`allow_insecure` / `PEP_ALLOW_INSECURE` / `allowInsecure`	Start, or accept a configuration, despite missing security settings - logged every time. Every PEP refuses without it. Development and demos only.

Configuration screens

Kong Manager and the PingAccess console provide configuration forms. Their reference pages include screenshots. The other components use files or code. Their pages show configuration examples and the resulting logs or responses.

Kong Manager showing the authzen-pdp plugin's configuration — **Kong Manager**, the plugin as Kong shows it. Every field on the Kong page.

The PingAccess console showing the AuthZEN PDP rule's form — **The PingAccess console**, the rule's form. Every field on the PingAccess page.

Conventions

Allowlists are lists of URL prefixes. An entry matches on scheme, host and port at a path boundary: https://pdp.example admits https://pdp.example/tenants/a and refuses https://pdp.example.evil.test. A URL whose path the server could resolve somewhere other than where it reads is refused before it is matched: a dot segment (.. or ., literal or as %2e, also with a parameter after it as in ..;, which Tomcat and older Jetty treat as ..), an encoded slash or backslash (%2f, %5c), a literal backslash or a double-encoded one of these (%252e), so https://pdp.example/tenants/a/../b never passes for tenant a. Comma-separated in environment variables, arrays in plugin config and code.
Layer lists are ordered. An entry is static, resource, or a PDP identifier, optionally followed by a space and fail-open or fail-closed: https://estate.example fail-open, resource. Comma-separated in environment variables and Envoy settings, arrays elsewhere.
Booleans in per-route settings are the strings "true" and "false", because ext_authz context_extensions carries only strings. Kong and PingAccess use real booleans; the Node SDK uses true and false.
Durations: Go durations in environment variables (15s, 5m), seconds in Kong and PingAccess, milliseconds in the Node SDK.
Well-known paths: RFC 9728 inserts its segment after the host and keeps the identifier's path after it (/.well-known/oauth-protected-resource/bank); AuthZEN does the same (/.well-known/authzen-configuration/tenants/bank-a); OpenID Federation appends its segment to the identifier's path (/bank/.well-known/openid-federation).
Fail closed is the default everywhere: a PDP that cannot be reached is a 503 (Envoy family, Kong, PingAccess) or a pdp_error verdict rendered as 502 (Node). fail_mode and a layer's own modifier are the only ways to change that, and neither ever turns a deny or a refusal into a permit.