AuthZEN Fine-Grained Authorization

cidaas provides fine-grained authorization beyond OAuth2 scopes and group/role restrictions through the OpenID AuthZEN standard. AuthZEN separates policy administration from policy decision and supports attribute-based policies (Rego/OPA), external data via Policy Information Points (PIP), and Relationship-Based Access Control (ReBAC).

Architecture

Component	Service	Responsibility
Policy Management	policy-management-srv	Create and manage Rego policies, PIP data sources, AuthZEN entities, versions, export/import bundles, and ReBAC administration (schema, tuples, catalog)
Policy Decision Point (PDP)	policy-decision-srv	Evaluate access requests, run batch evaluations, search subjects/resources/actions, expose AuthZEN discovery
ReBAC runtime	rebac-srv	Decision-time ReBAC permission checks and lookups used by PDP rebac.* Rego builtins
ReBAC store	Relation Store	Stores relationship tuples and schema; optional per-tenant configuration

How It Fits With Permission Management

AuthZEN complements the mechanisms described in Permission Management:

Mechanism	Use case
Scopes	Coarse-grained client permissions on APIs
Groups & roles	User membership and login-time token claims
AuthZEN policies	Fine-grained, context-aware authorization (ABAC) at runtime
ReBAC	Graph-based permissions (owner, editor, viewer, group membership)

Typical flow:

1. Authenticate the user or service and obtain an access_token.
2. Call the PDP evaluation API with subject, resource, action, and optional context.
3. Use the decision boolean to allow or deny the operation in your application.

Required Scopes and Roles

Administrative APIs require OAuth2 scopes and CIDAAS_ADMINS group roles.

Scope	Purpose
cidaas:authzen_evaluate	Evaluate access and run PDP search APIs
cidaas:authzen_read	Read policies, entities, data sources, ReBAC
cidaas:authzen_write	Create and update AuthZEN resources
cidaas:authzen_delete	Delete AuthZEN resources
cidaas:authzen_rebac_read	Read ReBAC schema and relationships
cidaas:authzen_rebac_write	Write ReBAC schema and relationships
cidaas:resource_export	Export configuration bundles
cidaas:resource_import	Import configuration bundles

Eligible roles in the CIDAAS_ADMINS group include ADMIN, SECONDARY_ADMIN, AUTHZEN_MANAGER, POLICY_READ, POLICY_CREATE, and POLICY_DELETE.

Evaluation and search APIs on policy-decision-srv require a valid bearer token with cidaas:authzen_evaluate.

Documentation

Topic	Description
Policy Management	Policies, entities, data sources, validation, versions, export/import
Access Evaluation	Runtime PDP evaluation, search, cache invalidation
ReBAC	ReBAC schema, relationship tuples, Rego integration

OpenAPI References

API	OpenAPI
Policy Management	policy-management
Policy Decision (PDP)	policy-decision
ReBAC (runtime)	rebac

Quick Start

1. Create a Rego policy via POST /policy-management-srv/admin/policies.
2. Evaluate access with subject, resource, and action.

Policy Management

The policy-management-srv is the administrative API for AuthZEN authorization in cidaas. It stores Rego policies, PIP configuration, semantic versions, and ReBAC administration data.

Policies

Policies are written in Rego (Open Policy Agent) and must use package authzen. The evaluator looks for rules that set allow (or equivalent decision logic).

Policy structure

  package authzen

  default allow := false

  allow if {

      input.subject.properties.roles[_] == "admin"

      input.action.name == "read"
  }

The evaluation input object contains:

Field	Description
subject	Requesting entity (id, type, properties)
resource	Target resource (id, type, properties)
action	Requested action (name, properties)
context	Additional context; PIP data appears under context.pip

Create a policy

API	Description	Link
Create policy	Store a new Rego policy	View API
List policies	List all tenant policies	View API
Get policy	Fetch policy by ID; optional version query	View API
Update policy	Replace policy script and metadata	View API
Delete policy	Soft-delete policy and versions	View API

Example: create policy

  curl -X POST 'https://{host}/policy-management-srv/admin/policies' \
    -H 'access_token: {token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "DocumentReadPolicy",
      "script": "package authzen\n\ndefault allow := false\n\nallow if {\n  input.action.name == \"read\"\n  input.resource.properties.owner_id == input.subject.id\n}\n",
      "language": "rego"
    }'

Policy Validation

Before deploying changes, validate the full bundle or a proposed dry-run set.

API	Description	Link
Validate all policies	Async compile/validate of current bundle	View API
Dry-run	Validate proposed policy changes without saving	View API
Profile bundle	Profile evaluation against a sample request	View API
SSE stream	Receive validation progress events	View API

Async endpoints return a task with ref. Connect to GET /policy-management-srv/sse/{ref} to receive PENDING, SUCCESS, or FAILURE events.

Data Sources (PIP)

PIP (Policy Information Point) data sources fetch external attributes during evaluation. Discovery data sources provide URLs for entity lookup.

Field	PIP	Discovery
type	PIP	Discovery
key	Required unique PIP key	—
communicationEP	HTTP endpoint URL	Discovery URL
apiAccess	Credential setup (required)	Credential setup (required)
matchingCriteria	Subject/resource/action type filters (* = all)	—

API	Description	Link
Create data source	Register PIP or Discovery endpoint	View API
List data sources	Optional type filter	View API
Get / update / delete	CRUD by ID	View API

PIP data is available in Rego as input.context.pip.{key}.*.

Versions

Semantic versions track policy and ReBAC script history.

API	Description	Link
Create version	New version for a policy or ReBAC artifact	View API
Get version by ID	Fetch version document	View API
Get version by policy	GET .../versions/{policyId}/{version}	View API

Supported type values: POLICY, REBAC_SCHEMA, REBAC_RELATIONSHIP_TUPLE, REBAC_CAVEAT_PARAM.

Resource Export and Import

Move AuthZEN configuration between environments using cidaas-resource-bundle documents.

Kind	Description
cidaas.authzen.policy	Rego policies
cidaas.authzen.datasource	PIP and Discovery sources
cidaas.authzen.entity	AuthZEN subject, resource, and action entities
cidaas.authzen.rebac.schema	Versioned ReBAC schema catalog entries
cidaas.authzen.rebac.relationship_tuple	Versioned relationship tuple catalog entries
cidaas.authzen.rebac.caveat_param	Versioned caveat parameter catalog entries

API	Description	Link
Export	JSON or ZIP (format=zip); query kinds, includeDeleted, includeSecrets	View API
Import preview	Detect conflicts; returns importSessionId	View API
Import apply	Resolve conflicts and apply bundle	View API

Conflict resolutions: SKIP, KEEP_EXISTING, REPLACE, REPLACE_ALL.

AuthZEN Entities

Register subject, resource, and action entities used by PDP search APIs and entity discovery.

API	Description	Link
Create entity	Register a subject, resource, or action	View API
List entities	List by entityType query (subject, resource, action)	View API
Get / update / delete	CRUD by ID	View API
Entity discovery	Paginated discovery at GET /policy-management-srv/authzen/entity/discovery	View API

Evaluation Audit

Query policy evaluation audit history stored by policy-management-srv.

API	Description	Link
Count audits	Count evaluations in a time window	View API
List audits	Paginated audit records with request/response payloads	View API

Webhooks and Activity

Policy create, update, and delete operations emit facts (AUTHZEN_POLICY_CREATED, AUTHZEN_POLICY_UPDATED, AUTHZEN_POLICY_DELETED) for activity streams and webhook integration.

Evaluation Audit

Every access evaluation performed by the PDP is recorded as an audit entry, capturing the original request(s) and the returned decision(s). Use these admin APIs to review or report on authorization activity.

API	Description	Link
Count audits	Number of audit entries in a time range	View API
List audits	Audit entries (newest first) with request and decision	View API

Both require a time range with from (required) and optional to (RFC 3339; defaults to now). Each audit entry contains evaluatedTime, tenantKey, refNumber, the request/response arrays, and evaluationCount (a single entry covers a whole batch request). Paginate the list by passing the response nextTime as the to of the next request. These read APIs require cidaas:authzen_read or cidaas:authzen_management.

Access Evaluation (Policy Decision Point)

The policy-decision-srv is the AuthZEN Policy Decision Point (PDP). It evaluates Rego policies from policy-management-srv, merges PIP data from configured data sources, and exposes AuthZEN-standard evaluation and search APIs.

OpenAPI: policy-decision.

Discovery

Discover PDP endpoints via the AuthZEN configuration document:

API	Description	Link
AuthZEN configuration	Well-known PDP metadata	View API

GET /policy-decision-srv/.well-known/authzen-configuration returns:

• policy_decision_point
• access_evaluation_endpoint
• access_evaluations_endpoint
• search_subject_endpoint, search_resource_endpoint, search_action_endpoint

Evaluation Workflow

Step 1: Ensure policies are current

The PDP caches compiled policy evaluators, PIP data, and discovery data per tenant. After a policy change you have three options:

Approach	API	When to use
Invalidate immediately	POST /access/v1/cache/invalidate	Apply policy changes right away; the next evaluation reloads the latest bundle
Reload policies	POST /access/v1/policies/reload	Force a re-fetch and rebuild of the evaluator cache
Wait for the cache TTL	—	If you do nothing, cached entries expire automatically and policies refresh on the next evaluation

Both operations accept an optional tenant_key body; when omitted, the tenant is resolved from the request token. They require cidaas:authzen_evaluate or cidaas:authzen_management.

Step 2: Single evaluation

API	Description	Link
Evaluate access	Single subject–action–resource decision	View API

Request:

  {
    "subject": {
      "id": "user-123",
      "type": "user",
      "properties": {
        "roles": ["admin"]
      }
    },
    "resource": {
      "id": "doc-456",
      "type": "document",
      "properties": {
        "owner_id": "user-123"
      }
    },
    "action": {
      "name": "read"
    },
    "context": {}
  }

Response:

  {
    "decision": true,
    "context": {
      "reason": "Policy evaluation completed"
    }
  }

Unlike policy-management admin APIs, evaluation responses follow the AuthZEN specification directly (no success wrapper).

Step 3: Batch evaluation

API	Description	Link
Batch evaluate	Multiple decisions in one request	View API

Use options.evaluations_semantic to control evaluation order:

Value	Behaviour
execute_all	Evaluate all requests (default)
deny_on_first_deny	Stop at first decision: false
permit_on_first_permit	Stop at first decision: true

Parent-level subject, resource, action, and context are inherited by each item in evaluations unless overridden per item.

Search APIs

Search endpoints return candidate subjects, resources, or actions that match policy criteria. The PDP fetches the candidate pool from the Discovery data sources configured in policy-management-srv (see Data Sources), then evaluates each candidate against the fixed parts of the request before returning the matches. Configure at least one Discovery data source for the relevant entity type, otherwise search returns no candidates. Results support pagination.

API	Description	Link
Search subjects	Who can perform action on resource	View API
Search resources	Which resources match criteria	View API
Search actions	Which actions are permitted	View API

Pagination uses page.token and page.limit. Responses include page.next_token and results.

PIP Data in Evaluation

When PIP data sources are configured in policy-management-srv, the PDP fetches matching endpoints and injects data into input.context.pip before Rego evaluation.

Example Rego using PIP:

  package authzen

  default allow := false

  allow if {
      input.context.pip.my_pip_key.data.customFields.account_id in input.context.pip.my_pip_key.data.customFields.consent_accounts
  }
  

Authentication

All PDP endpoints require a valid bearer token (access_token header or Authorization: Bearer). The token must include cidaas:authzen_evaluate.

Related Documentation

• ReBAC — graph-based permissions in Rego

warning

Need Support?

Please contact us on our support page or reach out to cidaas support at [email protected].