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, versions, export/import bundles, and ReBAC schema/tuples
Policy Decision Point (PDP)	`policy-decision-srv`	Evaluate access requests, run batch evaluations, search subjects/resources/actions, expose AuthZEN discovery
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:

Authenticate the user or service and obtain an access_token.
Call the PDP evaluation API with subject, resource, action, and optional context.
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_management`	Full AuthZEN admin access
`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 or cidaas:authzen_management.

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

Quick Start

Create a Rego policy via POST /policy-management-srv/admin/policies.
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

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.

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.

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

After any policy change, cache gets refreshed within 60 seconds. Wait for at least 60 seconds after policy change.

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. They use entities registered in policy-management-srv and 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 or cidaas:authzen_management.

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].

Architecture​

How It Fits With Permission Management​

Required Scopes and Roles​

Documentation​

OpenAPI References​

Quick Start​

Policy Management​

Policies​

Policy structure​

Create a policy​

Example: create policy​

Policy Validation​

Data Sources (PIP)​

Versions​

Resource Export and Import​

Webhooks and Activity​

Access Evaluation (Policy Decision Point)​

Discovery​

Evaluation Workflow​

Step 1: Ensure policies are current​

Step 2: Single evaluation​

Step 3: Batch evaluation​

Search APIs​

PIP Data in Evaluation​

Authentication​

Related Documentation​