An architecture review is running late. The platform team has a proposal on the screen: "Move all authorization into the API gateway. One place to write rules, one place to audit, and the services get simpler." The gateway already validates every token, checks the audience and maps routes to scopes. Adding a few more rules there sounds like tidying up.
Someone asks one question: "When broker u-broker-n1 asks for GET /quotes/Q-6620, what does the gateway know about Q-6620?" It knows the URL, the token and the scope quotes.read. It does not know that Q-6620 belongs to the brokerage brk-south; that fact lives in the quote service's database. A gateway that "decides" here can only say yes to every quote, or no to every quote.
This site's own case UW-A03 runs exactly that design. The gateway passes a valid token with the right scope, the quote service trusts the gateway, and another tenant's quote comes back with status 200. Nothing crashed. The decision was made in a place that could not see what it was deciding about.
This page is about where each part of an access decision lives, and what each part does when another is stale or down.
Four jobs, four names#
Take the peer underwriter's attempt from the previous chapters. Underwriter u-uw-w2 works in unit commercial-west and is assigned to SUB-1007. In the underwriter cockpit, u-uw-w2 opens SUB-1004, which is assigned to a colleague, and presses "record decision". Four different jobs happen before anything is written.
Someone has to stop the request and ask. In the example that is the code behind POST /submissions/{id}/decision: it holds the request, builds a question ("may this subject perform decision.record on SUB-1004, now?"), and obeys the answer. That code is the policy enforcement point (PEP). A tiny example: a servlet filter that returns 403 when a function says no.
Someone has to evaluate the rules. In the example that is pdp.decide in examples/uw-auth/pdp.py: pure code that takes subject, action, resource and context and returns allow or deny, a status, the rule that decided, a reason and the policy version. That is the policy decision point (PDP). Here it answers deny, 403, rule R-AZ-09, "underwriter is not assigned to SUB-1004".
Someone has to supply facts the request does not carry. The token says who u-uw-w2 is. It does not say which submissions are assigned to whom today, which unit SUB-1004 belongs to, or how recently u-uw-w2 used a phishing-resistant authenticator. Those come from the directory (roles, unit, assignments, entitlements), the record store (tenant, unit, risk tier of the submission) and the identity provider's session (acr, auth_time). Each source is a policy information point (PIP).
Someone has to write, review and release the rules. In the example the rules are code, released as named versions: authz-2026.11.1 (current) and authz-2026.10.3 (previous). The place where policy is authored and approved is the policy administration point (PAP). Here it is a code review and a test suite, not a product.
Plain English. The PEP asks and obeys, the PDP decides, the PIPs know things, the PAP writes the rules. Four jobs; they may run in one process or four, but they never merge into "the gateway decides".
Before AI. Spring Security already splits these jobs. The filter chain and method interceptors are enforcement points; an AuthorizationManager makes the decision; a user lookup or an LDAP group query supplies facts; the security configuration in the repository is the policy. A reverse proxy in front of a Java service has always been a coarse enforcement point that cannot see rows.
Where the names come from, and which vocabulary is which#
The four names are older than most current products. Standard (XACML 3.0, OASIS Standard, 22 January 2013, read 2026-11-18): the PEP is "The system entity that performs access control, by making decision requests and enforcing authorization decisions"; the PDP is "The system entity that evaluates applicable policy and renders an authorization decision"; the PIP is "The system entity that acts as a source of attribute values"; the PAP is "The system entity that creates a policy or policy set". This page uses that vocabulary.
Zero trust architecture uses an overlapping but different set. Guideline (NIST SP 800-207, read 2026-11-18): the PDP is "broken down into two logical components: the policy engine and policy administrator". The policy engine (PE) makes "the ultimate decision to grant access to a resource for a given subject"; the policy administrator (PA) establishes or shuts down "the communication path between a subject and a resource (via commands to relevant PEPs)"; the PEP enables, monitors and terminates connections. Note the trap: NIST's policy administrator opens and closes sessions at run time, while XACML's policy administration point authors rules. Same initials, different jobs. NIST also says it took the PDP and PEP concepts from XACML.
A newer standard, OpenID AuthZEN Authorization API 1.0 (Final, 11 January 2026), defines the wire between PEP and PDP; it is described further down.
| Vocabulary | Who decides | Who enforces | Who supplies facts | Who manages policy | Scope |
|---|---|---|---|---|---|
| XACML 3.0 (standard) | PDP | PEP | PIP (through a context handler) | PAP (authors policy) | any application request |
| NIST SP 800-207 (guideline) | PE, inside the PDP | PEP | data sources (identity, threat feeds, logs) | PA (opens and closes sessions at run time) | enterprise access to resources |
| AuthZEN 1.0 (standard) | PDP, serves the API | PEP, calls the API | not specified | not specified | the request and response between PEP and PDP |
| This example (code) | pdp.decide | quote service, assessment service, tool server, cockpit BFF | directory, record store, identity provider session | reviewed versions authz-2026.11.1, authz-2026.10.3 | every sensitive hop |
The smallest enforcement point#
The PEP is small on purpose. Its job is to ask the right question and obey, and to have a defined answer when it cannot ask. This is the whole PEP call in the example, services.py pep_decide, quoted as it is:
def pep_decide(subject: dict[str, Any] | None, action: str, resource: dict[str, Any], context: dict[str, Any],
*, pdp_available: bool = True, policy_version: str = pdp.CURRENT_POLICY) -> dict[str, Any]:
"""The enforcement point's call to the PDP. If the PDP is unreachable: fail closed (503), never allow."""
if not pdp_available:
return {"allow": False, "status": 503, "rule": "PEP-FAIL-CLOSED",
"reason": "policy decision point unavailable: fail closed", "policy_version": policy_version,
"obligations": ["write audit record", "raise availability alert"]}
return pdp.decide(subject, action, resource, context, policy_version)
Three details carry the design. The subject comes from validated claims plus the directory (subject_from_claims), never from a request parameter. The resource is built from the record (resource_for(record_id)). And an unreachable PDP produces a denial with its own rule name, never a silent pass.
In our insurance example. The quote service, the assessment service, the tool server and the cockpit BFF are all PEPs, and all call the same PDP. The broker sees quoteQ-5531; the insurer works it as submissionSUB-1004; every PEP decides on the record both ids point to.
Gateway check versus service check#
Now the review's proposal, run. The snippet below demonstrates where each check runs for the broker's request for the other tenant's quote, with and without the service's own check. A successful run proves which component decided in this simulation; it does not prove anything about a particular gateway product.
import services
for toggles in ({"gateway_only": True}, {}):
r = services.request_path("other", toggles)
print("toggles:", toggles or "none", "->", r["outcome"])
for h in r["hops"][1:]:
print(f" {h['hop']:<11} decision={h['decision']:<16} decided_by={h['decided_by']}")
Run in a scratch copy of examples/uw-auth on 2026-11-18:
toggles: {'gateway_only': True} -> {'status': 200, 'data_returned': True, 'leaked': True}
2 gateway decision=pass decided_by=svc-api-gateway
3 service decision=no object check decided_by=nobody
4 database decision=rows: 1 decided_by=nobody
toggles: none -> {'status': 404, 'data_returned': False, 'leaked': False}
2 gateway decision=pass decided_by=svc-api-gateway
3 service decision=deny 404 decided_by=pdp R-AZ-03
4 database decision=not reached decided_by=nobody
The gateway line is identical in both runs, and correct both times: the token was genuine, meant for the quote API, unexpired and carried quotes.read. The difference is at hop 3. With the service check, the PDP compares tenant brk-south on the record with tenant brk-north on the subject and answers 404. Without it, nobody decided, and the database returned the row because the query asked by id only.
That failure has two names. Guideline (OWASP API Security Top 10 2023, read 2026-11-18): API1 is Broken Object Level Authorization (BOLA): "Object level authorization is an access control mechanism that is usually implemented at the code level." The older name for the same hole is insecure direct object reference (IDOR): the caller changes an identifier in the request and reaches an object the server never checked. The OWASP Microservices cheat sheet says it in one line: "Gateway checks complement these controls; they do not establish that a downstream operation is authorized."
Diagram: Three layers on one request · what each can see, decide and miss
Rows are the three places a check can run for the broker's request for Q-6620. Read across a row for one layer. The gateway sees the token but never the record, so it can refuse a bad token and cannot refuse a valid token asking for the wrong record. The quote service loads the record and asks the policy decision point. The repository adds the tenant from the verified context to the query, a last line that returns nothing even if a check was forgotten.
- API gateway
- token, route, scope: The bearer token, its signature, issuer, audience, expiry and scope, and the route that was called.
- bad token: 401 missing scope: 403: Refuses forged, expired or misdirected tokens and requests without the coarse scope, early and cheaply.
- whose record Q-6620 is: The tenant of the record lives in the quote service's database. A gateway-only check passes every quote (UW-A03).
- Quote service
- subject + the record: The subject built from validated claims and the directory, and the record with its tenant, unit and assignment.
- PDP on the record: Asks the policy decision point about this action on this record and obeys the answer.
- paths that skip the service: An export job or a direct database reader that never calls the service never meets this check.
- Repository
- id + tenant from verified context: The repository takes the record id from the request and the tenant or unit from the verified subject, never from parameters.
- zero rows: A forgotten service check still returns nothing for another tenant's record.
- actions and assignments: A tenant predicate cannot express 'only the assigned underwriter may decide'. It is a backstop, not the policy.
Read the diagram row by row: the gateway refuses bad tokens early, the service is the only place that sees the record, and the repository's predicate makes a forgotten check return nothing. Whether to answer 404 or 403 for the other tenant's record is decided on Authorization.
The four-hop lab starts on this preset: the gateway-only check, broker u-broker-n1, quote Q-6620. Switch the gateway-only toggle off and watch who decides at hop 3.
| Preset | Own quote Q-5531 | Other tenant's Q-6620 | What it shows |
|---|---|---|---|
| default | 200 (PDP rule R-AZ-03) | 404 (PDP rule R-AZ-03) | A valid token is not a permission: the service asked the PDP about this quote and answered 404, without revealing it exists. |
| bola | 200 (nobody checked the record) | 200, leaked (nobody checked the record) | BOLA: the gateway passed a valid token with the right scope, and nobody checked the record. |
The agent here is a scripted stand-in, so these results show how the access controls work, not how good any model is.
Common confusion. "Centralize authorization" can mean two different things. Centralizing the rules (one policy, one review, one version) is a good idea. Centralizing the enforcement in one network hop is not, because the hop cannot see most of what the rules talk about.
Who supplies which fact#
The PDP is only as right as the facts it receives. Here is the peer underwriter's request again, as the policy lab shows it: subject, action, resource, context, the version, and the layer that supplied each fact.
Diagram: Who asks, who decides, who knows, who writes · the peer underwriter's decision on SUB-1004
Read left to right. The cockpit backend is the enforcement point: it holds the request and asks. The policy decision point evaluates rule R-AZ-09 under version authz-2026.11.1. It needs facts the token does not carry: the assignment from the directory, the unit of the submission from the record store, the strength and time of the last sign-in from the session. The reviewed policy versions come from the administration point. The answer is deny, 403, because u-uw-w2 is not assigned to SUB-1004.
- Ask and obey
- cockpit backend: Holds POST /submissions/SUB-1004/decision, builds the question, obeys the answer, writes the audit record.
- Decide
- pdp.decide: Pure code: subject, action, resource, context and a policy version in; allow or deny, status, rule, reason and obligations out.
- Supply facts
- directory: Workflow data that changes during the day, read at decision time instead of trusted from a token claim.
- record store: Attributes of the resource itself, loaded by the service.
- sign-in session: How and when the person last authenticated, from the identity provider's assertion held by the cockpit backend.
- Write the rules
- reviewed versions: Policy written as code, reviewed and tested, released under a version name. The previous version authz-2026.10.3 lacks the assignment check.
The important observation is the arrow from the directory. The token issued to u-uw-w2 at 08:50 cannot say that a team lead reassigned SUB-1004 at 08:55. Assignment is workflow data; it changes during the day. That is why the PDP reads it from a PIP at decision time instead of trusting a claim, and why every cache in front of the PDP has to be honest about staleness (below).
The policy lab lets you change each fact and each version. It opens on the assigned underwriter u-uw-w1, after step-up, recording a decision on SUB-1004 under the current policy.
| Subject | Request | authz-2026.11.1 | authz-2026.10.3 | Reason (current) |
|---|---|---|---|---|
| assigned underwriter u-uw-w1, cockpit, step-up now | decision.record SUB-1004 | allow 200 (R-AZ-09) | allow 200 | assigned underwriter decides through the cockpit after step-up |
| peer underwriter u-uw-w2, cockpit, step-up now | decision.record SUB-1004 | deny 403 (R-AZ-09) | allow 200 (drift) | underwriter is not assigned to SUB-1004 |
| u-uw-w1, basic login 600 s ago | decision.record SUB-1004 | deny 401 (R-AZ-09) | deny 401 | step-up required: strong authentication within 300 s |
| u-uw-e1 (commercial-east), step-up | decision.record SUB-1004 | deny 404 (R-AZ-09) | deny 404 | record belongs to another business unit: not found (existence not revealed) |
| underwriting agent with a misgranted cockpit client | decision.record SUB-1004 | deny 403 (R-AZ-09) | deny 403 | an agent or service principal never records an underwriting decision |
Who supplies what in the lab: PEP = svc-quote, svc-assessment, the tool server, svc-cockpit-bff (ask and obey); PDP = pdp.decide; PIP = the directory (roles, unit, assignments, entitlements) and the session (acr, auth_time); PAP = the reviewed policy versions. The second row, where the old version allows what the current one denies, is the subject of Policy as code.
Central administration, local enforcement#
Once the four jobs are separate, a design question appears: where does the PDP run? Three shapes are common (each a Pattern; no standard mandates one).
A library in the service. The PDP is a function called in-process, as pdp.decide is in the example. No network hop, no new outage; but every service must ship the same policy version, so drift between services is easy.
A local decision service next to each service. A sidecar or host daemon, called over localhost, with policy and data pushed from a central place. Product (OPA, as documented on 2026-11-18): bundles are "gzipped tarballs (.tar.gz) that contain policies and/or data", downloaded "from a remote HTTP server" on a polling interval, optionally signed, with a revision string in the manifest. One administration point, many local decision points.
A central decision service. Every PEP calls one PDP over the network, for example through the AuthZEN API. One place holds the policy and the freshest facts. The cost is a network call on every decision and a dependency whose outage stops every service that asks it.
| Shape | Decision latency | Policy freshness | Outage blast radius | Typical trigger to adopt |
|---|---|---|---|---|
| Library in the service | lowest (in-process) | as fresh as the last release | none added | one or two services, one team |
| Local decision service (sidecar) | low (localhost) | as fresh as the last bundle pull | one host | many services, one policy team, rules change weekly |
| Central decision service | a network call | freshest | every service that calls it | facts that only one place has (relationships, live assignments) |
This site's recommendation: administer centrally and enforce locally. Keep one policy source, one review and one version number (the PAP); evaluate as close to the PEP as the facts allow. The example is the first shape, which is the simplest credible design for a handful of services. The trigger to grow is a second team writing rules for the same resources, or a fact (such as a relationship graph) that no single service owns.
What this is not. NIST's zero trust architecture applies the same split to network sessions: which device and user may open a connection to which resource. It does not define business authorization inside an application. Gateways, service meshes and zero trust tenets are on Gateways and zero trust.
Caching decisions, and the invalidation problem#
A PDP call on every request costs something, even in-process: a directory lookup for assignments, a record lookup for the tenant. The natural next step is a decision cache: remember the answer for a subject, action and resource for a short time. It is also the most common way a correct policy starts making wrong decisions.
The sketch below was written for this page, not taken from the example. It wraps pdp.decide in a 60-second cache (illustrative) and then changes the directory: at 09:00:20 SUB-1004 is reassigned away from u-uw-w1. A successful run demonstrates what a cache key forgets; it is not a recommended cache design, and it caches a protected write only to make the mistake visible.
# A decision cache written for this page (not part of the example), wrapped around pdp.decide.
import pdp
from clock import START_EPOCH_S as NOW
from directory import ACR_STRONG, resource_for, subject_for
TTL_S = 60 # illustrative
cache: dict[tuple, tuple[int, dict]] = {}
def cached_decide(subject, action, resource, now, version=pdp.CURRENT_POLICY, directory_version=1):
key = (subject["principal_id"], action, resource["id"], version, directory_version)
hit = cache.get(key)
if hit and now < hit[0]:
return dict(hit[1], cache="hit")
d = pdp.decide(subject, action, resource, {"now": now}, version)
if d["status"] != 401: # never cache a step-up challenge
cache[key] = (now + TTL_S, d)
return dict(d, cache="miss")
res = resource_for("SUB-1004", "submission")
w1 = subject_for("u-uw-w1", now=NOW, acr=ACR_STRONG, auth_time=NOW, client_id="svc-cockpit-bff")
print("09:00:00", cached_decide(w1, "decision.record", res, NOW)["cache"], "allow")
# 09:00:20 the submission is reassigned away from u-uw-w1 (the directory changes).
moved = dict(w1, assignments=[])
d = cached_decide(moved, "decision.record", res, NOW + 20)
print("09:00:20 key without directory version:", d["cache"], "allow" if d["allow"] else "deny")
d = cached_decide(moved, "decision.record", res, NOW + 20, directory_version=2)
print("09:00:20 key with directory version 2: ", d["cache"], "allow" if d["allow"] else "deny", "|", d["reason"])
09:00:00 miss allow
09:00:20 key without directory version: hit allow
09:00:20 key with directory version 2: miss deny | underwriter is not assigned to SUB-1004
The second line is the bug. The facts changed, the key did not, and for up to 60 seconds a person who is no longer assigned can still record a decision. The third line is one fix: put a version of every fact the decision depends on into the key, and bump it when the fact changes. Then the stale entry is never read again.
| Cache choice | What can go stale | Safe when |
|---|---|---|
| Key on subject, action, resource only | role, assignment, record attributes, policy version | never for writes |
| Add policy version to the key | facts in the directory and the record | policy changes are the only change you expect |
| Add a version (or change counter) per fact source | nothing, if every source bumps its version | the PIPs can publish change events |
| Short TTL on reads | any answer, for up to the TTL | reads of low-sensitivity data |
| No cache for a protected write | nothing | decision.record, admin actions, anything irreversible |
This site's recommendation: do not cache decisions for protected writes at all; the cost of one PDP call is small next to an underwriting decision. For reads, cache with a short TTL and include the policy version and a version of every fact source in the key. Never cache a step-up challenge (401): it depends on the clock. How cached policy is purged during an incident is on Operations.
When the policy decision point is down#
The cockpit BFF sends decision.record for SUB-1004 at 09:14. The PDP does not answer: a deploy went wrong, or the network between them is partitioned. The PEP has three choices: allow (fail open), deny (fail closed), or decide something itself. Only the second keeps the policy true.
The snippet demonstrates the example's answer, case UW-A23: the cockpit's write and a broker's read, both with the PDP unavailable. A successful run proves nothing was written; it does not show how a real outage is detected.
import services
import tokens
from clock import START_EPOCH_S as NOW
from directory import ACR_STRONG
platform = services.Platform(NOW)
session = {"principal_id": "u-uw-w1", "acr": ACR_STRONG, "auth_time": NOW}
down = platform.cockpit_record_decision(session, "SUB-1004", "refer_to_inspection",
"roof ages differ", "req-1", pdp_available=False)
print("PDP down, decision.record:", down["status"], down["decision"]["rule"], "|", down["decision"]["reason"])
print("obligations:", down["decision"]["obligations"])
print("decisions written:", len(platform.decisions))
tok = tokens.issue_for("u-broker-n1", aud=tokens.API_AUD, now=NOW)
read = platform.read_quote(tok, "Q-5531", "req-2", pdp_available=False)
print("PDP down, quote.read:", read["status"], "body:", read["body"])
PDP down, decision.record: 503 PEP-FAIL-CLOSED | policy decision point unavailable: fail closed
obligations: ['write audit record', 'raise availability alert']
decisions written: 0
PDP down, quote.read: 503 body: None
Both requests got 503, not 403 and not 200. The status says what happened: the service is temporarily unable to decide, which is different from "you are not allowed". The obligations say what the PEP must still do: write an audit record of the refusal and raise an availability alert, so that a person learns about the outage from the alert and not from an underwriter's complaint. This is fail closed: when a check cannot run, the action does not happen.
Diagram: The policy decision point is down · the write fails closed (UW-A23)
Time runs down the page. The assigned underwriter records a decision through the cockpit. The enforcement point asks the policy decision point and gets no answer. It does not guess and does not allow: it answers 503, writes an audit record of the refusal and raises an availability alert. Nothing is written to the submission.
- Underwriter u-uw-w1 to Cockpit backend (PEP): record decision. The person acts through the cockpit.
- Cockpit backend (PEP) to Policy decision point: decide decision.record. The enforcement point asks about this subject, action and record.
- Policy decision point to Cockpit backend (PEP): no answer. Timeout or connection refused. No decision exists.
- Cockpit backend (PEP) to Audit + alerts: audit + alert. The refusal is recorded and a person is told about the outage.
- Cockpit backend (PEP) to Underwriter u-uw-w1: 503: try again later. Temporarily unable to decide, which is different from not allowed. Nothing was written.
Fail closed is a property of the PEP's code path, and it is easy to lose by accident. A try/except that logs the PDP error and continues is fail open. A client library whose timeout returns None, followed by if decision and not decision["allow"]: deny(), is fail open. Standard (AuthZEN 1.0): for a batch of evaluations, "Decisions default to closed (i.e. false)", but the specification read here gives no required PEP behaviour for a PDP that does not answer at all; that part is your code. Standard (XACML 3.0): PEPs "are required to deny access" unless they "understand and can discharge all of the" obligations of the applicable policy. The same reasoning covers the obligations above: a PEP that cannot write the audit record should not perform the write.
Availability and safety are different questions. A team may accept that a broker reads their own quote during a PDP outage, because the repository predicate still blocks the cross-tenant read; that is a documented degraded mode for one action, never a default. Protected writes stay closed. In the identity provider outage of the same case, no new step-up can be obtained, so decision.record answers 401 and nothing is written.
Production pitfall. A PDP whose port answers is not proof that it decides correctly. Probe it with a known deny (the peer underwriter on SUB-1004) and alert if it ever returns allow.
A standard wire between PEP and PDP#
When the PDP is a separate service, the PEP and PDP need a protocol. Teams used to invent one per engine. Standard (AuthZEN Authorization API 1.0, read 2026-11-18): the PEP sends an HTTPS POST with a JSON Access Evaluation request of subject, action and resource (required) and an optional context, to the default path /access/v1/evaluation; the PDP answers with a boolean decision. The specification defines the request and response, not the policy language, and leaves authentication between PEP and PDP out of scope while saying "the PDP SHOULD authenticate the calling PEP". The full exchange for the peer underwriter is folded below.
AuthZEN on the wireThe peer underwriter's request as an Access Evaluation
Each entity may carry an optional properties object; subject and resource have type and id, the action a name. A batch form lives at /access/v1/evaluations, search APIs at /access/v1/search/subject, /access/v1/search/resource and /access/v1/search/action, and metadata at /.well-known/authzen-configuration. The field layout below follows the specification; the values are the example's; the host is invented and this exchange was not run against a real PDP.
POST /access/v1/evaluation HTTP/1.1
Host: pdp.internal.example
Content-Type: application/json
Authorization: Bearer <token of svc-cockpit-bff for the PDP>
{"subject": {"type": "user", "id": "u-uw-w2",
"properties": {"roles": ["underwriter"], "business_unit": "commercial-west",
"acr": "urn:insurer.example:acr:phishing-resistant"}},
"action": {"name": "decision.record"},
"resource": {"type": "submission", "id": "SUB-1004",
"properties": {"business_unit": "commercial-west", "risk_tier": "standard"}},
"context": {"client_id": "svc-cockpit-bff", "authz_policy_version": "authz-2026.11.1"}}
HTTP/1.1 200 OK
Content-Type: application/json
{"decision": false,
"context": {"reason": "underwriter is not assigned to SUB-1004", "rule": "R-AZ-09"}}
Two things to notice. The response is 200 with decision: false: the PDP answered, and the answer is no. The PEP turns that into 403 for the cockpit (or 404, where existence must be hidden). And the assignment is not in the request: the PDP looks it up from its own PIP.
Whether the PEP sends facts or the PDP fetches them is a design choice; Policy as code shows both, because OPA expects them in the input while OpenFGA keeps them as stored relationships.
In a coding agent. The coding agent pushes through a repo-scoped GitHub App installation; branch protection is the enforcement point that refuses a direct push to the default branch; its rules are the policy, changed only by admins. The sandbox holds no production database credential. See Coding agents.
Choosing where checks run#
| Case | Simplest credible design | Grow when | Alternatives |
|---|---|---|---|
| One service, one team | Token validation in the service; a PDP function in-process; repository predicate | a second service needs the same rules | a shared library with the policy |
| Microservices behind a gateway | Gateway: token, audience, coarse scope. Every service: object check through a local PDP | rules change weekly, several teams | sidecar policy engine with central bundles |
| Facts owned by one system (assignments, relationships) | A central decision service that owns those facts | latency or outage risk of the central call hurts | replicate the facts to local PDPs, with versions |
| Agent tool calls | The tool server is a PEP for every call, plus the downstream service | tools shared across teams | an MCP or API gateway for coarse checks, never instead of the service |
A check belongs where its facts are visible, and every sensitive hop decides again on the record.
Security notes#
- The PEP builds the subject from validated credentials and the directory, never from request parameters or headers such as
x-app-id. - Every path to the data is a PEP: the API, the export job, the search index, the agent's tool server.
- An unreachable PDP, an error, a timeout or an unknown answer is a denial. Write a test for each.
- Decision logs record the policy version, the rule and the reason, and never the token (see Audit).
- The PDP's own API is a protected resource: authenticate the PEPs that call it.
Monday checklist#
- For each route, write down which component checks the token and which one checks the record. Any route where the answer is "the gateway" for both is a BOLA candidate.
- A test that sends a valid token with the right scope for another tenant's record and expects 404 at the service, not at the gateway.
- A test that makes the PDP unreachable and expects 503 and no write.
- Review every cache in front of a PDP: what is in its key, what invalidates it, and whether it ever stores a decision for a protected write.
- A synthetic deny probe against the PDP in monitoring.
Exercises#
Exercise 1. The platform team proposes adding a rule at the gateway: "brokers may only call GET /quotes/{id} where {id} starts with their tenant prefix." Does that close UW-A03?
AnswerIt moves a fact into the URL; it does not check the record
Only if every quote id encodes its tenant forever and no other id (such as SUB-2001) reaches the same record. It fails for the submission id, for any record created before the convention, and the moment ids are reissued. The tenant is an attribute of the record; check it at the service against the record.
Exercise 2. A PEP calls the PDP with a 200 ms timeout. On timeout, the client library returns {"allow": None}, and the PEP does if result["allow"] is False: return 403. What happens during a PDP outage?
AnswerFail open: None is not False
Every request passes, because None is False is false. Test for the allow case explicitly (if result.get("allow") is not True: deny) and return 503 when no decision arrived.
Exercise 3. Where is the PIP for auth_time in the example, and why can the cockpit BFF not take it from a request header?
AnswerThe identity provider session behind the BFF
It comes from the authenticated session the cockpit BFF holds (originally the identity provider's assertion of when the underwriter last authenticated). A header is written by the client, so a client could claim a step-up that never happened.
Advanced perspective#
Push or pull factsWho fetches the attributes decides who can be stale
In a push design the PEP sends every fact in the request (OPA's input, AuthZEN properties). The PDP is stateless and easy to test, but the PEP must know which facts each rule needs, and a PEP that forgets one gets a decision on missing data. Product (OPA, as documented on 2026-11-18): "Expressions that refer to undefined values are also undefined", so a rule body that reads a missing field never becomes true, and default allow := false supplies the answer. That is safe for allow rules and dangerous for deny rules written as "deny if X". In a pull design the PDP fetches facts from PIPs itself. The PEP stays simple and the facts are fresher, but the PDP now depends on every PIP at decision time, and its latency and failure modes become theirs. A common middle: the PEP pushes what it already holds (validated claims, the record it loaded), and the PDP pulls what only it can know (relationships, live assignments). Write the rule's required inputs down next to the rule, and have the PDP deny when a required one is absent.
The PEP as a confused deputyWhose authority does the PEP ask about?
A service with broad rights that asks the PDP about itself instead of about its caller launders authority. The assessment service may read every submission's roof report for its own batch jobs; when it acts for the underwriting agent, the PEP must ask "may the agent, acting for u-uw-w1 inside task run-7f3a, read SUB-1004?", not "may the assessment service?". In the example, subject_from_claims makes the actor in an act claim the subject, with the delegation attached, so the PDP sees the agent and its task. Service identity answers "which program is calling"; the decision is about the principal the request is for. Depth is on Agents and on the MCP site's authorization chapter.
Obligations and adviceA decision can carry work the PEP must do
A plain allow or deny is not always enough. The example's decisions carry obligations: "write audit record", "filter results to business_unit commercial-west" on precedent search, "the recommendation is advisory: a person decides" on recommendation.record, and for break-glass "raise security alert" and "open mandatory post-use review". XACML formalized this: an obligation is "An operation specified in a rule, policy or policy set that should be performed by the PEP", and a conforming PEP denies when it cannot discharge one. AuthZEN's response context can carry such data, but the specification read here does not define obligations as a typed concept, so a team that relies on them must define the contract and test that every PEP honours it. A filter obligation is the riskiest kind: the PDP allowed a search on the condition that results are filtered, and a PEP that skips the filter turns an allow into a leak.
Latency without numbersWhat actually costs time in a decision
The evaluation of a rule set like the example's is rarely the slow part. The cost is in fetching facts (a directory round trip, a record lookup, a relationship graph walk) and in the network hop to a remote PDP. Measure your own system before choosing a shape; no figure from a vendor page transfers to your policies and data. The design levers, in order of safety: co-locate the PDP with the facts it needs; batch decisions for list pages (AuthZEN's evaluations endpoint, or a predicate pushed into the SQL query); cache facts with versions rather than decisions; and only then cache decisions for low-risk reads.
In one breath#
An access decision has four jobs: the PEP asks and obeys, the PDP decides, the PIPs supply facts the request does not carry, and the PAP writes and releases the rules. The gateway is a fine PEP for the token and a blind one for the record, which is why UW-A03 leaks and why every service that owns data asks again on the record. Caches must carry the versions of the facts they depend on, and protected writes are not cached. When the PDP cannot answer, the PEP fails closed with 503, writes the audit record and raises an alert.
The enforcement point now asks the right question in the right place. What it asks about, the rule R-AZ-09 and its versions, is still a block of Python that only its author can review. Policy as code writes the same rule in six engines, and shows why a decision log must name the version that decided.