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 and Discovery data-source registrations (URL, GraphQL config, credentials), search configuration, live/simulation version pins, optional sample entities, versions, export/import bundles, and ReBAC administration
Policy Decision Point (PDP)	policy-decision-srv	Live and simulation evaluation, search, explain, AuthZEN well-known 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

The source of truth for subjects, resources, and actions used in search is your own systems (IdP, CMDB, application database). Register that GraphQL API as a Discovery data source, the same way you register a PIP for evaluation attributes. policy-management-srv stores the registration (URL, query template, credentials), not your production catalog.

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 live PDP search APIs
cidaas:authzen_simulate	Evaluate access and run search on the simulation channel
cidaas:authzen_explain	Run OPA explain traces on the live channel
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 cidaas:authzen_evaluate (live) or cidaas:authzen_simulate (simulation).

warning

Deprecated scope: cidaas:authzen_management

cidaas:authzen_management is deprecated and will be removed. Do not request it for new clients. Existing tokens that still include it continue to work until removal. Grant the granular scopes in the table above instead:

Instead of cidaas:authzen_management	Use
Policy-management read (list/get, search-config, audit, discovery)	cidaas:authzen_read
Policy-management create/update, modes, SearchConfig PUT	cidaas:authzen_write
Deletes	cidaas:authzen_delete
Live PDP eval, search, cache invalidate, reload	cidaas:authzen_evaluate
Simulation PDP	cidaas:authzen_simulate
Live explain	cidaas:authzen_explain
ReBAC admin	cidaas:authzen_rebac_read / cidaas:authzen_rebac_write
Export / import	cidaas:resource_export / cidaas:resource_import

Documentation

Topic	Description
Policy Management	Policies, entities, data sources, validation, versions, export/import
Live and simulation	Version pins and simulation-channel PDP APIs
Access Evaluation	Runtime PDP evaluation, cache invalidation
AuthZEN Search	Filter policies, Discovery, SearchConfig, search APIs
AuthZEN Simulation	Pin versions and compare live vs simulation
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 and Discovery data-source registrations, semantic versions, and ReBAC administration data. It does not replace your entity database.

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 and channel (live | simulation)	View API
Update policy	Replace policy script and metadata	View API
Update modes	Pin or clear liveVersionId / simulationVersionId	View API
Simulation revision	Tenant hash used as a PDP simulation cache key	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 and Discovery)

PIP (Policy Information Point) data sources fetch external attributes during evaluation. Discovery data sources are external GraphQL APIs the PDP calls at search time to list subjects, resources, or actions from your catalog.

communicationEP for Discovery is your GraphQL URL. A bundled sample endpoint at /policy-management-srv/authzen/discovery/graphql exists only so you can experiment without wiring your catalog first; do not treat it as the production source of truth.

Field	PIP	Discovery
type	PIP	Discovery
key	Required unique PIP key	Optional label
searchEntityType	—	Required: subject, resource, or action
graphqlConfig	—	Required (queryTemplate, resultPath, pagination); adapt templates to your schema
communicationEP	External HTTP URL	External GraphQL URL
apiAccess	Credential setup (required)	Credential setup (required)
matchingCriteria	Subject/resource/action type filters (* = all)	Same; used to match a search request

API	Description	Link
Create data source	Register a PIP or your Discovery GraphQL endpoint	View API
List data sources	Optional type filter	View API
Get / update / delete	CRUD by ID	View API
Discovery templates	Starting GraphQL query shape (adapt to your schema)	View API
Bootstrap Discovery	Sample sources pointing at the bundled GraphQL API	View API
Sample GraphQL discovery	Experimental catalog backed by the sample entities API	View API
Search configuration	Filter queries and post-eval flags	View API

PIP data is available in Rego as input.context.pip.{key}.*. For connecting your GraphQL source, filter policies, and the optional sample catalog see AuthZEN Search.

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.searchconfig	Tenant search configuration singleton
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 (sample catalog)

These APIs store a sample subject/resource/action catalog for experiments. Production search does not read this store unless you register the bundled sample GraphQL endpoint as a Discovery data source. Your real entities stay in your own systems.

API	Description	Link
Create entity	Add a sample catalog row	View API
List entities	List by entityType query (subject, resource, action)	View API
Get / update / delete	CRUD by ID	View API
Entity discovery	Paginated REST sample catalog (legacy)	View API
Seed samples	Demo alice/bob/accounts/read/write	View API

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.

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.

Live and simulation

Each policy can pin a live version (liveVersionId) and a simulation version (simulationVersionId). An empty pin means that channel uses the working-copy script.

• Live PDP routes: /policy-decision-srv/access/v1/*
• Simulation PDP routes: /policy-decision-srv/access/v1/simulation/*

Caches are separate. See AuthZEN Simulation for pinning, diff vs live baseline, and a rollout checklist.

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
• simulation_evaluation_endpoint, simulation_evaluations_endpoint, simulation_explain_endpoint
• simulation_search_subject_endpoint, simulation_search_resource_endpoint, simulation_search_action_endpoint

Live explain is available at POST /policy-decision-srv/access/v1/explain and is not advertised in this well-known document. Only the simulation explain URL is returned (simulation_explain_endpoint).

Evaluation Workflow

Step 1: Ensure policies are current

The PDP auto-refreshes its live cache about every 10 seconds. That cache holds compiled policy evaluators, PIP definitions, Discovery data-source registrations, and SearchConfig. You do not need to invalidate after every change; wait for the next refresh.

Invalidate or reload only when you need the change on the next request:

Approach	API	When to use
Wait for auto-refresh	—	Default. Live cache refreshes about every 10 seconds
Invalidate immediately	POST /access/v1/cache/invalidate	Apply policy, PIP, Discovery, or SearchConfig changes right away
Reload policies	POST /access/v1/policies/reload	Force a re-fetch and rebuild of the live evaluator cache

Both operations accept an optional tenant_key body; when omitted, the tenant is resolved from the request token. They require cidaas:authzen_evaluate. Simulation evaluators use a separate cache that also auto-refreshes about every 10 seconds. See AuthZEN Simulation.

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 uses filter policies (partial evaluation → UCAST → GraphQL) and optional post-evaluation with data.authzen.allow. The PDP calls the external GraphQL URL on the matched Discovery data source. Configure at least one Discovery source whose communicationEP is reachable. Full walkthrough: AuthZEN Search.

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 (default 50). Responses include page.next_token and results. Simulation search URLs are under /access/v1/simulation/search/*.

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). Live evaluation and search need cidaas:authzen_evaluate. Simulation endpoints need cidaas:authzen_simulate. Live explain needs cidaas:authzen_explain.

Related Documentation

• AuthZEN Search — Discovery, filter policies, SearchConfig
• AuthZEN Simulation — live vs simulation channels
• ReBAC — graph-based permissions in Rego

info

Need Support?

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