All chapters
  1. Start hereA valid token is not a permission
  2. Foundations · 1Identity and trust primitives: who is calling, and who checks
  3. Foundations · 2People and identity proofing: accounts, passwords and recovery
  4. Foundations · 3Sessions and browser security: cookies, CSRF, XSS and the BFF
  5. Foundations · 4Authenticators and MFA: passwords, passkeys and phishing resistance
  6. Foundations · 5API keys and application credentials: what a key proves
  7. Foundations · 6Tokens: bearer, JWT anatomy, validation and revocation
  8. Foundations · 7OAuth, OpenID Connect and federation: delegation and login
  9. Authorization · 8Authorization from first principles: subject, action, resource, context
  10. Authorization · 9Access control models: RBAC, ABAC, ReBAC and ownership
  11. Authorization · 10The enforcement architecture: PEP, PDP, PIP and PAP
  12. Authorization · 11Policy as code: versions, tests, engines and decision logs
  13. Authorization · 12Tenant and data isolation: one platform, many brokerages
  14. Authorization · 13Identity governance and lifecycle: joiner, mover, leaver
  15. Authorization · 14Privileged access: standing rights, just-in-time elevation and break-glass
  16. Workloads · 15TLS, PKI and certificates: proving a host, and a client
  17. Workloads · 16Workload and service identity: SPIFFE, mTLS and caller allowlists
  18. Workloads · 17API gateways and zero trust: the edge checks, the service decides
  19. Workloads · 18Event-driven identity: Kafka principals, ACLs and replay
  20. Workloads · 19Cloud IAM and secretless deployment: roles, federation and no stored keys
  21. Workloads · 20External SaaS, webhooks and trust: calls that cross company lines
  22. Workloads · 21Private controlled environments: what private networking does and does not secure
  23. AI-native · 22Authenticating to model providers: keys, gateways and cloud IAM
  24. AI-native · 23MCP identity and authorization: discovery is not permission
  25. AI-native · 24RAG and retrieval authorization: only what this caller may read
  26. AI-native · 25Agents as principals and delegates: whose authority is this?
  27. AI-native · 26Agent-to-agent trust: identity, capabilities and forwarded authority
  28. AI-native · 27Coding agents and CI: repository scopes, OIDC and no production keys
  29. Operations · 28Auditing and observability of access: decisions you can prove later
  30. Operations · 29Threat modeling and testing: the negative tests that prove access control
  31. Operations · 30Operational lifecycles: rotation, revocation and outages
  32. Reference · 31Standards, frameworks and products: what each one is, and what it is not
  33. Reference · 32Architecture decision playbooks: choosing an auth strategy
  34. ReferenceGlossary
  35. AboutAbout this site and its sources
Authorization · 10

The enforcement architecture: PEP, PDP, PIP and PAP

Who asks, who decides, who supplies facts, who writes the rules. Gateway checks versus service checks, central administration with local enforcement, caching and invalidation, fail-safe defaults, and how a gateway-only check lets one broker read another's quote.

You will name
The four roles of an access decision, PEP, PDP, PIP and PAP, on real components of the insurance example.
You will place
Each check where it can see what it decides on: the gateway on the token, the service on the record.
You will design
Decision caching, invalidation and outage behaviour that fail closed instead of quietly allowing.

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.

VocabularyWho decidesWho enforcesWho supplies factsWho manages policyScope
XACML 3.0 (standard)PDPPEPPIP (through a context handler)PAP (authors policy)any application request
NIST SP 800-207 (guideline)PE, inside the PDPPEPdata sources (identity, threat feeds, logs)PA (opens and closes sessions at run time)enterprise access to resources
AuthZEN 1.0 (standard)PDP, serves the APIPEP, calls the APInot specifiednot specifiedthe request and response between PEP and PDP
This example (code)pdp.decidequote service, assessment service, tool server, cockpit BFFdirectory, record store, identity provider sessionreviewed versions authz-2026.11.1, authz-2026.10.3every 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 quote Q-5531; the insurer works it as submission SUB-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.

  1. API gateway
    1. token, route, scope: The bearer token, its signature, issuer, audience, expiry and scope, and the route that was called.
    2. bad token: 401 missing scope: 403: Refuses forged, expired or misdirected tokens and requests without the coarse scope, early and cheaply.
    3. 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).
  2. Quote service
    1. subject + the record: The subject built from validated claims and the directory, and the record with its tenant, unit and assignment.
    2. PDP on the record: Asks the policy decision point about this action on this record and obeys the answer.
    3. paths that skip the service: An export job or a direct database reader that never calls the service never meets this check.
  3. Repository
    1. 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.
    2. zero rows: A forgotten service check still returns nothing for another tenant's record.
    3. 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.

PresetOwn quote Q-5531Other tenant's Q-6620What it shows
default200 (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.
bola200 (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.

  1. Ask and obey
    1. cockpit backend: Holds POST /submissions/SUB-1004/decision, builds the question, obeys the answer, writes the audit record.
  2. Decide
    1. pdp.decide: Pure code: subject, action, resource, context and a policy version in; allow or deny, status, rule, reason and obligations out.
  3. Supply facts
    1. directory: Workflow data that changes during the day, read at decision time instead of trusted from a token claim.
    2. record store: Attributes of the resource itself, loaded by the service.
    3. sign-in session: How and when the person last authenticated, from the identity provider's assertion held by the cockpit backend.
  4. Write the rules
    1. 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.

SubjectRequestauthz-2026.11.1authz-2026.10.3Reason (current)
assigned underwriter u-uw-w1, cockpit, step-up nowdecision.record SUB-1004allow 200 (R-AZ-09)allow 200assigned underwriter decides through the cockpit after step-up
peer underwriter u-uw-w2, cockpit, step-up nowdecision.record SUB-1004deny 403 (R-AZ-09)allow 200 (drift)underwriter is not assigned to SUB-1004
u-uw-w1, basic login 600 s agodecision.record SUB-1004deny 401 (R-AZ-09)deny 401step-up required: strong authentication within 300 s
u-uw-e1 (commercial-east), step-updecision.record SUB-1004deny 404 (R-AZ-09)deny 404record belongs to another business unit: not found (existence not revealed)
underwriting agent with a misgranted cockpit clientdecision.record SUB-1004deny 403 (R-AZ-09)deny 403an 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.

ShapeDecision latencyPolicy freshnessOutage blast radiusTypical trigger to adopt
Library in the servicelowest (in-process)as fresh as the last releasenone addedone or two services, one team
Local decision service (sidecar)low (localhost)as fresh as the last bundle pullone hostmany services, one policy team, rules change weekly
Central decision servicea network callfreshestevery service that calls itfacts 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 choiceWhat can go staleSafe when
Key on subject, action, resource onlyrole, assignment, record attributes, policy versionnever for writes
Add policy version to the keyfacts in the directory and the recordpolicy changes are the only change you expect
Add a version (or change counter) per fact sourcenothing, if every source bumps its versionthe PIPs can publish change events
Short TTL on readsany answer, for up to the TTLreads of low-sensitivity data
No cache for a protected writenothingdecision.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.

  1. Underwriter u-uw-w1 to Cockpit backend (PEP): record decision. The person acts through the cockpit.
  2. Cockpit backend (PEP) to Policy decision point: decide decision.record. The enforcement point asks about this subject, action and record.
  3. Policy decision point to Cockpit backend (PEP): no answer. Timeout or connection refused. No decision exists.
  4. Cockpit backend (PEP) to Audit + alerts: audit + alert. The refusal is recorded and a person is told about the outage.
  5. 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#

CaseSimplest credible designGrow whenAlternatives
One service, one teamToken validation in the service; a PDP function in-process; repository predicatea second service needs the same rulesa shared library with the policy
Microservices behind a gatewayGateway: token, audience, coarse scope. Every service: object check through a local PDPrules change weekly, several teamssidecar policy engine with central bundles
Facts owned by one system (assignments, relationships)A central decision service that owns those factslatency or outage risk of the central call hurtsreplicate the facts to local PDPs, with versions
Agent tool callsThe tool server is a PEP for every call, plus the downstream servicetools shared across teamsan 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#

Monday checklist#

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.