The AuthZEN Authorization API 1.0

Objective

Describe the OpenID AuthZEN Authorization API 1.0 evaluation contract, read a single and a batch evaluation payload, and say what the discovery endpoint advertises.

Concept

A PEP and a PDP talk over an interface. If that interface is proprietary, swapping either side means a rewrite. AuthZEN is the OpenID standard that makes the interface portable: the PEP asks "may this subject do this action on this resource" in one agreed shape, and any conformant PDP answers in one agreed shape. Learn the contract, not a vendor's wire format.

The evaluation request

Every AuthZEN evaluation carries up to four objects:

subject — who is asking. A type (for example user), an id, and optional properties (roles, department, anything the policy needs to know about the caller).
action — what they want to do. A name, for example can_read or can_delete.
resource — what they want to act on. A type, an id, and optional properties (owner, classification, department).
context — request-time facts that belong to neither party: time of day, source IP, request risk. Optional.

A single evaluation looks like this:

{
  "subject": { "type": "user", "id": "alice@acme.com" },
  "action": { "name": "can_read" },
  "resource": { "type": "document", "id": "doc-1" },
  "context": {}
}

It is sent to POST /access/v1/evaluation. The response is deliberately small:

{ "decision": true }

A boolean. The PDP may attach additional context, but the load-bearing field is decision. The PEP permits on true and blocks on false.

The batch request

A single page often needs many decisions at once: can this user see the edit button, the delete button, the share menu? Rather than N round trips, AuthZEN defines a batch endpoint, POST /access/v1/evaluations. It carries shared defaults plus a list of evaluations, and returns one decision per item, in order:

{
  "subject": { "type": "user", "id": "alice@acme.com" },
  "resource": { "type": "document", "id": "doc-1" },
  "action": { "name": "can_read" },
  "evaluations": [
    { "action": { "name": "can_edit" } },
    { "action": { "name": "can_delete" } }
  ]
}

Response:

{
  "evaluations": [{ "decision": true }, { "decision": false }]
}

Each item inherits the top-level subject, action, and resource and overrides only what it names. Use single evaluation on the enforcement path where one decision gates one operation. Use batch when a caller needs several related decisions together, for example to render a UI.

Discovery

A PEP should not hard-code where the PDP lives or which endpoints it offers. GET /.well-known/authzen-configuration returns the PDP's metadata document: the base URL and the paths it serves, so a PEP can find the evaluation endpoints the way an OIDC client reads /.well-known/openid-configuration. It advertises capability; it does not make a decision.

Where this maps to the request flow

The AuthZEN request is exactly the input a PDP evaluates. subject, action, and resource are what the PEP knows about the call; context is often filled from a PIP. The decision is what the PDP returns and the PEP enforces. The standard does not change the PEP/PDP/PIP roles; it standardizes the message between the PEP and the PDP.

Hands-on lab

Open ../lab/policy.rego. Notice its input is an AuthZEN request: input.subject, input.action.name, input.resource.properties, input.context. The rule named decision is the boolean AuthZEN returns. Run the suite:

git clone https://github.com/EnforceAuth/university-labs.git
cd university-labs
opa test courses/authzen-pdp-integration -v

Run it from the cloned university-labs repo. Expected: PASS: 9/9. Read test_admin_can_delete: its with input as {...} block is a full AuthZEN single-evaluation request. Read test_viewer_no_relationship_cannot_read_internal: it is the same shape, and asserts not decision, which is the AuthZEN response {"decision": false}.

Check for understanding

Name the four objects in an AuthZEN evaluation request and say which one is optional and typically supplied from a PIP.
What is the single load-bearing field in the AuthZEN evaluation response, and what does a PEP do with each of its two values?
A page must decide whether to show the edit, delete, and share buttons for one document and one user. Which endpoint fits, POST /access/v1/evaluation or POST /access/v1/evaluations, and why?
What does GET /.well-known/authzen-configuration return, and what does it explicitly not do?

Objective​

Concept​

The evaluation request​

The batch request​

Discovery​

Where this maps to the request flow​

Hands-on lab​

Check for understanding​