The PingAccess rule

AuthZEN PDP is an Add-on SDK rule: the PingAccess counterpart of the Kong plugin, sending the PDP the same AuthZEN request and rendering the same challenges, so a client cannot tell from a deny which gateway said no. Token and actor-claim extraction, RFC 9470 challenges, REST mapping, RFC 9728 and AuthZEN discovery and policy layers are native Java; DPoP verification and every decision on an MCP route are delegated to coaz-pep, as Kong does. It is configured in the PingAccess console or through the admin API, spelled the same as every other PEP here.

Not to be confused with PingAccess's built-in PingAuthorize Policy Decision Access Control and PingAuthorize Access Control rules. Those speak PingAuthorize's own APIs to PingAuthorize alone. This one speaks AuthZEN 1.0 to any conformant PDP, discovers which PDP decides for a resource, and returns resolvable challenges.

Upgrading to 0.4.0

0.4.0 refuses things 0.3 let through. A rule saved under 0.3 may fail to configure under 0.4.0, and every request through it is then a 500 deny until it is fixed, so check each rule before deploying the jar.

• style: mcp needs coaz_url, and every request on an MCP route goes to coaz-pep, not only tools/call. Nothing passes on a token alone.
• coaz_defaults is on by default: every MCP method is governed by the COAZ binding's default table.
• An MCP body the rule cannot read one way only is refused with a JSON-RPC error: a batch, invalid UTF-8, a BOM, trailing data, a case-variant member, a compressed or partial body.
• An access token PingAccess did not validate is a 401: protect the application, or tick allow_insecure for development.
• X-User-Token needs a JWKS and an audience. Without a JWKS it is ignored, and require_user_login without one is refused. The token must carry exp, sub and the audience.
• X-User-Token counts only as the principal's own login: its sub is the access token's subject, and it is neither the access token itself nor a delegated token. A route where staff approve for a customer sets user_token_subject: pdp, and the PDP judges whose login it is.
• The PDP gets coaz-pep's user context: user_scope, token_aud, user_acr, user_sub, user_iss, and authorization_details with the consented amount and creditor.
• Missing security settings are refused, not warned about: an API key or forwarded token over http, coaz_url without its key, discovery without pdp_allowlist, pdp_discovery_insecure, pdp_ssl_verify off. allow_insecure lets a development rule start with them, and logs each one.
• Every URL must be one the rule can call: absolute http or https with a host. http://authzen_pdp:8080 is refused - an underscore is not legal in a host name.
• A fail-open layer opens on an outage only. A 4xx, a redirect or an answer that is not a decision is a refusal, and closed.
• A resource whose metadata cannot be read is not the static PDP's. Only a resource that publishes nothing (a 404, or a document naming no PDP) falls back to authzen_url; an outage, a refusal or a document that does not validate serves the last good copy for up to one more TTL, then fails the resource layer by its mode.
• A payment needs a readable body with a from_account and a numeric amount, or it is a 400 before any PDP is asked.

Build and install

The Add-on SDK is on no public Maven repository. Take it from a PingAccess install or, without one, from the public Docker image, which needs no licence to pull.

cd gateways/pingaccess/authzen-pdp
id=$(docker create pingidentity/pingaccess:9.1.0-latest)
mkdir -p .pa/lib && docker cp "$id:/opt/server/lib/pingaccess-sdk-9.1.0.1.jar" .pa/lib/ && docker rm "$id"
mvn verify                                    # tests, the coverage ratchet, the jar
# or, against an install:
mvn -Dpa.server.root=/opt/pingaccess -Dpa.sdk.version=9.1.0.1 verify

The jar is target/authzen-pdp-pingaccess-<version>.jar; PingAccess supplies Jackson, jose4j and slf4j, so nothing is bundled. The bytecode is Java 17, so it needs a Java 17 or later runtime; it has been tested on PingAccess 9.1.0.1 (Java 21) and nothing earlier. Copy it to <PA_HOME>/deploy/ and restart; the DevOps image's local server profile is /opt/in/instance/deploy/. The rule then appears as AuthZEN PDP (class com.idpartners.pa.authzen.AuthZenRule) for Site and Agent destinations.

The rule in the console

The console draws one form from the rule's descriptor: each field with a widget, a label, a default, a help note, and whether it is required or behind Show Advanced Settings. The same descriptor is what the admin API serves at GET /pa-admin-api/v3/rules/descriptors/AuthZenPdpRule. Captured from the demo's PingAccess (docker compose --profile pingaccess) as configured by its start-up hook.

Every field

Names are as saved under configuration; the console shows a label with the name in brackets. advanced marks a field behind Show Advanced Settings.

The PDP

The route

coaz-pep

Discovery

Layers

The user token

Transport and compatibility

Saving validates twice: field constraints first, reported on the field under a Save Failed banner (the PDP URL must not be blank, the drop-downs must hold one of their options, the numbers must be numbers), then the rule's own configure. That refuses a URL the rule could not call (not absolute http or https, no host, user info), style: mcp or require_dpop without coaz_url, a JSON null for a drop-down, and - unless allow_insecure is ticked - every missing or weakened security setting, listed in one banner. The descriptor sets agentCachingDisabled: true: an agent never caches this rule's verdict, because it depends on the token, the body and the PDP's current view.

The admin API

The same configuration as JSON, keyed by the names above. This is the repository's reference sample; demo/pingaccess/hooks/81-after-start-process.sh is the whole sequence, site and application included, as a script.

curl -sk -u administrator:$PA_PASSWORD -H 'X-Xsrf-Header: PingAccess' -H 'Content-Type: application/json' \
  https://pa-admin:9000/pa-admin-api/v3/rules -d '{
  "name": "authzen-pdp",
  "className": "com.idpartners.pa.authzen.AuthZenRule",
  "supportedDestinations": ["Site", "Agent"],
  "configuration": {
    "authzen_url": "https://pdp.bank.example",
    "authzen_api_key": "...",
    "pep_label": "PEP#2 (Bank API edge)",
    "style": "rest",
    "require_token": true,
    "pdp_discovery": "resource",
    "resource": "https://api.bank.example",
    "resource_metadata_allowlist": ["https://api.bank.example"],
    "pdp_allowlist": ["https://pdp.bank.example"],
    "pdp_layers": ["https://estate-pdp.example fail-open", "resource"],
    "user_token_jwks_url": "https://as.bank.example/jwks",
    "user_token_audience": "https://api.bank.example"
  }
}'

A saved rule reads back as GET /pa-admin-api/v3/rules/{id} with the form's values under configuration; concealed fields come back encrypted.

Attaching it to an application

Then POST /applications with the rule in the API policy. The demo's hook creates the site, the virtual host and the application in that order and attaches the rule; this is the shape of the application.

{
  "name": "bank",
  "contextRoot": "/bank",
  "destination": "Site",
  "siteId": 1,
  "virtualHostIds": [1],
  "accessValidatorId": 0,                     # unprotected: the demo's tokens are unsigned, so its rule sets allow_insecure
  "enabled": true,
  "policy": { "API": [ { "type": "Rule", "id": 1 } ] }
}

In the console: Applications → Applications, edit the application, the API Policy tab, drag authzen-pdp from Available Rules onto the policy. Applications are created disabled unless enabled is set. Unprotected applications still run rules, but the rule refuses a token PingAccess did not validate unless it is configured with allow_insecure, which is how the demo uses unsigned tokens. A production application has an access token validator, and then PingAccess validates the bearer before the rule runs.

What PingAccess does, and what the rule does

• The access token. When the application is protected, PingAccess validates the bearer token before any rule runs: signature or introspection, expiry, audience. The rule reads what PingAccess established from the exchange's identity, and those attributes win over the token's own payload, which is also read when the token is a JWT, so act, cnf and acr are available whether PingAccess exposes them or not. Unprotected, PingAccess establishes no identity, and a request carrying a token is a 401 unless the rule has allow_insecure.
• DPoP. PingAccess enforces DPoP natively when it validates the token (the application's dpopSettings); that is the place for it. require_dpop is for the unprotected case and for parity with Kong: the proof goes to coaz-pep's /v1/dpop/verify.
• The user token. Unlike Kong, the rule verifies X-User-Token itself, since jose4j is on the classpath: signature, exp, sub and the configured audience. Without user_token_jwks_url the token is ignored. A verified token counts only as the principal's own login, unless user_token_subject is pdp; whenever one counts, the PDP is told whose it is (user_sub, user_iss), as coaz-pep tells it.
• MCP routes. Every request goes to coaz-pep's /v1/mcp/check. A body that is not exactly one JSON-RPC message the rule read in full is refused first: 400 with -32700 or -32600, 413 for a partial body, 415 for a compressed one.
• Headers. A permit removes every X-Auth-* header the client sent before setting the ones the PEP asserts. Values from a PDP's answer are cleaned for a header, and escaped inside WWW-Authenticate.
• The deny on the wire, the forwarded context, layers and fail mode are the Kong plugin's, knob for knob. A layer fails open on an outage only, never on a refusal. The long form of each is on the Kong page; the reasoning is in docs/pingaccess.md.