> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/pbac/pbac-reference.md). # PBAC reference The pbac-manager service, its infrastructure dependencies, cache intervals and configuration properties, usage metering, and the REST API behind the PBAC screens. ## What this is, and when you need it The operator-facing detail behind [Decide access with policies](/administration-guide/pbac.md): what runs, what it depends on, how quickly a change propagates, and the API the screens sit on. Read it when you are deploying, tuning or automating PBAC rather than authoring policies. ## The service PBAC is delivered by **`pbac-manager`**, a Spring Boot microservice that owns policy storage, compilation and evaluation. Isolating it means policy-decision availability and latency are insulated from load on the rest of the platform. ``` Webconsole UI ── REST ──> Webconsole backend │ RabbitMQ (vhost: openiam_pbac) ▼ pbac-manager ──> Cedar engine (embedded, native) │ │ │ ├── pbac database (policies, versions, │ │ simulations, usage counters) │ ├── Redis (policy + entity caches) │ └── auth-manager (entitlement graph) └── audit log (decision log entries) ``` ## The Cedar engine Policies are compiled and evaluated by the embedded [Cedar](https://www.cedarpolicy.com/) engine (`cedar-java` 4.10.x), which bridges into Cedar's formally verified Rust evaluator through JNI. {% hint style="warning" %} **The `pbac-manager` image is glibc-based, unlike most OpenIAM services.** Cedar's native library cannot load on musl, so this service does not use the Alpine base the rest of the platform does. Use the image shipped for the release; do not rebase it onto the standard base image. A rebase produces a service that starts and then fails to evaluate anything. {% endhint %} All applicable policies for a request are merged and evaluated in a **single engine call**, so Cedar's *forbid wins* semantics apply across the whole policy set rather than policy by policy. ## Infrastructure dependencies | Dependency | Use | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **MariaDB/MySQL**, or PostgreSQL, MSSQL, Oracle | A dedicated **`pbac` database/schema** with its own connection pool, so evaluation availability is isolated from the shared `openiam` database. Migrations ship with the standard Flyway tooling — the `FLYWAY_PBAC_*` installer settings | | **RabbitMQ** | A dedicated vhost **`openiam_pbac`** carrying three queues: policy management, authorization decisions, and simulations. Decision traffic is isolated from authoring and simulation traffic, so a heavy simulation cannot delay live decisions. Created by the standard init scripts (`rabbitmqctl add_vhost openiam_pbac`) | | **Redis** | Distributed caches for compiled policies and Cedar entity snapshots | | **Vault** | Database credentials — `SECRET_PBAC_JDBC_USERNAME` and `SECRET_PBAC_JDBC_PASSWORD`. See [Rotate service credentials](/administration-guide/security/rotate-service-credentials.md) | | **OpenSearch** | Used indirectly: decision-log queries go to the audit index, and random simulation subjects are drawn through user search | A `pbac-manager` helm chart ships with the release — StatefulSet, anti-affinity across nodes, default requests of 100m CPU and 1Gi memory. {% hint style="warning" %} **The `pbac` database is one of seven, and backup procedures written before 2026.7.1 will not include it.** Confirm your backup and restore covers it before you rely on either — see [What a backup and restore must cover](/administration-guide/platform/backup-and-restore-scope.md). {% endhint %} ## Caching and propagation `pbac-manager` keeps active policies and entity snapshots in layered caches. | Cache | Contents | Refresh | | ------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------- | | Policy write sweep | `ACTIVE` policies with their current version, database → Redis | `org.openiam.pbac.policy.cache.sweep.time` ms, default `300000` (5 min) | | Policy read sweep | Redis → per-node memory | `org.openiam.pbac.policy.cache.read.sweep.time` ms, default `60000` (60 s) | | Principal entities | Cedar snapshot of a user and their entitlements | Local TTL 5 min, Redis TTL 15 min | | Resource entities | Cedar snapshots of groups, roles, organizations, resources | Local TTL 5 min, Redis TTL 15 min | What that means in practice: * A **status or enforcement-mode change** is visible on every node after at most write sweep + read sweep — about **6 minutes** with defaults. * A change to a user's **attributes or entitlements** may take up to the entity-cache TTL — about **15 minutes** — to affect decisions. A policy that reads an attribute you just changed will keep deciding on the old value until then. * A policy version that **fails to compile during a sweep is skipped and logged**, not fatal. It is picked up again once fixed. * From 2026.10.2 a **policy save, status change or mode change also publishes a change notice** on the cache exchange, and every node refreshes its policies at once. The sweeps remain as the fallback when the notice is lost. Configuration properties, with shipped defaults: {% code overflow="wrap" expandable="true" %} ```properties org.openiam.pbac.policy.cache.sweep.time=300000 org.openiam.pbac.policy.cache.read.sweep.time=60000 org.openiam.pbac.usage.counter.flush.time=30000 org.openiam.pbac.cedar.principal.cache.local.ttl.minutes=5 org.openiam.pbac.cedar.principal.cache.redis.ttl.minutes=15 org.openiam.pbac.cedar.principal.cache.max.size=100000 org.openiam.pbac.cedar.resource.cache.local.ttl.minutes=5 org.openiam.pbac.cedar.resource.cache.redis.ttl.minutes=15 org.openiam.pbac.cedar.resource.cache.max.size=200000 org.openiam.pbac.cedar.adhoc.policy.cache.ttl.minutes=60 org.openiam.pbac.cedar.adhoc.policy.cache.max.size=200 org.openiam.pbac.mcp.catalog.url= org.openiam.pbac.mcp.catalog.refresh.seconds=600 org.openiam.pbac.log.nopolicy.invokingsystems=mcp ``` {% endcode %} The last three arrived in 2026.10.2 for the MCP server: where to read the server's tool catalog, which gives the service the tool action groups and tool resources, how often to re-read it, and the invoking systems whose decisions are logged even when no policy governs them. They are explained in [Decide MCP tool calls with policies](/administration-guide/federation/mcp-server/mcp-policies.md). ## Usage metering Decision volume is metered per policy into hourly buckets — `PBAC_USAGE_COUNTER` in the `pbac` schema — flushed asynchronously off the decision path. **Shadow evaluations are counted**, because the per-policy count is the exposure figure used to judge a rollout. Users skipped by a partial rollout are not counted. Usage counters survive policy deletion. ## REST API The Webconsole exposes PBAC administration under its own context, `/webconsole/rest/api/…`. All endpoints require an authenticated Webconsole session with administrative rights. **Policies — `/rest/api/pbac/policies`** | Verb | Path | Description | | -------- | ----------------------------------- | ---------------------------------------------------------------------------------- | | `GET` | `/` | Search policies — `name`, `status`, `from`, `size` | | `GET` | `/{id}` | Read one policy including its version history | | `POST` | `/` | Create or update a policy header | | `POST` | `/version` | Append a version. The body must not carry an id; the author comes from the session | | `POST` | `/{id}/current-version/{versionId}` | Make a version current — activate or roll back | | `DELETE` | `/{id}` | Delete the policy and all its versions | **Simulations — `/rest/api/pbac/simulations`** | Verb | Path | Description | | -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/` | Search runs — `policyVersionId`, `mode`, `status`, paging | | `GET` | `/{id}` | Read one run; used for polling | | `GET` | `/{id}/subjects` | Page through per-subject results — `decision`, `errored`, paging. Page size capped at 200 | | `POST` | `/` | Launch a run; returns the run id immediately. From 2026.10.2 the body may carry `actionType` `MCP_TOOL` and an `mcp` record, to simulate a tool call on the MCP server; the record is used for the run and not stored with it | | `POST` | `/{id}/cancel` | Cancel a running run. Results so far are kept | | `DELETE` | `/{id}` | Delete a run and its subject rows | **Decisions — `/rest/api/pbac/decisions`** | Verb | Path | Description | | ----- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/` | Search decisions — `principalId`, `resourceId`, `decision`, `from`, `to`, paging, and from 2026.10.2 `invokingSystem`, `agentNhiId`, `toolName`, `mode` and `wouldChange`. Page size capped at 200 | | `GET` | `/{id}` | Read one decision entry | | `GET` | `/impact` | From 2026.10.2: what one policy would change for MCP tool calls — `policyId`, `from`, `to`, `sample` (how many would-change calls to return, default 10) | **Page metadata — `/rest/api/ui/metadata/pbac`** Returns the vocabulary the editor builds policies from: principal and resource entity types with their attributes, the context attributes supplied at decision time with locale-aware value labels, and the deployment's access rights with their Cedar action identifiers. Cedar text is validated by compilation at the API boundary, so a version that does not compile is rejected with the compiler's error message — the same behaviour as the editor. ## Related * [Decide access with policies](/administration-guide/pbac.md) — the section this supports * [Roll a policy out safely](/administration-guide/pbac/roll-out-a-policy.md) — where the sweep intervals above become operational * [Rotate service credentials](/administration-guide/security/rotate-service-credentials.md) — the `pbac` vault keys * [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md) — where `pbac-manager` sits among the services * [Decide MCP tool calls with policies](/administration-guide/federation/mcp-server/mcp-policies.md) — the catalog and the properties above *Applies to OpenIAM 2026.8.1. Last reviewed 20 October 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/administration-guide/pbac/pbac-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.