A week after a release, an auditor reads the quote service's log and finds a line that looks harmless: at 09:00 the principal svc-cockpit-bff read quote Q-5531. The underwriter cockpit's backend is a trusted internal client, so nobody worries. Then someone notices that the cockpit backend does not read quotes. It submits decisions. Its own logs show no such call.
The team pulls the request. It came from a script on the internal network, with no token and no client certificate. It carried one header, x-app-id: svc-cockpit-bff. The quote service read the header, treated the caller as the cockpit, skipped its policy check and returned the row. The log line was accurate about what the service believed. It was wrong about who called.
This is this site's own case UW-A04. No cryptography failed and no password leaked. The service confused a claim with a proof, and the audit trail then recorded the claim as a fact. Every word on this page exists to keep those two apart.
A claim is cheap; a proof is checked by someone#
Start with the plainest version. A visitor walks up to an office door and says "I work here". That sentence is a claim. The guard asks for a badge, looks at the photo and the hologram, and lets the visitor in. The badge check is a proof, checked by a named person. Whether the visitor may then open the server room is a third question, which the badge alone does not settle.
The analogy stops being useful quickly, because software has no guard at the door. It has a signed token, a database row with an id, and several programs between them, each of which sees a different part of the request. So the rest of this page uses those objects.
Identification is the claim: a caller says who it claims to be. The broker types the username u-broker-n1. A service sends client_id=svc-portal-bff. The script in UW-A04 sends x-app-id: svc-cockpit-bff. All three are identification, and none costs anything to make.
Authentication is checking proof that the claim is true, to some level of confidence. The identity provider checks the broker's password and passkey. A service checks a client certificate in a TLS handshake. The quote service checks the signature on a token. The result is a verified identity, plus a statement about how sure we are.
Plain English. Identification is "I am the cockpit". Authentication is "prove it, and I will check". Everything after that, including whether the cockpit may read this quote, is a separate decision.
Before AI. Java web developers met this in the servlet era. A reverse proxy authenticated the user and set a header such as X-Remote-User; the application read it with no further check. Anyone who could reach the application port directly could type the header. The fix then is the fix now: the application accepts identity only from a credential it can verify, or from a channel it has authenticated, and never from a header a caller controls.
The smallest primitive: a verified subject#
The quote service never makes a decision from the raw request. It first turns what it verified into a subject: the principal as the policy sees it. In the example, services.py subject_from_claims does this after the token passed every check. The snippet demonstrates which facts come from the validated token and which come from the directory. A successful run proves only that the service built the subject from verified data; it decides nothing.
The example uses demo tokens signed with HMAC from the Python standard library and keys that say they are not secrets. They are teaching tokens: use a maintained library and a real identity provider in production.
import json
import demo_keys
import services
import tokens
from clock import START_EPOCH_S as NOW
tok = tokens.issue_for("u-broker-n1", aud=tokens.API_AUD, now=NOW)
v = tokens.verify(tok, keyset=demo_keys.keyset(), expected_issuer=tokens.ISSUER,
expected_audience=tokens.API_AUD, now=NOW)
subject = services.subject_from_claims(v["claims"], now=NOW)
keep = ["authenticated", "principal_id", "principal_type", "roles", "tenant", "scopes", "client_id", "acr"]
print(json.dumps({k: subject[k] for k in keep}, indent=2))
Run in a scratch copy of examples/uw-auth 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):
{
"authenticated": true,
"principal_id": "u-broker-n1",
"principal_type": "person",
"roles": [
"broker"
],
"tenant": "brk-north",
"scopes": [
"quotes.read",
"quotes.submit"
],
"client_id": "svc-portal-bff",
"acr": "urn:insurer.example:acr:password"
}
Notice three things. The subject names one principal, u-broker-n1, a person. It records the client that carried the request, svc-portal-bff, which is a different principal. And it records how she authenticated, acr (the authentication context class, here this example's value for a password login). None of these came from a request parameter. The tenant and roles came from the directory, keyed by the verified sub.
The subject and the token's sub claim are usually the same principal, but not always. When the underwriting agent acts for the underwriter, the token's sub is the person and its act claim names the agent. subject_from_claims then makes the agent the principal and keeps the person as "on behalf of":
token sub: u-uw-w1 | act: {'sub': 'wl-underwriting-agent'} | scope: uw.read uw.recommend
principal the policy sees: wl-underwriting-agent agent
on behalf of: u-uw-w1 | task submission: SUB-1004
That output comes from agent.py delegated_token and the same function. A delegated token never looks like the person; the policy always knows an agent is acting. Agents owns delegation; here it shows that "who is the subject" is a decision the receiving service makes, not a field it copies.
The fourteen words, on one request#
The broker reads her quote Q-5531. The broker sees a quote id; the insurer works the same record as submission SUB-1004, one to one, and every decision is made on the record both ids point to. Here is every word this site uses, attached to the object that carries it in that one request, and to the component that produces it.
| Word | Plain meaning | The object in this request | Produced or checked by |
|---|---|---|---|
| principal | who the request is made by or for | the person u-broker-n1; also the client svc-portal-bff | the directory lists them |
| identity | the set of attributes that makes one principal unique in this system | u-broker-n1, tenant brk-north, role broker | the identity provider and the directory |
| identification | the claim of an identity | the username typed at sign-in | the broker |
| credential | what a principal holds to prove itself | her password and passkey; later, the access token | the broker holds them; the token is issued |
| authenticator | the thing that demonstrates control of a factor | the passkey on her laptop | the identity provider verifies it |
| authentication | checking the proof | sign-in at https://idp.insurer.example; signature check at the gateway | identity provider, gateway |
| assurance | how confident that check is | acr password versus phishing-resistant | identity provider records it |
| session | server-side memory of an authenticated person | the portal BFF's session for her browser | portal BFF |
| subject | the principal as the policy sees it | the dict printed above | quote service (subject_from_claims) |
| authorization | deciding whether this subject may do this action to this resource now | quote.read on the record behind Q-5531 | policy decision point |
| policy | the rules that map those facts to a decision | authz-2026.11.1, rule R-AZ-03 | owned by the platform team, run by the policy decision point |
| decision | the answer with its reason | allow, 200, R-AZ-03, "broker of tenant brk-north on its own quote" | pdp.decide |
| enforcement point | the code in the path that asks and obeys | the quote service's read handler | svc-quote |
| audit record | the durable, secret-free account of what happened | one record with principal, action, resource, rule, policy version | the quote service writes it |
The table also contains the last word, trust boundary: a line in the system where data or a request passes from a part you do not control, or have not verified, into a part that will act on it. In this request there are four: the browser to the portal BFF, the BFF to the API gateway, the gateway to the quote service, and the quote service to the database. Each one is a place where a claim must be turned into a proof again, or carried over a channel already proven.
The fourteen words fall into three groups, in the order a request meets them: prove who, decide what, make it stick.
Diagram: Fourteen words, three jobs · prove who, decide what, make it stick
Read left to right. The first lane turns the broker's claim into a verified identity: she identifies herself, an authenticator proves control of a factor, the identity provider authenticates her with some assurance, and the portal backend keeps a session. The second lane decides: the quote service builds a subject from verified facts only, and the policy returns a decision for one action on one record. The third lane makes it stick: the enforcement point obeys the decision and writes an audit record without secrets. Trust boundaries sit between the boxes wherever a request changes hands.
- Prove who
- identification: The caller says who it claims to be. Free to make, so worth nothing alone.
- credential + authenticator: A credential is what the principal holds; an authenticator demonstrates control of a factor.
- authentication + assurance: The identity provider checks the proof and records how strong it was (acr) and when (auth_time).
- session at the portal BFF: The portal backend remembers that she signed in and keeps her tokens on the server.
- Decide what
- subject: The principal as the policy sees it, built from a validated token plus the directory; never from request fields.
- policy: The rules that map subject, action, resource and context to a decision.
- decision: Allow or deny with a status, the deciding rule, a reason and the policy version.
- Make it stick
- enforcement point: The code in the request path that asks for the decision and applies it, on every path to the data.
- audit record: Who acted, for whom, on which record, under which rule and policy version, and the outcome. Never the token.
The arrows matter more than the boxes. Nothing in the second lane may use a fact the first lane did not verify, and nothing in the third lane may act without an answer from the second.
A few pairs in the table are confused so often that they need a sentence each.
Credential, token, session. The password is the broker's original credential. The access token is a separate string the identity provider issued after checking it; stealing the token does not reveal the password, and resetting the password does not by itself stop a token already issued. The session is the BFF's server-side memory that she signed in; the token sits inside that session on the server. Sessions and Tokens own those mechanics.
Authenticator and assurance. The passkey is the authenticator. Guideline (NIST SP 800-63-4, read 2026-11-18): an authenticator is "a means of demonstrating the control or possession of one or more factors in an authentication protocol", and the authentication assurance level (AAL) describes "the robustness of the authentication process itself". Assurance is a property of one authentication event, so it ages: in the example a strong login counts as recent for 300 seconds, after which recording a decision needs a fresh one. Authenticators owns the levels.
Identity and real-world identity. u-broker-n1 is unique inside this system. Guideline (NIST SP 800-63-4): "A digital identity is always unique in the context of an online service." Whether it is linked to a specific real person is a separate process, identity proofing, which People explains.
Common confusion. "Principal" and "user" are not the same word. The portal BFF, the quote service, a nightly job and the underwriting agent are principals too, with their own credentials. A rule that says "the user" hides which of them is acting, and that is where confused deputies begin.
Who verifies what at each hop#
Now put the words on the path. The broker's browser talks only to the portal BFF. The BFF holds her session and attaches her access token to an API call. The API gateway checks the token. The quote service asks the policy decision point about the record. The repository reads the row.
Diagram: Who verifies what at each hop · and what each hop cannot know
Rows are the four hops of the broker's request to read a quote; columns are what each hop sees, what it can verify, and what it cannot know. Read down the middle column: the portal backend checks the session, the gateway checks the token, the quote service asks the policy decision point about the record, the repository adds the tenant predicate. Read down the right column: every hop has a blind spot that the next hop covers. The forged header case UW-A04 skips the gateway and lands on a service that checked nothing.
- Portal BFF
- session cookie: The browser sends only a session cookie; the access token stays in the BFF's server-side session.
- the session is live: The session exists, has not timed out, and belongs to this browser.
- whether the API will allow it: The BFF can hide buttons, but the decision about the record belongs to the service that owns it.
- API gateway
- access token: A token issued by the identity provider for the quote API's audience.
- signature, audience, expiry, route scope: The token is genuine, meant for this API, current, and its scope allows the route.
- the quote's tenant: The gateway cannot tell Q-5531 from Q-6620; both pass. Callers inside the network never reach it.
- Quote service
- validated claims + the record: The service builds the subject from validated claims and the directory, and loads the record's attributes.
- asks the PDP: The policy decision point answers for this subject, this action, this record.
- a header's truth: A header such as x-app-id is a claim. If the service trusts it, nobody decides.
- Database
- service account of svc-quote: The database authenticates the service, not the person.
- tenant predicate: The repository always adds the tenant from the verified context, so a missing upstream check still returns no foreign row.
- which person asked: The database sees one service account for every broker; per-person facts must come from the service.
Read the diagram one row at a time. Each hop can check only what it can see. The gateway sees a valid token for the right audience with the scope quotes.read; it never sees the quote's tenant, so it cannot answer "may she read this quote?". The quote service sees the record and can. The repository adds the tenant predicate taken from the verified subject, so even a missing check upstream cannot return another tenant's row.
services.py request_path simulates the four hops and records, per hop, the credential presented, the subject, the decision and who decided. The snippet demonstrates where each decision happens for her own quote and for the other tenant's quote, and what changes when a service trusts a header. It does not demonstrate network behaviour; the hops are in-process stand-ins.
import services
from clock import START_EPOCH_S as NOW
for scenario, toggles in [("own", {}), ("other", {}), ("own", {"forged_app_id": True, "trust_header": True})]:
r = services.request_path(scenario, toggles, now=NOW)
print("scenario", scenario, "toggles", sorted(k for k, on in toggles.items() if on) or "none",
"->", r["outcome"])
for h in r["hops"]:
print(f" {h['hop']:<11} {h['component']:<24} decided_by={h['decided_by']:<20} {h['decision']}")
print(" lesson:", r["lesson"])
scenario own toggles none -> {'status': 200, 'data_returned': True, 'leaked': False}
1 caller broker via portal BFF decided_by=nobody sends
2 gateway svc-api-gateway decided_by=svc-api-gateway pass
3 service svc-quote decided_by=pdp R-AZ-03 allow
4 database quotes table decided_by=repository predicate rows: 1
lesson: Every sensitive hop decided on the record: the gateway on the token, the service on the quote, the repository on the tenant.
scenario other toggles none -> {'status': 404, 'data_returned': False, 'leaked': False}
1 caller broker via portal BFF decided_by=nobody sends
2 gateway svc-api-gateway decided_by=svc-api-gateway pass
3 service svc-quote decided_by=pdp R-AZ-03 deny 404
4 database quotes table decided_by=nobody not reached
lesson: A valid token is not a permission: the service asked the PDP about this quote and answered 404, without revealing it exists.
scenario own toggles ['forged_app_id', 'trust_header'] -> {'status': 200, 'data_returned': True, 'leaked': True}
1 caller unauthenticated script decided_by=nobody sends
2 gateway svc-api-gateway decided_by=nobody bypassed
3 service svc-quote decided_by=nobody trusted the header
4 database quotes table decided_by=nobody rows: 1
lesson: A plain x-app-id header is metadata, not proof: the service that trusted it returned the quote to an unauthenticated script.
Compare the decided_by column of the first two runs with the third. In the first two, three different components made a decision, each about the part of the request it could see. In the third, the word "nobody" fills every row. The status is the same 200 as in the first run, which is why the incident in the opening went unnoticed for a week: a successful response does not tell you whether anyone decided.
The four-hop lab: forge the header#
The lab replays the same request. Start with the forged preset, which reproduces UW-A04; then switch the toggle "the quote service requires the mTLS peer identity" and watch the same header get refused. The plain table holds the same recorded results for a reader without JavaScript.
| 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. |
| forged | 200, returned to an unauthenticated script (nobody decided) | 200, leaked (nobody decided) | A plain x-app-id header is metadata, not proof: the service that trusted it returned the quote. |
| forged_mtls | 401 (svc-quote) | 401 (svc-quote) | Requiring the mTLS peer identity refuses the forged header: identity comes from a verified credential. |
The default preset is the healthy baseline; open it to compare hop by hop.
What goes wrong: a claim crosses a boundary unverified#
UW-A04 has a precise shape. The script was on the inside of the network, so it never passed the API gateway, the one component that checked tokens. It reached the quote service directly. The quote service had a shortcut for internal callers: if x-app-id names a known service, skip the policy decision point. The header crossed the trust boundary between "anything on the network" and "the quote service" as a claim, and the service promoted it to an identity.
Three things followed, each from the one before. Because the service believed it was the cockpit, it skipped the record check. Because it skipped the check, it returned a row nobody had authorized. Because it believed the claim, the audit record named svc-cockpit-bff as the principal, which sent the investigation to the wrong team. A false identity does more damage in the log than in the response, because the log is what people trust later.
The forged_mtls row shows the correction. The quote service accepts a service identity only from a verified client certificate (a SPIFFE id in this example, from mutual TLS). The script has no certificate, so the service answers 401 and writes a record that says "caller unknown". Workload identity owns that mechanism; the rule it rests on is this page's: a header is metadata, a credential is proof.
Production pitfall. "Internal callers are trusted" usually means "anything that can reach this port is trusted". Guideline (NIST SP 800-207, read 2026-11-18): an enterprise "should not rely on implied trustworthiness", and an implicit trust zone "must be as small as possible". Count the hosts that can reach your service. That number is the size of your trust zone.
Where to establish identity: the simplest credible design#
Every system needs an answer to one question per hop: at this boundary, what turns the caller's claim into a verified identity? There are a handful of credible answers, and the right one depends on the hop.
| At this boundary | Simplest credible proof | Grows into, when |
|---|---|---|
| person to the application | a managed identity provider and a server-side session at a BFF | federation with customer identity providers; step-up for sensitive actions |
| application to an API, for a person | an access token for that API's audience, validated by the API | token exchange when one service must call the next for the person |
| service to service, no person | the receiving service authenticates the caller's workload identity (mTLS or a signed workload token) | many teams and clusters: a workload identity system such as SPIFFE |
| service to its own database | a database role for the service, plus the tenant predicate from the verified subject | row-level security as a last line of defence |
| scheduled job, no person | the job's own workload identity, nothing else | never invent a person for a job |
This site's recommendation: verify at the service that owns the data, even when a gateway already checked. The gateway's check is cheap and stops most garbage early, but it cannot see the record, and it can be bypassed by anything already inside. The trigger to add more is not size but boundary count: each new path into the data (a queue consumer, an export job, an agent's tool server) is another boundary that needs its own proof.
Two things never count as proof on their own. A network location, because every attacker who gets one foothold inherits it. And a request field the caller controls, whether it is a header, a query parameter or a body field such as "tenant": "brk-north". Those can carry hints; the subject is built from what was verified.
What this is not. This page does not explain how tokens are validated, how sessions are kept, or how certificates work. It names the pieces and says who checks them. The mechanics are on Tokens, Sessions, TLS and PKI and Workload identity; the policy side starts on Authorization.
How the standards name the same pieces#
The vocabulary is not this site's invention, and different standards draw the lines slightly differently. Knowing which document uses which word avoids arguments that are only about words.
Guideline (NIST SP 800-63-4, read 2026-11-18): the digital identity guidelines (final, July 2025) separate three assurance questions: identity proofing (IAL, how sure we are the account belongs to a real person), authentication (AAL, "the robustness of the authentication process itself") and federation (FAL, how an identity provider's assertion reaches a relying party). An assertion is "a verifiable statement about the subscriber account to the RP" (relying party). In this site's words, the ID token the portal BFF receives is an assertion, and the BFF is the relying party.
Guideline (NIST SP 800-207, read 2026-11-18): the zero trust architecture names a subject reaching a resource through a "policy decision point (PDP) and corresponding policy enforcement point (PEP)", and tenet 3 says access "is granted on a per-session basis" and "authentication and authorization to one resource will not automatically grant access to a different resource." That is the four-hop table in one sentence.
Standard (OpenID AuthZEN Authorization API 1.0, final, read 2026-11-18): an enforcement point asks a decision point with a request whose required members are subject, action and resource, plus optional context, and gets back a boolean decision. The same four nouns as this site.
Guideline (OWASP Microservices Security Cheat Sheet, read 2026-11-18): "A signature protects an assertion's integrity; it does not itself grant access to a requested resource." And it asks for the calling service to be authenticated separately from the propagated user context, which is the two-principal subject printed above.
Security notes#
- Build the subject only from verified sources: a validated token, a verified peer certificate, the directory keyed by a verified id. Never from a header, query parameter or body field the caller controls.
- Record both principals when there are two: the person and the client, or the person and the agent. An audit record with only one of them cannot answer "who acted for whom".
- Mark in the audit record where the identity came from (token, certificate, session). A record that says "principal: svc-cockpit-bff" without the source cannot be told apart from
UW-A04. - Treat assurance as perishable. Store
acrandauth_timewith the subject and let the policy decide whether they are recent enough for the action. - Never log credentials or tokens. The example's audit log is scanned for both by
UW-A24, which passes withleaks=[].
Monday checklist#
- List every trust boundary in one request path, including queues, batch jobs and tool servers, and write next to each one what proves the caller.
- Search the code for headers used as identity:
x-app-id,x-user,x-tenant,x-forwarded-user. For each, find the verified credential that should replace or confirm it. - Find the function that builds the subject and check that every attribute comes from a validated token or the directory.
- Check that each audit record names the principal, the client or actor, the action, the resource, the rule and the policy version, and nothing secret.
- Send one request to a service from inside the network with no credential. The answer must be 401 and an audit record that says the caller is unknown.
Exercises#
1. A team says: "Our gateway validates every token, so the services do not need to know who is calling." Which hop in the four-hop table proves them wrong, and why?
AnswerThe gateway cannot see the record
The quote service hop. The gateway sees a valid token with scope quotes.read; only the service sees that Q-6620 belongs to brk-south, so only it can decide. And a caller inside the network bypasses the gateway entirely (UW-A04).
2. The underwriting agent calls the assessment service with a delegated token whose sub is u-uw-w1. Who is the principal the policy sees, and why does it matter for the decision tool?
AnswerThe agent, acting for the person
wl-underwriting-agent, of type agent, on behalf of u-uw-w1. Because the principal is an agent, rule R-AZ-09 refuses decision.record whatever scopes it holds: the model recommends; a person decides.
3. The broker signed in with a phishing-resistant passkey ten minutes ago. Does that make her authorized to submit a quote for brk-south?
AnswerAssurance is not authority
No. High assurance says we are confident she is u-broker-n1. The policy still checks the record's tenant, and brk-south is not hers, so the decision is deny (404, existence not revealed).
Advanced perspective#
Every hop has two identities: the caller and the subjectThe connection and the request can name different principals
At the gateway, the network connection comes from the portal BFF, while the token names the broker. Both are true, and they answer different questions. The connection's identity (the immediate caller, often from mTLS) says which program is talking. The token's subject says on whose behalf. A design that verifies only the subject lets any program that steals a token use it; a design that verifies only the caller lets a trusted program act for anyone. Pattern: check both where both exist. The example records client_id in the subject and requires svc-cockpit-bff as the client for decision.record, so a valid underwriter token sent through the broker portal is refused (403, "decisions are accepted only through svc-cockpit-bff"). Sender-constrained tokens (RFC 8705, RFC 9449, on Tokens) bind the two cryptographically. When there is no person, as in a scheduled job, there is only one identity, and inventing a second one is a design smell.
Assurance decays; authority does not grow with itWhy the policy reads acr and auth_time, not just the role
Assurance describes an event: this person proved control of these factors at this time. A session carries that event forward, but the evidence gets older with every minute. NIST SP 800-63-4 sets reauthentication timeouts by level (AAL2: overall "SHOULD be no more than 24 hours", inactivity "SHOULD be no more than 1 hour"; AAL3: overall "SHALL be no more than 12 hours"), as read on 2026-11-18. Separately, an application may ask for a fresh, stronger event for one action. In the example, decision.record needs acr phishing-resistant within 300 seconds; a password login 600 seconds old gets 401 with the RFC 9470 challenge insufficient_user_authentication (UW-A12). The reverse never happens: stronger authentication never adds permissions. The policy treats assurance as one input among many, and an underwriter with a fresh passkey login is still refused a submission she is not assigned to.
What the audit record must say about identityClaimed, verified, and how
The opening incident was expensive because the log stated a claim as a fact. A durable audit record about an access decision should carry: the verified principal id and type; the actor when one principal acts for another; the client; how the identity was established (session, access token with its jti, certificate with its SPIFFE id); the action and the resource id; the decision, the rule and the authorization policy version; and correlation ids. When identity could not be established, the record says "unknown" and keeps any claimed value in a separate, clearly named field, so a reviewer can see that a script claimed to be the cockpit. It never stores the token or any secret: store the jti or a key id, which identify the credential without being usable. Audit owns the record format and its integrity.
In one breath#
A request carries claims, and a claim becomes an identity only when some named component checks a proof. The receiving service builds a subject from what was verified, asks a policy for a decision about one action on one record, enforces it, and records it without secrets. Each hop can check only what it can see, so the gateway checks the token and the service that owns the record decides on the record. A header, a network location or a strong login answers none of the later questions.
The broker in this example already has an account and a password, and this page took both for granted. Before a token or a session can stand for her, someone created that account, decided how sure to be that she is who she says, stored her password safely and planned how she gets back in when she forgets it. People and identity proofing starts there.