AuthZEN Authorization API

The OpenID AuthZEN Authorization API 1.0Opens in a new tab is a standard from the OpenID Foundation that defines a common interface between applications (Policy Enforcement Points) and authorization services (Policy Decision Points). It provides a simple, REST-based way for applications to request authorization decisions using a consistent request and response model, independent of the underlying policy engine. Axiomatics is a founding member of the OpenID AuthZEN Working Group.

Access Decision Service (ADS) implements native support for the AuthZEN Authorization API, enabling it to receive AuthZEN requests, evaluate them against XACML policies, and return standardized authorization decisions.

note

AuthZEN endpoints are available only when ADS runs in ads or ads_caq mode.

Enabling AuthZEN

AuthZEN endpoints are disabled by default. To enable them, set the authZen.enabled property to true, either in your deployment configuration or through Helm values.

• deployment.yaml
• Helm values

deployment.yaml

authZen:
  enabled: true

--set authZen.enabled=true

Endpoints

ADS exposes the following AuthZEN endpoints:

• Access evaluation endpoint

  /access/v1/evaluation

  Evaluates a single authorization request

• Batch access evaluation endpoint

  /access/v1/evaluations

  Evaluates multiple authorization requests in a single call

• PDP discovery endpoint

  /.well-known/authzen-configuration

  Discovers available AuthZEN endpoints and capabilities

An AuthZEN request is a JSON object with the following elements:

Element	Required	Description
subject	Yes	The user or principal requesting access.
action	Yes	The operation being performed.
resource	Yes	The target of the request.
context	No	Environmental or contextual attributes (IP address, time of day, etc.).

Each required element has its own required inner fields:

Element	Field	Required	Description
subject	id	Yes	Identifier of the subject (email address, etc.).
subject	type	Yes	Type of the subject (user, employee, etc.).
subject	properties	No	Additional subject attributes.
resource	id	Yes	Identifier of the resource.
resource	type	Yes	Type of the resource (account, document, etc.).
resource	properties	No	Additional resource attributes.
action	name	Yes	Name of the action (can_read, edit, etc.).
action	properties	No	Additional action attributes.

Request validation

ADS validates all required fields before evaluating a request. Any missing required field results in HTTP 400 with a descriptive error message.

Missing field	HTTP response
subject, resource, or action (top-level)	400 Bad Request
subject.id or subject.type	400 Bad Request
resource.id or resource.type	400 Bad Request
action.name	400 Bad Request

Example: missing subject field

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400,
  "message": "subject: subject is required"
}

Example: subject present but missing id

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400,
  "message": "subject.id: id is required"
}

Attribute mapping

ADS maps AuthZEN attributes to XACML attributes using the ADS dictionary (ALFA FQN lookup):

• subject.id, subject.type, resource.id, resource.type, and action.name have built-in default mappings and work out of the box with no additional configuration.
• For all other attributes, ADS looks up the ALFA FQN in the dictionary. A dictionary entry is applied only when both the key and the category match. If either does not match, ADS falls back to the default mapping.

Attributes that are not in the dictionary do not cause an error. As in the /authorize endpoint, ADS sends them to the policy as strings. An array value is sent as a multi-valued attribute, and an array that contains null returns HTTP 400.

Decision mapping

The AuthZEN decision field is a boolean. ADS maps the four possible XACML outcomes to this boolean as follows:

XACML decision	AuthZEN decision	Meaning
Permit	true	The access request has been permitted.
Deny	false	The access request has been denied.
NotApplicable	false	The policy is not applicable to the access request.
Indeterminate	false	There has been an error processing the request.

This default mapping (only Permit maps to true) is known as deny bias.

Response context

The AuthZEN response defines an optional context field, which ADS uses to carry information from the underlying XACML response that has no direct equivalent in the AuthZEN specification. This mapping follows the XACML 3.0 & ALFA Profile of OpenID AuthZEN 1.0Opens in a new tab:

Field	Description
xacml.decision	The raw XACML decision (Permit, Deny, NotApplicable, or Indeterminate), namespaced under xacml to avoid clashing with the top-level AuthZEN decision field.
xacml.obligations	An array of the obligations returned in the XACML response, in no particular order.
xacml.advice	An array of the advice returned in the XACML response, in no particular order.
includedAttributes	Attributes from the XACML response that were marked for inclusion in the result. Returned only for single access evaluations.

These fields are only present when the underlying XACML response includes them. For example, xacml.advice appears in the Access denied example below, where the evaluated policy returned an advice element.

Examples

Single access evaluation

Check whether user alice@acmecorp.com is allowed to read account 123:

Request

POST /access/v1/evaluation
Content-Type: application/json

{
  "subject": {
    "type": "employee",
    "id": "bob@acmecorp.com",
    "properties": {
      "department": "engineering",
      "clearanceLevel": "confidential"
    }
  },
  "action": {
    "name": "edit"
  },
  "resource": {
    "type": "document",
    "id": "project-plan-2026",
    "properties": {
      "classification": "confidential"
    }
  }
}

Response

• Access permitted
• Access denied
• Not applicable
• Indeterminate

{
  "decision": true,
  "context": {
    "xacml": {
      "decision": "Permit"
    }
  }
}

{
  "decision": false,
  "context": {
    "xacml": {
      "decision": "Deny",
      "advice": [
        {
          "id": "urn:example:advice:notify-manager",
          "attributes": {
            "message": "Access to confidential accounts requires manager approval."
          }
        }
      ]
    }
  }
}

{
  "decision": false,
  "context": {
    "xacml": {
      "decision": "NotApplicable"
    }
  }
}

{
  "decision": false,
  "context": {
    "xacml": {
      "decision": "Indeterminate"
    }
  }
}

Batch access evaluation

Evaluate multiple authorization requests in a single call. Shared subject and action values are specified at the top level, while each evaluation can override or specify its own resource. Every evaluation must have all required fields after the top-level values are applied; otherwise the whole request is rejected with HTTP 400.

Request

POST /access/v1/evaluations
Content-Type: application/json

{
  "subject": {
    "type": "user",
    "id": "alice@acmecorp.com"
  },
  "action": {
    "name": "can_read"
  },
  "evaluations": [
    {
      "resource": { "type": "account", "id": "123" }
    },
    {
      "resource": { "type": "account", "id": "456" }
    },
    {
      "action": { "name": "can_write" },
      "resource": { "type": "account", "id": "789" }
    }
  ]
}

Response

The response contains one decision per input request, in the same order:

{
  "evaluations": [
    {
      "decision": true,
      "context": {
        "xacml": {
          "decision": "Permit"
        }
      }
    },
    {
      "decision": false,
      "context": {
        "xacml": {
          "decision": "Deny"
        }
      }
    },
    {
      "decision": false,
      "context": {
        "xacml": {
          "decision": "NotApplicable"
        }
      }
    }
  ]
}

Invalid evaluations within a batch

ADS applies the top-level subject, action, and resource values to each evaluation as defaults, and then validates every evaluation against the required fields. If any evaluation is missing a required field after the defaults are applied, ADS rejects the whole request with HTTP 400.

The error message lists the errors for each invalid evaluation, identified by its index in the evaluations array:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400,
  "message": "evaluations[0].subject.id: id is required, evaluations[1].subject.id: id is required"
}

A top-level subject without an id is accepted if every evaluation provides its own subject.id.

PDP discovery

Discover which AuthZEN endpoints and capabilities ADS supports:

Request

GET /.well-known/authzen-configuration

Response

{
  "policy_decision_point": "https://ads.example.com",
  "access_evaluation_endpoint": "https://ads.example.com/access/v1/evaluation",
  "access_evaluations_endpoint": "https://ads.example.com/access/v1/evaluations"
}