Release binaries · Apache-2.0 · ID Partners

Federated enforcement.

Check each AI agent request against your access policy. OpenID AuthZEN is a standard API for authorisation decisions. These enforcement points use it from your gateway or Node.js service. They discover which policy decision point (PDP) handles each API. When the PDP denies access, it can return a challenge that tells the agent what to obtain before retrying.

Open the demo Read the overview Source on GitHub

Integrations: Kong, PingAccess, Envoy, Istio, agentgateway and Node.js
Decision API: OpenID AuthZEN 1.0
Access control: REST requests and Model Context Protocol (MCP) tool calls
PDP discovery: Resource metadata or OpenID Federation
Denied requests: Structured challenges when supplied by policy
PDP outages: Requests blocked by default; fail-open settings available per layer

why

Apply policy to every request

A policy enforcement point (PEP) intercepts requests and enforces the PDP's decision. The PDP evaluates your access policy for each request. You manage policy at the PDP and enforce it where requests enter your applications.

Check delegated authority

An agent acts on behalf of a customer. The PDP receives the agent's identity and the customer's delegated authority so policy can check both.

Set requirements by action

A balance enquiry and a payment can require different levels of approval. Evaluate each request against the policy for that action.

Return a challenge when access is denied

A PDP can require customer approval or a verified credential. Its challenge tells the agent what is required before it retries.

federation

Discover the PDP for each API

An API can publish its PDP address and access requirements in resource metadata. In federation mode, the enforcement point resolves that metadata through OpenID Federation. A trust anchor is a federation authority whose keys you configure as trusted. Its metadata policy can restrict which PDPs a member API uses.

PDP discovery selects the decision services. The gateway forwards approved requests with delegation details in headers.

Authoritative

Federation metadata

OpenID Federation 1.0 trust chain

OpenID Federation applies metadata policy through a verified trust chain. Federation operators can restrict the PDPs a resource uses and require organisation-wide policy checks. They can also set minimum authentication requirements.

Self-asserted

Resource metadata

RFC 9728 protected resource metadata

A resource can publish its PDPs and access requirements in RFC 9728 metadata. The enforcement point forwards these requirements to the PDP and identifies them as self-asserted.

Configured

Configured PDP

Configured PDP address

A configured PDP handles requests when discovery is disabled or no PDP is published for the resource. Only this PDP receives the configured API key.

Federation mode resolves metadata through a configured trust anchor.
An invalid trust chain blocks the request with a 503 response.
Allowlists restrict metadata and PDP addresses, including those named by a federation.
The PDP evaluates resource requirements alongside the request and token claims.
Metadata caches retain the last valid document for a limited time during an outage.
PDP metadata identifies supported evaluation endpoints, including batch support.

Layered policy

Apply organisation-wide policy before resource-specific policy. Each PDP must permit the request. An optional fail-open setting allows a layer to be skipped when its PDP is unavailable. A response header records the skipped layer. An explicit denial always blocks the request.

# Apply organisation policy, then resource policy
pdp_layers: "https://estate.example fail-open, resource"

Publish metadata through the gateway

The gateway publishes the resource's signed entity configuration and protected resource metadata. The federation controller manages metadata policy. The gateway can republish the resolved metadata for clients that use RFC 9728 discovery.

The demo shows how federation enrolment changes the published metadata without changing the gateway configuration.

request flow

How a request is authorised

Submit the request
The agent calls an API or an MCP tool with a delegated token.
Verify and map the request
The enforcement point verifies identity and checks any required proof of token possession. It maps the request to an AuthZEN evaluation.
Identify the PDP
The enforcement point discovers the PDP or uses its configured address. It calls each policy layer in order.
Evaluate the policy
The PDP evaluates the request using the delegation and resource requirements. It can return a denial with instructions for meeting those requirements.
Return the result
An approved request continues to the application. A denied request returns an error, with a challenge when the policy supplies one.

access challenges

Tell the agent what the policy requires

When a PDP denies access, it can include a challenge in the AuthZEN decision context. The enforcement point returns that challenge in the HTTP or MCP response. The project defines the challenge conventions below.

resource_authorisation

The customer grants the required access. The agent retries with a token that includes the requested scope.

identity_proofing

The customer supplies a verified credential, such as a mobile driving licence (mDL), to meet the policy's identity requirement.

authn

The customer signs in at the required authentication level. The response identifies the login requirement.

access approval · insufficient_scope

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
  error="insufficient_scope",
  scope="payments:approve"

{ "error":  "insufficient_scope",
  "scope":  "payments:approve",
  "reason": "Customer approval required" }

The response names the required scope. The agent can request customer approval before retrying.

identity verification · identity_verification_required

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
  error="identity_verification_required",
  doctype="org.iso.18013.5.1.mDL"

{ "error":   "identity_verification_required",
  "doctype": "org.iso.18013.5.1.mDL",
  "reason":  "Verified identity required" }

The response names the required credential. The agent can retry after the customer supplies it.

MCP response · JSON-RPC error

HTTP/1.1 200 OK

{ "jsonrpc": "2.0", "id": 7,
  "error": {
    "code": -32001,
    "message":
      "insufficient_scope scope=payments:approve",
    "data": { "authz_challenge": {
      "type":  "resource_authorisation",
      "scope": "payments:approve",
      "pep":   "mcp-edge" } } } }

The MCP error includes a structured challenge in data.authz_challenge.

integrations

Enforce decisions at your gateway or service

Install the integration for your gateway or add the SDK to a Node.js service. The configuration reference covers installation and settings for each component.

gateways/kong/authzen-pdp · Lua

Kong Gateway

A plugin for Kong routes and services, with support for DB-less deployments. It delegates MCP requests to the shared engine. When the engine is configured, it also handles REST decisions.

apt-get install -y unzip    # Required by Kong Enterprise images
luarocks install kong-plugin-authzen-pdp-0.4.2-1.all.rock

Configuration Download

gateways/pingaccess/authzen-pdp · Java

PingAccess

An Add-on SDK rule configured in the PingAccess console. It uses the identity validated by PingAccess and can verify a separate customer token. Tested with PingAccess 9.1.0.1 and Java 17 or later.

cp authzen-pdp-pingaccess-<version>.jar $PA_HOME/deploy/

Configuration Download

gateways/envoy · ext_authz

Envoy, Istio, agentgateway

Connect the gateway's external authorisation filter to the shared engine. The repository includes configurations for agentgateway and Istio.

docker pull ghcr.io/id-partners/coaz-pep:0.4.2

Configuration Download

sdk/node · TypeScript

Node.js

Express middleware for REST APIs and an authorisation guard for MCP tool calls. The SDK has no runtime dependencies and requires Node.js 22 or later. Unmatched routes are denied. Download the package from the GitHub release.

npm install ./id-partners-authzen-pep-<version>.tgz

Configuration Download

gateways/kong/sideband-pdp · Lua

Kong with PingAuthorize Sideband

Connect Kong to PingAuthorize's Sideband API with PDP discovery and ordered policy checks. PingAuthorize policy controls request mapping and the denial response.

apt-get install -y unzip    # Required by Kong Enterprise images
luarocks install kong-plugin-authzen-pdp-0.4.2-1.all.rock
luarocks install kong-plugin-sideband-pdp-0.4.2-1.all.rock

Configuration Download

demo · hosted, or docker

Compare discovery modes

Compare configured, resource-based and federation-based PDP discovery. The console shows the metadata retrieved and each policy decision. Optional configurations add Kong or PingAccess.

Open the demo

the engine

Shared authorisation engine

The shared coaz-pep engine processes authorisation requests for the gateway integrations. It provides an Envoy ext_authz service and an HTTP check API. The Node.js SDK can also delegate decisions to it.

Authorise individual tool calls

The engine reads MCP requests and evaluates tool calls using their declared mappings. Default mappings cover other supported methods. Unknown methods are denied. The COAZ Framework draft defines these mappings for AuthZEN.

Evaluate delegated authority

The evaluation includes the agent and the customer it represents. Policy can use the customer's access scope and authentication level when deciding whether to permit the request.

Verify tokens and proof of possession

The engine verifies token signatures and checks the issuer and audience. Demonstrating Proof of Possession (DPoP) binds a token to a client key. The engine verifies that proof when a token requires it.

Require security settings at startup

The engine requires token verification settings and a check-API token at startup. It also requires allowlists that restrict upstream and discovery addresses. A logged development override is available for demos.

# Container image for amd64 and arm64, signed with cosign, with an SBOM
docker run --rm -p 9191:9191 -p 9192:9192 \
  -e AUTHZEN_URL=https://pdp.bank.example/tenants/bank-a -e AUTHZEN_API_KEY=… \
  -e CHECK_API_TOKEN=… -e MCP_UPSTREAM_ALLOWLIST=https://mcp.bank.example \
  -e ACCESS_TOKEN_JWKS_URL=… -e ACCESS_TOKEN_ISSUER=… -e ACCESS_TOKEN_AUDIENCE=… \
  ghcr.io/id-partners/coaz-pep:0.4.2

See the coaz-pep reference for configuration and operational controls, including readiness checks, audit logs and metrics.

get started

Connect your gateway to a PDP

Review the demo
Open the hosted demo, or build it yourself with docker build -f site/Dockerfile .. Select Discover, then member, to compare resource metadata with federation policy.
Select an integration
Choose the integration for your gateway or Node.js service. Follow its installation guide in the configuration reference.
Connect a PDP
Set the PDP address using your integration's configuration reference. The shared engine uses AUTHZEN_URL. PingAuthorize integrations include a Go proxy and an in-process Server SDK servlet.
Configure discovery
Publish resource metadata or configure federation membership. Set the discovery allowlists to restrict which endpoints the enforcement point can contact.

docs/architecture.md

Architecture

Component responsibilities and the design of the authorisation flow.

one page

Overview

A visual explanation of PDP discovery and federation policy.

diagrams

Finding the PDP

The resolver, policy sets of several PDPs and their PIPs, the discovery modes, and federation trust chains.

design note

Resource policy from metadata

An API publishes its policy parameters, and one generic PingAuthorize policy enforces them.

docs/reference

Configuration reference

Configuration options, defaults and examples for each component.

docs/reference/demo.html

Demo guide

The demo's components and controls, and a walkthrough of the discovery scenarios.

CHANGELOG.md

Release notes

Release history and upgrade instructions. All components share one version.

SECURITY.md

Reporting a vulnerability

How to report a vulnerability privately and what to expect from the response.

specifications

Standards and project extensions

The project uses the specifications below. Its authzen_policy_set metadata field is a project extension. They are provisional pending a working-group profile.

OpenID AuthZEN 1.0 authorisation evaluation and PDP metadata at /.well-known/authzen-configuration
COAZ working-group drafts for authorisation mappings and MCP tool calls
RFC 9728 protected resource metadata, scopes_supported, signed_metadata
OpenID Federation 1.0 entity configurations, subordinate statements, trust chains, metadata policy
RFC 9470 step-up authentication challenges
RFC 9449 DPoP, sender-constrained tokens
RFC 8707 resource indicators used for discovery
RFC 8693 · RFC 9396 token exchange and rich authorisation requests
Envoy ext_authz external authorisation for Envoy, Istio and agentgateway
PingAccess Add-on SDK custom authorisation rules in PingAccess

ID Partners

Work with ID Partners

ID Partners is an Australian digital identity consultancy. We develop Federated Enforcement and help organisations deploy it. We can review your access requirements or implement policy enforcement in your environment.

assess

Architecture and policy workshop

Define access requirements for your AI agent use cases.
Identify enforcement points and the delegation model.

pilot

Pilot in your environment

Connect one application to policy enforcement in non-production.
Demonstrate approval and identity verification workflows.

run

Production deployment and support

Configure security controls and deploy across applications.
Work with a named engineer, with fixes shipped in the next release.

Talk to ID Partners Read the source