Submission SUB-1004 is assigned to the underwriter u-uw-w1. The roof on it is a problem: the application says 9 years, the roof data provider says 22. One morning a second underwriter in the same unit, u-uw-w2, opens the cockpit, completes a fresh passkey login, and records a decision on SUB-1004. The cockpit accepts it.
In the review afterwards, every check looked right. u-uw-w2 is a person with the role underwriter. The token carries the scope uw.decide. The submission belongs to the unit commercial-west, and so does u-uw-w2. The request came through the cockpit backend, after strong authentication. Each sentence is true. The rule still failed, because the business does not say "any underwriter of the unit decides". It says "the underwriter assigned to this submission decides". The deployed authorization policy, version authz-2026.10.3, did not ask that question.
This is this site's own case UW-A09. It is not a login problem and not a token problem. It is the problem this page is about: deciding whether this principal may do this action, to this record, in this situation, and making sure the rule asks every question the business asks.
Four inputs, one answer#
Authorization is a function. Its inputs are four facts about one request, and its output is a decision.
The subject is who is asking, as verified: u-uw-w2, a person, role underwriter, unit commercial-west, entitlement uw.decide, assigned to SUB-1007. The action is the business operation: decision.record, not "POST to an endpoint". The resource is the specific record: SUB-1004, with its own attributes (unit commercial-west, assigned underwriter u-uw-w1, risk tier standard). The context is everything else that matters now: the time, how strongly and how recently the subject authenticated, which client carried the request.
subject × action × resource × context → allow or deny, with a reason.
Written that way, the gap in UW-A09 is visible at once. The old policy read the subject's role and unit and the resource's unit. It never compared the subject's assignments with the resource's id. The fix is one more comparison between two inputs that were already there.
Plain English. Authentication found out who is asking. Authorization asks: may this person do this thing to this record, right now? The answer comes from rules, and the rules can only check what they are written to check.
Before AI. In Spring Security,@PreAuthorize("hasRole('UNDERWRITER')")on a controller method answers a question about the subject only.@PreAuthorize("@authz.canDecide(authentication, #submissionId)")passes the record id into a bean that can load the record and compare. The first is a role check; the second is authorization. The same split existed with servlet filters, LDAP groups and stored procedures long before agents.
The smallest primitive: the decision function#
In the example, one pure function makes every decision: pdp.decide in examples/uw-auth/pdp.py, the policy decision point (PDP: the code that evaluates policy and returns allow or deny with a reason). Here is its branch for decision.record, verbatim. It shows the order of questions the business asks, and the status each failure returns. It is teaching code: a production system would use the same structure in a maintained framework or policy engine.
# verbatim excerpt from examples/uw-auth/pdp.py, decide(), the decision.record branch
if action == "decision.record":
if ptype != "person":
return _d(False, 403, "R-AZ-09", "an agent or service principal never records an underwriting decision", v)
if "underwriter" not in roles:
return _d(False, 403, "R-AZ-09", "role underwriter required", v)
if "uw.decide" not in (subject.get("entitlements") or []):
return _d(False, 403, "R-AZ-09", "entitlement uw.decide required", v)
if res.get("business_unit") != unit:
return _d(False, 404, "R-AZ-09", "record belongs to another business unit: not found (existence not revealed)", v)
if POLICIES[v]["assignment_check"] and sub_id not in (subject.get("assignments") or []):
return _d(False, 403, "R-AZ-09", "underwriter is not assigned to " + str(sub_id), v)
if res.get("risk_tier") == "high" and HIGH_RISK_ENTITLEMENT not in (subject.get("entitlements") or []):
return _d(False, 403, "R-AZ-09", "risk tier high needs the entitlement " + HIGH_RISK_ENTITLEMENT, v)
if subject.get("client_id") != DECISION_CLIENT:
return _d(False, 403, "R-AZ-09", "decisions are accepted only through " + DECISION_CLIENT, v)
at = subject.get("auth_time")
recent = isinstance(at, int) and now - at <= STEP_UP_MAX_AGE_S
if subject.get("acr") != ACR_STRONG or not recent:
return _d(False, 401, "R-AZ-09", "step-up required: strong authentication within " + str(STEP_UP_MAX_AGE_S) + " s", ...)
return _d(True, 200, "R-AZ-09", who + " decides through the cockpit after step-up", ...)
(The two ... stand for the obligations argument, shortened here; the file has them in full.)
This branch is the whole page in miniature. Every path but the last returns deny. Each refusal names its rule and reason. The statuses differ on purpose. And the questions mix kinds: principal type, role, entitlement, attribute, relationship, client and authentication strength.
Before the branch runs, decide has already asked three general questions in order: is the policy version known, is the subject authenticated (else 401, rule R-AZ-01), and does the token's scope name this action family (else 403, rule R-AZ-02). Then, for any action on a record, does the record exist.
Diagram: One decision, questions in order · general checks first, then the business rule on the record
Read left to right. The four inputs enter the policy decision point. The general lane refuses anything unknown, anything unauthenticated, any token whose scope does not name the action family, and any record that does not exist. The business lane for decision.record asks, in order: is the subject a person, an underwriter with the entitlement uw.decide, in the record's unit, assigned to it, entitled for its risk tier, using the cockpit client, after a fresh strong login. Every exit but the last is a deny with its own status and reason. The output lane is what the enforcement point receives.
- Four inputs
- subject × action × resource × context: Who (verified), which business operation, which record (attributes loaded from it), and the situation (time, acr, auth_time, client).
- General checks
- known version, known action: An unknown policy version, action or principal type is refused: no rule allows it.
- authenticated?: No valid authentication: the caller is unknown, so nothing else can be decided.
- scope names the action family: The token's coarse scope must admit this kind of action. A scope never says which record.
- record exists: Actions on records need the record; a missing one is not found.
- Business rule R-AZ-09
- person, role, entitlement: Only a person with role underwriter and entitlement uw.decide; never an agent or service.
- same unit: Another unit's record is refused without revealing that it exists.
- assigned to this submission: The relationship the business rule names. authz-2026.10.3 skipped it.
- risk tier, client, fresh strong login: High risk needs uw.decide.high; only svc-cockpit-bff may submit; acr phishing-resistant within 300 s, else a 401 challenge.
- Decision
- allow · status · rule reason · version: What the enforcement point receives and must obey, including duties such as writing the audit record.
The example, decided#
The snippet below runs the function for this site's own cases UW-A01 (the broker reads her own quote), UW-A02 (the broker of the other tenant, with a valid token, asks for the same record by both its ids) and UW-A09, then for a dozen single requests. It demonstrates which rule and status each request gets. It does not prove the policy is complete; only the tests and a review against the business rules do that.
import pdp
import scenarios
from clock import START_EPOCH_S as NOW
from directory import ACR_STRONG, resource_for, subject_for
print("UW-A01", scenarios.a01())
print("UW-A02", scenarios.a02())
print("UW-A09", scenarios.a09())
def show(label, subject, action, resource, version=pdp.CURRENT_POLICY):
d = pdp.decide(subject, action, resource, {"now": NOW}, version)
verdict = "allow" if d["allow"] else "deny"
print(f"{label:<44} {verdict:<5} {d['status']} {d['rule']:<8} {d['reason']}")
broker = subject_for("u-broker-n1", now=NOW)
show("no authenticated subject", None, "quote.read", resource_for("Q-5531"))
show("broker, action nobody named (quote.delete)", broker, "quote.delete", resource_for("Q-5531"))
show("broker, submission.read (scope lacks uw.read)", broker, "submission.read", resource_for("SUB-1004", "submission"))
show("broker, quote.read Q-6620", broker, "quote.read", resource_for("Q-6620"))
show("broker, quote.read Q-9999 (no such record)", broker, "quote.read", resource_for("Q-9999"))
w1 = subject_for("u-uw-w1", now=NOW, acr=ACR_STRONG, auth_time=NOW, client_id="svc-cockpit-bff")
show("u-uw-w1 decision.record SUB-1004", w1, "decision.record", resource_for("SUB-1004", "submission"))
w1_portal = subject_for("u-uw-w1", now=NOW, acr=ACR_STRONG, auth_time=NOW, client_id="svc-portal-bff")
show("u-uw-w1 via the broker portal client", w1_portal, "decision.record", resource_for("SUB-1004", "submission"))
w1_weak = subject_for("u-uw-w1", now=NOW, client_id="svc-cockpit-bff")
show("u-uw-w1, password login 600 s ago", w1_weak, "decision.record", resource_for("SUB-1004", "submission"))
w2 = subject_for("u-uw-w2", now=NOW, acr=ACR_STRONG, auth_time=NOW, client_id="svc-cockpit-bff")
show("u-uw-w2 (peer) authz-2026.11.1", w2, "decision.record", resource_for("SUB-1004", "submission"))
show("u-uw-w2 (peer) authz-2026.10.3", w2, "decision.record", resource_for("SUB-1004", "submission"), pdp.PREVIOUS_POLICY)
show("u-uw-w1, unknown policy version", w1, "decision.record", resource_for("SUB-1004", "submission"), "authz-2099.1")
Run in a scratch copy of the example on 2026-11-18 (the example's agent is a scripted stand-in, so results here show how the access controls work, not how good any model is):
UW-A01 {'status': 200, 'rule': 'R-AZ-03', 'quote_id': 'Q-5531', 'tenant': 'brk-north'}
UW-A02 {'token_valid': True, 'status': 404, 'rule': 'R-AZ-03', 'body': None, 'status_by_submission_id': 404}
UW-A09 {'current': {'allow': False, 'status': 403, 'reason': 'underwriter is not assigned to SUB-1004'}, 'previous': {'allow': True, 'status': 200, 'policy_version': 'authz-2026.10.3'}}
no authenticated subject deny 401 R-AZ-01 no valid authentication: the caller is unknown
broker, action nobody named (quote.delete) deny 403 R-AZ-00 no rule allows action quote.delete: deny by default
broker, submission.read (scope lacks uw.read) deny 403 R-AZ-02 token scope lacks uw.read (insufficient_scope)
broker, quote.read Q-6620 deny 404 R-AZ-03 record belongs to another tenant: not found (existence not revealed)
broker, quote.read Q-9999 (no such record) deny 404 R-AZ-00 no such record
u-uw-w1 decision.record SUB-1004 allow 200 R-AZ-09 assigned underwriter decides through the cockpit after step-up
u-uw-w1 via the broker portal client deny 403 R-AZ-09 decisions are accepted only through svc-cockpit-bff
u-uw-w1, password login 600 s ago deny 401 R-AZ-09 step-up required: strong authentication within 300 s
u-uw-w2 (peer) authz-2026.11.1 deny 403 R-AZ-09 underwriter is not assigned to SUB-1004
u-uw-w2 (peer) authz-2026.10.3 allow 200 R-AZ-09 underwriter of the unit (this policy version does not check assignment) decides through the cockpit after step-up
u-uw-w1, unknown policy version deny 403 R-AZ-00 unknown authorization policy version authz-2099.1: deny by default
UW-A02 deserves a second look. The broker of brk-south asked for Q-5531 and for SUB-1004. Both ids point to the same record (the broker sees a quote id, the insurer works the submission id, one to one), and both requests got 404. Authorization is decided on the record, never on which id the caller happened to send. A system that checks the quote id path and forgets the submission id path has two doors to one room and a lock on one of them.
Deny by default: the answer to the question nobody asked#
Look at the second, fifth and last rows. Nobody wrote a rule for quote.delete, for a record that does not exist, or for a policy version called authz-2099.1. The function did not crash and did not allow. It answered deny, with rule R-AZ-00.
Deny by default means that access is refused unless a rule explicitly allows it. The opposite design, allow unless a rule forbids, fails in exactly the cases nobody imagined: a new action added to the API, a new kind of principal, a misspelled version string. Those are the cases most likely to be wrong.
Guideline (OWASP Authorization Cheat Sheet, read 2026-11-18): "Deny by Default" is one of its headings, and the API Security Top 10 entry on broken function level authorization says enforcement should "deny all access by default, requiring explicit grants to specific roles". The principle is older than the web. Guideline (Basic Principles of Information Protection, read 2026-11-18 on web.mit.edu): "Fail-safe defaults: Base access decisions on permission rather than exclusion."
Policy engines build the same default in. Product (Cedar, as documented on 2026-11-18): "no request is authorized (decision Allow) unless there is a specific permit policy that grants it". Product (PostgreSQL 18, as documented on 2026-11-18): with row-level security enabled, "If no policy exists for the table, a default-deny policy is used".
Deny by default has an operational twin: when the decision cannot be made, refuse. In the example, if the policy decision point is unreachable, the enforcement point answers 503 for writes and never allows (UW-A23). Enforcement owns that fail-closed design.
Complete mediation: every request, every path#
A rule that is right but not asked is worth nothing. Complete mediation means every access to every protected resource goes through the decision, every time, on every path. Guideline (Basic Principles of Information Protection): "Every access to every object must be checked for authority." Guideline (OWASP Authorization Cheat Sheet): "Permission should be validated correctly on every request."
"Every path" is the hard half. The quote can be reached through the broker API, the underwriter cockpit, a nightly export, the search index that powers "find my quotes", and the underwriting agent's tool server. If four of them ask the policy decision point and the export job reads the table with a service account, the export job is the door that matters.
Diagram: Complete mediation · every path to the quote asks the same decision
Read left to right. Five different paths can reach the same quote record: the broker API, the underwriter cockpit, the nightly export, the search index behind 'my quotes', and the underwriting agent's tool server. Each path has its own enforcement point, and each one calls the same policy decision point with the same four inputs. The amber box is the classic gap: a batch job that reads the table with a service account and asks nobody. One unguarded path makes the other four irrelevant.
- Paths to the data
- broker API: The broker portal backend calls the quote API with the broker's access token.
- underwriter cockpit: The cockpit backend reads submissions and records decisions for a stepped-up underwriter.
- nightly export: A job that reads rows with a service account. Unless it asks the policy or runs with a narrow grant, it bypasses every rule.
- search index: A list or search returns many records; the policy must become a filter, not a check after the fact.
- agent tool server: Model-written tool calls arrive with the agent's delegated token and are decided like any request.
- Enforcement points
- ask before any data moves: Each path's code builds the subject from verified facts, names the business action, loads the record, and asks.
- One decision
- same policy, same version: Every path gets the same answer for the same inputs, and the decision records the version.
"Every time" is the other half. Caching a decision for the length of a session turns one check into a permission that outlives the facts it was based on. If the underwriter is moved to another unit at 10:00, a decision cached at 09:00 still says yes. The example re-decides per request from current directory facts; where a cache is needed for speed, it must be short and keyed on everything the decision read.
401, 403 and 404: three different things to tell a caller#
The output above uses three refusal statuses. They are not interchangeable, and choosing between them is part of the design.
Standard (RFC 9110, HTTP Semantics, read 2026-11-18): 401 means the request "lacks valid authentication credentials for the target resource". 403 means "the server understood the request but refuses to fulfill it"; if credentials were sent, the server "considers them insufficient to grant access", and the client should not repeat the request with the same credentials. And in the 403 section: an origin server that "wishes to "hide" the current existence of a forbidden target resource MAY instead respond with a status code of 404".
For bearer tokens the error codes are fixed too. Standard (RFC 6750, read 2026-11-18): invalid_token ("expired, revoked, malformed, or invalid for other reasons") goes with 401; insufficient_scope ("The request requires higher privileges than provided by the access token") goes with 403. Standard (RFC 9470, read 2026-11-18): insufficient_user_authentication with acr_values and max_age tells the client to authenticate again, more strongly or more recently, which is why the example answers a stale login with 401 and not 403.
| Situation in the example | Status | Why this status | Rule |
|---|---|---|---|
| no valid token, or a token that fails validation | 401 | we do not know who is calling | R-AZ-01 |
| underwriter decides with a password login 600 s old | 401 + step-up challenge | we know who, but the authentication is not strong or recent enough; a new login can fix it | R-AZ-09 |
| broker token used to read an internal submission | 403 insufficient_scope | the token was never meant for this kind of action | R-AZ-02 |
peer underwriter decides on SUB-1004 | 403 | caller knows the submission exists (same unit); the refusal is the honest answer | R-AZ-09 |
broker of brk-north reads Q-6620 | 404 | the quote belongs to another tenant; saying "forbidden" would confirm it exists | R-AZ-03 |
underwriter of commercial-east reads SUB-1004 | 404 | another unit's record; same reason | R-AZ-04 |
| a quote that does not exist | 404 | it does not exist | R-AZ-00 |
The rule of thumb the example follows: return 404 when the caller has no business knowing the record exists, and 403 when it legitimately can know and is still refused. The last three rows must look identical from the outside, in body, headers and as far as practical in timing, or the 404 hides nothing. Guideline (OWASP REST Security Cheat Sheet, read 2026-11-18) describes 403 as "used when the authentication succeeded but authenticated user doesn't have permission"; the choice to hide existence with 404 is the application's, as every framework demo in examples/frameworks/ shows.
Common confusion. HTTP calls 401 "Unauthorized", but it is about authentication: the caller is unknown or not proven enough. "Not allowed" is 403. The misnomer is historical, and the RFC text above is what counts.
Scopes, roles and entitlements: three answers to three questions#
UW-A09 passed a scope check, a role check and an entitlement check and still broke the rule. That is because none of the three says which record.
A scope is a coarse permission name carried in a token. quotes.read says the token may be used to read quotes in general; it never says which quote. Scopes are decided when the token is issued, so they describe what the client may attempt, not what the person may do to a given record. (OAuth and OIDC owns scopes.)
A role is a named set of permissions given to principals: underwriter, broker, auditor. It answers "what kind of principal is this?".
An entitlement is a specific grant to a principal, often for a class of resources or one resource: uw.decide (may record underwriting decisions at all), uw.decide.high (may decide high-risk submissions), or the assignment of SUB-1004 to u-uw-w1. Entitlements live in the directory or the policy data, not in the token, because they change faster than tokens expire and can be too many to carry.
| Name | Example | Carried in | Says | Never says |
|---|---|---|---|---|
| scope | quotes.read, uw.decide | the access token | this client may attempt this kind of action | which record |
| role | underwriter | directory (sometimes copied into the token) | what kind of principal this is | which unit's or which tenant's records |
| entitlement | uw.decide, uw.decide.high | directory, read by the PDP | this principal holds this specific grant | which submission, unless it names one |
| relationship | SUB-1004 assigned to u-uw-w1 | directory, read by the PDP | this principal is linked to this record | anything about other records |
The policy needs all four, plus the record's own attributes, to state the business rule. The scope check (R-AZ-02) stops a broker's token from reaching underwriting actions at all. The role and entitlement checks narrow to who may decide. The relationship check says on which record. Access control models treats roles, attributes and relationships as models in their own right.
Check the business operation, not only the endpoint#
An endpoint is a URL and a method: POST /submissions/{id}/decision. A business operation is what the request does to the business: record an underwriting decision on SUB-1004, possibly overriding the recommendation. Authorization belongs to the second.
The difference shows in three ways. First, one endpoint can carry several operations: the same decision endpoint records an approval, a decline, a referral or an override, and an organization may want only senior underwriters to override. Second, one operation can be reached through several endpoints: a decision recorded through the cockpit, through a batch import, or through an agent tool. Third, the conditions belong to the operation: the cockpit-only client and the fresh strong login in R-AZ-09 are about recording a decision, wherever the request arrives.
Guideline (OWASP API Security Top 10 2023, read 2026-11-18): API1, broken object level authorization, is the missing check on the record; API5, broken function level authorization, is a caller reaching "functionality" it should not, such as an administrative function behind a guessed URL or a changed HTTP method. A business-operation check closes both: it names the operation and evaluates it on the record.
In the example the action names are business operations (quote.read, decision.record, recommendation.record), and the route maps to the action in one place (services.py: "the route decides the action; the record decides the rest"). The tool record_underwriter_decision maps to the same action, so the underwriting agent meets R-AZ-09 too, and is refused because it is not a person. The model suggests an action; deterministic code decides whether it may run.
In a coding agent. The same split appears in a repository. A coding agent working through a repository-scoped GitHub App installation can push a branch and open a pull request; merging into the protected branch is a different business operation, which the repository's rules reserve for a person with merge rights. The endpoint (a git push) looks similar; the operation and its rule differ. Coding agents owns the details.
Policy freshness: decisions are only as current as their facts#
UW-A09 has a second lesson. The old policy authz-2026.10.3 was not malicious; it was stale. The business rule had always said "assigned", and the code had drifted from it. Two kinds of freshness matter.
The policy must be current: the deployed version must match the reviewed one, and every decision should record which version produced it (policy_version in each decision of the example). Without that field, UW-A09 is a mystery; with it, a reviewer filters decisions made under authz-2026.10.3 and finds every peer decision in minutes. Policy as code owns versions, tests and drift.
The facts must be current: roles, units, assignments and entitlements change. A token issued at 09:00 copies some of them and keeps them until it expires; a decision cache keeps them for its lifetime. This site's recommendation: keep fast-changing facts (assignments, entitlements) out of tokens and read them at decision time, keep slow ones (tenant, principal type) in claims, and give every cache a lifetime shorter than your access-removal target. Operations owns revocation and removal deadlines.
Least privilege: grant the smallest set that does the job#
Least privilege means each principal gets only the permissions its job needs, for as long as it needs them. Guideline (Basic Principles of Information Protection): "Every program and every user of the system should operate using the least set of privileges necessary to complete the job." Guideline (OWASP Authorization Cheat Sheet): "Enforce Least Privileges".
In the example, least privilege is visible in four places. Brokers hold quotes.read quotes.submit and nothing internal. The underwriting agent may hold at most uw.read uw.recommend; a token exchange asking for uw.decide is refused with invalid_scope (agent run, step 2). The auditor reads audit records and writes nothing. And the platform administrator has no standing rights at all, only just-in-time elevation (R-AZ-11; Privileged access).
Grants decay as people change jobs, so least privilege needs Governance and access reviews, not only a careful first grant.
The authorization models lab: roles alone#
The lab decides the same five requests under three models. This page embeds it on RBAC (role-based access control: the role alone decides), with the cross-tenant request selected, to show what a role check misses. Switch the model to see attributes and relationships close the holes; Access control models walks through all three.
| Principal | Action | Record | RBAC | ABAC | ReBAC | ReBAC reason |
|---|---|---|---|---|---|---|
| u-broker-n1 (broker, brk-north) | quote.read | Q-5531 | allow | allow | allow | role, attributes and relationship match |
| u-broker-n1 (broker, brk-north) | quote.read | Q-6620 (brk-south) | allow (hole) | deny | deny | tenant brk-south is not the caller's tenant brk-north |
| u-uw-w1 (assigned underwriter) | decision.record | SUB-1004 | allow | allow | allow | role, attributes and relationship match |
| u-uw-w2 (peer underwriter, same unit) | decision.record | SUB-1004 | allow (hole) | allow (hole) | deny | no assigned_to relationship between u-uw-w2 and SUB-1004 |
| u-uw-e1 (underwriter, commercial-east) | submission.read | SUB-1004 | allow (hole) | deny | deny | unit commercial-west is not the caller's unit commercial-east |
Holes against the business rule: RBAC 3 of 5, ABAC 1 of 5, ReBAC 0 of 5. The fourth row is UW-A09 again.
What goes wrong without these ideas#
Each idea on this page has a failure that looks like success. Without deny by default, a new action ships open. Without complete mediation, the export job leaks what the API protects. Without the 404 choice, the difference between 403 and 404 enumerates other tenants' quote ids. Without separating scope from entitlement, the peer underwriter decides. Without freshness, a moved underwriter keeps the old unit's records until a cache expires. And without a reason on every decision, none of this can be found afterwards: UW-A09 was caught because the decision named its rule and version.
Choosing where the decision lives#
The function is the same everywhere; where it runs changes with the system.
| Stage | Simplest credible design | Trigger to grow | Grows into |
|---|---|---|---|
| one service, a few rules | the rule in the service, in one function per operation, called before every data access | the same rule is needed in a second service or path | a shared in-process decision module (like pdp.decide) with tests |
| several services, shared rules | one policy module or library, versioned, imported by each service | teams need to change policy without redeploying services, or audit asks for decision logs | an external policy engine (OPA, Cedar, OpenFGA) called by each enforcement point |
| many relationships, fine-grained sharing | relationships in your own tables | relationships outnumber rows, change constantly, or cross services | a relationship-based engine with its own store |
This site's recommendation: start with the decision as one pure function with named rules and reasons, called by every path, and tested with negative cases. Move it out of process only when a named trigger appears. An external engine adds a network hop, a deployment pipeline and an availability dependency; it does not add correctness by itself. Policy as code compares the engines; Enforcement covers where the enforcement points sit.
What this is not. This page is about the decision. Where it is enforced (gateway versus service, caching, fail-closed) is on Enforcement. How tenants are isolated in the data is on Tenants. Whether an MCP tool call is authorized follows the same function; its identity side is on MCP, and the protocol on MCP Engineering.
In real frameworks (these ran)#
The same rule ran in real, maintained frameworks on 2026-11-18 (examples/frameworks/; commands and full output in each OUTPUT.md).
Library (Spring Security 7.1.2, run with Spring Boot 4.1.2): URL rules check the coarse scope (hasAuthority("SCOPE_quotes.read")), and method security passes the record id into a bean for the object-level decision; a handler turns a denied quote read into 404. 17 tests, 0 failures. The annotations, verbatim from UwController.java with the method bodies shortened to a comment (Java is not compiled by this site's build; it compiled and ran in the demo):
@GetMapping("/quotes/{quoteId}")
@PreAuthorize("@uwAuthz.canReadQuote(authentication, #quoteId)")
@HandleAuthorizationDenied(handlerClass = HideExistence.class)
public Map<String, Object> readQuote(@PathVariable String quoteId) { /* ... */ }
@PostMapping("/submissions/{submissionId}/decision")
@PreAuthorize("@uwAuthz.canRecordDecision(authentication, #submissionId)")
public Map<String, Object> recordDecision(@PathVariable String submissionId, @AuthenticationPrincipal Jwt jwt) { /* ... */ }
Product (Spring Security, as documented on 2026-11-18): @EnableMethodSecurity enables @PreAuthorize, and Spring Boot does not enable method-level authorization by default; AuthorizationManagers "are responsible for making final access control decisions". Two differences from pdp.py, recorded in the demo: a weak login answers 403 there (a @PreAuthorize bean returns allow or deny only; a 401 step-up challenge needs extra code), and an underwriter of another unit gets 403, not 404.
Library (FastAPI 0.165.0 with PyJWT 2.15.1): a dependency validates the token (401), checks the scope (403), and the endpoint makes the object-level decision (200, 404 tenant, 401 step-up, 403 peer and agent). 19 passed.
In both, the framework proved the token was genuine and the scope present. The rule itself, tenant, unit, assignment and authentication strength, stayed in application code. Standard (OpenID AuthZEN Authorization API 1.0, final, read 2026-11-18) standardizes the call between an enforcement point and a decision point (subject, action, resource, optional context, a boolean decision), not the rules.
Security notes#
- Decide on the record the id points to, after loading it, never on the id string or on which id form was sent.
- Take every subject attribute from verified sources; take every resource attribute from the record, not from the request body.
- Make "not found" and "hidden" responses identical in status, body and headers.
- Log every decision with rule, reason and authorization policy version, and never the token.
- Treat an error from the decision point as deny. Never catch the exception and continue.
- Remember the agent: a model may ask for any tool; the policy decides on the principal type, the task and the record.
Monday checklist#
- For one sensitive operation, write the business rule in one sentence, then check that the code compares every noun in it (who, which record, which relationship, which condition).
- List every path to the same data (API, export, search, agent tool, admin console) and check that each one calls the same decision.
- Grep for authorization that reads only the token's scope or role on endpoints that take a record id.
- Try three requests with a valid token: another tenant's record, a nonexistent id, and an action that no rule names. Expect 404, 404 and 403, all with reasons in the log.
- Check that decisions record the policy version, and that a cache, if any, lives shorter than your access-removal target.
Exercises#
1. A team adds DELETE /quotes/{id} and forgets to write a rule for quote.delete. What happens in the example's design, and in a design that allows unless a rule forbids?
AnswerDeny by default refuses it; allow by default opens it
pdp.decide returns deny, 403, R-AZ-00 "no rule allows action quote.delete: deny by default". An allow-unless-forbidden design would let every authenticated caller delete any quote until someone noticed.
2. The underwriter u-uw-e1 of commercial-east asks for SUB-1004. Should the answer be 403 or 404, and why does it matter?
Answer404: another unit's record is not hers to know about
404 (R-AZ-04). A 403 would confirm that SUB-1004 exists in another unit; repeated over many ids, that difference enumerates the other unit's submissions.
3. A reviewer proposes adding the assignment list to the underwriter's access token "so the service does not need the directory". What goes wrong?
AnswerThe assignment outlives the token's facts
Assignments change during the token's lifetime. A reassigned submission would stay decidable by the old underwriter until the token expires, and the token grows with every assignment. Keep the relationship in the directory and read it at decision time.
Advanced perspective#
The cost of 404 for forbidden recordsEnumeration safety against support and debugging
Hiding existence has real costs. A broker who mistypes a quote id and a broker who tries another tenant's id see the same answer, so support cannot tell them apart from the response; the audit record must carry the difference (rule R-AZ-03 versus R-AZ-00). Debugging gets harder for the same reason. And the hiding is only as good as its consistency: a different response time, a different error body, a Content-Length difference, a cache header present for real records, or a list endpoint that returns a count all reveal existence again. The trade-off is usually worth it for records owned by another customer (tenants) and often not worth it inside one organization, where a 403 with "ask the assigned underwriter" saves time. The example uses 404 across tenants and units and 403 within a unit, and says so in each reason. RFC 9110 makes the 404 choice optional ("MAY"); it is a design decision to write down, not a protocol requirement.
Authorizing lists, searches and countsA filter is a decision applied to many records at once
A single-record check is easy to place: load the record, decide, return. A list endpoint ("my quotes"), a search, or an export returns many records, and checking each one after fetching a page leads to short pages, leaked counts and slow queries. The common answer is to turn the policy into a query predicate (tenant = the subject's tenant) applied by the repository, as the example's QuoteRepository.find does, and to keep that predicate generated from the same rule as the single-record check so they cannot drift. Counts and facets are records too: a result count for a filter the caller may not see is a leak. Retrieval for agents has the same problem at larger scale, with an extra twist about recall; RAG owns it.
Obligations: what the enforcement point must also doA decision can carry duties, not only a yes
Every decision in the example carries obligations, a list of duties the enforcement point must perform if it acts on the decision: "write audit record" always; "filter results to business_unit commercial-west" for a precedent search; "the recommendation is advisory: a person decides" for a recommendation; "raise security alert" and "open mandatory post-use review" for break-glass. The word is borrowed from earlier policy languages; here it means only what the example does with it. The design rule is strict: an enforcement point that cannot fulfil an obligation must not act on the allow. That keeps duties like audit and filtering next to the rule that needs them, instead of scattered across handlers where one path forgets them. It also makes the decision log richer, because the log can show not only "allowed" but "allowed on condition of a filter", which is what an auditor needs to verify.
Model intent is input, never authorityWhy the agent's request goes through the same function
An agent changes who writes the request, not who decides it. The model may produce a tool call to record_underwriter_decision because a retrieved passage told it to (UW-005 shape; agent run step 6). That call is an action request like any other: the tool server maps it to decision.record, builds the subject from the agent's delegated token (principal type agent, acting for u-uw-w1, task limited to SUB-1004 and named actions), and asks the same policy. It is refused twice: first at the scope check (the agent's token never holds uw.decide), and even with a misgranted scope, by R-AZ-09, which refuses any non-person principal (UW-A10). Two lessons generalize. Put the most important rules on principal type and task, not only on scope, because scopes get misgranted. And never let the model write any input of the decision: not the tenant, not the subject, not the filter. Agents owns delegation and task tokens; Guardrails Engineering owns checks around the model itself.
In one breath#
Authorization is a function of subject, action, resource and context that returns allow or deny with a rule and a reason. It refuses what no rule allows, runs on every request and every path, and tells the caller 401, 403 or 404 on purpose. Scopes, roles and entitlements each answer a narrower question than "may this person do this to this record", so the policy combines them with the record's own attributes and relationships, at the business operation, from current facts.
The peer underwriter was stopped by a relationship, the cross-tenant broker by an attribute, and neither by a role. That pattern is the start of a choice every system makes: which model expresses which part of a rule, and why none of them is enough alone. Access control models takes RBAC, ABAC and ReBAC apart on the same five requests.