AuthZEN Adapter

An AuthZEN evaluation {subject, action, resource, context} becomes a governance-engine decision request. Each tuple element travels as a JSON string under a configurable attribute prefix, so a Trust Framework request resolver can read it; the engine's verdict maps straight back to the AuthZEN boolean, and any policy reason rides along in context.

The subject id is accepted under id (spec) or identity (as earlier Ping enforcement points send it) - identity wins when both are present. The adapter reads {"authorised":…}, {"authorized":…} or {"decision":"PERMIT"|"DENY"} from the engine, so it works against either dialect.

Flat attributes, Shared Signals events and the SPIFFE caller check are off unless configured; advice mapping applies whenever policy returns the advice statement codes.

Two policy statement codes are mapped into the AuthZEN response context as custom advice fields, so a PEP can trigger step-up authentication or identity proofing rather than act on a bare DENY. These fields are ID Partners conventions, not part of AuthZEN, and the PEP decides how to issue any challenge.

Statements are scanned in order and the last advice statement's message wins. A missing or malformed payload still sets the bare flag; it just contributes no detail. With no advice at all, the reason comes from the engine's reason field, else the first statement's payload.

Subject and action search: the query endpoint

These call the governance-engine query endpoint (query-url) and map the echoed values into AuthZEN results. The query names subject and resource with your attribute-prefix but the action bare, for Trust Frameworks that give action its own value source - validate the mapping against your query resolvers. An echoed value is parsed as JSON when it is JSON and kept as text when it is not, so an engine that answers with a bare action name is understood rather than rejected.

POST query-url · subject search
{ "query": [
  { "attribute": "Gateway.subject",  "values": ["{\"type\":\"user\"}"] },
  { "attribute": "action" },
  { "attribute": "Gateway.resource", "values": ["{\"type\":\"account\",\"id\":\"acct-1\"}"] }
] }

Resource search: the policy

The query endpoint cannot enumerate a free resource id - there is no finite value source to draw from - so the answer comes from policy instead. One evaluation runs with the resource carrying only its type; a PERMIT with an entitled_accounts statement supplies the permitted ids.

statement code: entitled_accounts · payload
{ "accounts": ["CHK-1001", "SAV-2002"] }

A DENY, a missing statement, a wrong code, a non-JSON payload or a payload without an array all yield the empty set. The search fails closed rather than guessing, and your policy must attach the statement for it to return anything.

The adapter is tested with the OpenID Foundation conformance suite, the suite behind OpenID Connect and FAPI certification. In September 2026 all six of its AuthZEN policy decision point plans were run, on suite release 5.3.1, against PingAuthorize 11.1 holding the certification scenario's fixture policy, built as code, with the metadata document found by discovery: 147 of 147 tests passed. The run is held in ID Partners' account on the suite; ask us for the plan logs.

Two things to know before quoting that number. The suite's AuthZEN plans are alpha tests, not yet part of the OpenID certification programme, so this is evidence of conformance rather than a certificate, and ID Partners does not describe the adapter as certified. And one module still tests a rule from the draft of the certification scenario - that a batch entry inherits a missing type from the request-level default - which the published scenario and AuthZEN 1.0 reversed. The adapter follows the published rule; the batch-defaults=fill setting lets it satisfy the suite as it stands, and comes off when the suite catches up.

Suite release 5.3.1, September 2026, with pdp_auth_type=none and pdp_server_metadata=discovery: the run that exercises the metadata checks. The AuthZEN Authorization API 1.0 is an OpenID Foundation specification.

api-key says that someone holding the shared key called. On a connection handler that requires a client certificate, the handler has already established which workload called before the adapter runs - and the adapter reads the peer's SPIFFE ID off that verified chain.

1. The peer's SPIFFE ID is listed in accepted-spiffe-id. Admitted, no bearer needed, and forwarded to policy as <prefix>.caller (plus callerSpiffeId with flat-tuple).
2. Otherwise, unless spiffe-required is true, a valid Authorization: Bearer <api-key>. Admitted with no caller attribute - its absence is how policy tells a key holder from a listed workload.
3. Otherwise, when no api-key is configured either, anyone.

The two /.well-known/ documents skip the gate by design. The caller rides on evaluations, batches and resource search; the query path carries none. spiffe-required with no listed ID, or an ID that is not a well-formed SPIFFE ID, is refused when the adapter is configured, rather than silently locking everyone out.

Set ssf-shared-secret and the adapter acts as a Shared Signals transmitter for the evaluations it answers - single and batch. Searches, and calls made directly to PingAuthorize's own decision APIs, produce no events. The adapter queues evaluation events for background delivery. Delivery is best effort. Unset, the SSF paths answer 404 and nothing is published.

# register the Receiver
curl -s https://pdp.example/ssf/stream \
  -H "Authorization: Bearer <api-key>" \
  -H 'Content-Type: application/json' \
  -d '{ "aud": "receiver-app",
        "events_requested": ["https://schemas.idpartners.com.au/ssf/authzen-decision"],
        "delivery": { "method": "urn:ietf:rfc:8935",
                      "endpoint_url": "https://receiver.example/events",
                      "authorization_header": "Bearer <receiver-secret>" } }'
# 201 {"stream_id":"…","iss":"…","aud":"receiver-app","events_supported":[…],
#      "events_requested":[…],"events_delivered":[…],"delivery":{…}}

GET /ssf/stream?stream_id=… reads it back; DELETE unregisters it, idempotently. events_delivered is the intersection of what was asked for and what the Transmitter supports - an unrecognised event type is simply not delivered, not an error.

POST https://receiver.example/events
Content-Type: application/secevent+jwt

# header
{ "alg": "HS256", "typ": "secevent+jwt" }
# claims - no sub or exp
{
  "iss": "https://pdp.example",
  "jti": "0d9c6b1e-4f7a-4a52-9a0e-3c1b7d2e8f41",
  "iat": 1789180200,
  "aud": "receiver-app",
  "events": {
    "https://schemas.idpartners.com.au/ssf/authzen-decision": {
      "subject": "agent-42",
      "action": "transfer",
      "resource": "acct-1",
      "decision": "DENY",
      "step_up_required": true,
      "step_up_scope": "payments:high-value",
      "reason": "Transfers over 10,000 AUD need a stronger sign-in",
      "attrs": { "amount": 25000, "currency": "AUD", "to_account": "SAV-2002" }
    }
  }
}

Advice fields from the decision context are merged in at the top level. attrs carries a fixed whitelist of request-context keys - amount, currency, to_account, user_scope, channel - and is omitted when none are present.

The adapter ships as a manage-extension bundle for your PingAuthorize major version. Install it, then apply the registration batch inside it - which also adds the adapter to the HTTPS connection handler.

# 1. install the bundle
<paz>/bin/manage-extension --install authzen-adapter-<version>.zip

# 2. register and serve it - set the arguments in the batch first
<paz>/bin/dsconfig --no-prompt --batch-file config/register.dsconfig

# serve it from another handler too, e.g. the SPIFFE mTLS handler
<paz>/bin/dsconfig set-connection-handler-prop \
  --handler-name "SPIFFE mTLS Connection Handler" \
  --add "http-servlet-extension:AuthZEN Adapter"

• One code base, both majors. PingAuthorize 11 moved its Server SDK from javax.servlet to jakarta.servlet and refuses a bundle built for the other. Both bundles are built from the same source. Talk to ID Partners to confirm support for your exact PingAuthorize release.
• Nothing to conflict with. The bundle carries only the extension jar; JSON, servlet and SDK classes come from the running server.
• Coverage-gated. The build fails unless the methods that admit a caller, shape a decision request, read an answer, stop a batch or build an event have full line and branch test coverage.