Auth engineering · identity, delegation, enforcement and audit
A valid token is not a permission.
Every request in a secure system answers two questions: who is calling, and may this caller do this to this record, now. This site starts with one broker asking to read one insurance quote and climbs, one honest step at a time, to AI agents that call models, MCP servers and retrieval while acting for people.
For backend engineers who secure APIs, architects who design identity across services, and teams who are adding agents to systems that already have users, roles and audits. One running example, fourteen labs, and code that runs without a network, an identity provider, a model or a real key.
A broker at a brokerage called brk-north signs in to an insurer's broker portal on a Tuesday morning. The portal shows her the quote she asked for last week, Q-5531. Everything works. Out of curiosity, or by a slip of the keyboard, she edits the address bar and changes the last digits to Q-6620.
Q-6620 belongs to a different brokerage, brk-south. It names a warehouse, its roof, the requested coverage and a premium indication. It is commercially sensitive, and it is none of her business.
What should happen next? Her session is valid. Her access token is signed by the insurer's identity provider, has not expired, and carries the scope quotes.read. The API gateway checks all of that and lets the request through. If the quote service behind the gateway now looks up Q-6620 by its id and returns the row, nothing in the system has malfunctioned. Every component did what it was built to do. And one customer has read another customer's quote.
This is the most common way access control fails in real systems, and it has a name on the OWASP API Security list: broken object level authorization. It is not a failure of login, of cryptography, or of the network. It is a missing question. Somebody proved who the broker was, and nobody asked whether she may read this particular quote.
This site is about asking the right question, at the right place, every time, and about what changes when the caller is not a person but a service, a scheduled job or an AI agent acting for someone.
Five questions behind every request#
Pull the broker's request apart and you find five separate questions. Systems fail when they answer one and assume the others.
1. Identification: who does the caller claim to be? The broker types a username. A service sends a client id. A claim costs nothing to make. A header such as x-app-id: svc-cockpit-bff is also only a claim: any program can type it.
2. Authentication: what proves the claim, and how sure are we? The broker's password plus a passkey, verified by the identity provider. A service's private key, proven in a TLS handshake. The result is a level of confidence, not a yes for everything. A stronger login tells you more reliably who this is. It tells you nothing about what she may do.
3. Authorization: may this caller do this action to this resource, in this context, now? May broker u-broker-n1 perform quote.read on the record Q-6620, whose tenant is brk-south, at 09:12 on a Tuesday? The answer is computed from a policy, and here it is no.
4. Enforcement: is the answer applied on every path to the data? The quote service must refuse, and so must the export job, the search index, the mobile API and the agent's tool. A decision that only one path obeys is not a control.
5. Audit: what is recorded, so a person can reconstruct it later? Who asked, for which record, under which policy version, what the answer was, and why, without writing the token or any secret into the log.
Diagram: Five questions behind one request · answering one never answers the next
Read left to right for the broker who asks for quote Q-6620. Identification is a claim. Authentication turns it into verified identity with a level of confidence. Authorization decides on this record, under a policy. Enforcement applies the answer on every path. Audit records it without secrets. The broker's request passes the first two and fails the third: a valid token is not a permission.
- 1 · Identification
- a claim: The caller says who it is. A claim costs nothing and proves nothing.
- 2 · Authentication
- verified identity: Proof is checked by the identity provider or the receiving service. The result is who, and how sure, never what.
- 3 · Authorization
- decision on the record: Policy decides whether this subject may perform this action on this resource now, and says why.
- 4 · Enforcement
- every path obeys: The code in each request path asks and obeys. A decision only one path respects is not a control.
- 5 · Audit
- a durable record: Who asked, for which record, under which policy version, the answer and the reason, so a person can reconstruct it later.
Plain English. Authentication answers "who are you, and how do we know?". Authorization answers "may you do this, to this, now?". A valid answer to the first is never an answer to the second.
Seven sentences follow from this split, and each one has a chapter behind it:
| Common belief | What is true | Chapter |
|---|---|---|
| She logged in, so she can see her data | A successful login proves identity; each request still needs a decision about the record | Authorization |
| The token is valid, so the request is allowed | A valid token proves who issued it, for whom and until when; it says nothing about quote Q-6620 | Tokens |
| It came from inside our network, so it is trusted | A network location is not an identity; zero trust starts from that sentence | Gateways and zero trust |
The request carries x-app-id, so we know the caller | A plain header is metadata anyone can type; identity needs a verified credential | Workload identity |
| We use JWT for authentication | JWT is a token format; the protocol that authenticated someone is a different thing | Tokens |
| OAuth logs the user in | OAuth delegates access to an application; OpenID Connect adds who logged in | OAuth and OIDC |
| Strong MFA means the user is trusted for this action | Assurance of identity and authority to act are separate questions | Authenticators |
The vocabulary on one request#
The broker's request already contains every word this site needs. Here they are on the actual objects, not on a building badge.
- The principal is whoever the request is made by or for: here the person
u-broker-n1. Principals can also be applications, workloads, services and agents. - The subject is the principal as the policy sees it: the verified
subclaim plus attributes such astenant: brk-northandroles: [broker]. - The resource is the specific thing acted on: the record behind
Q-6620, with its own attributes (tenant: brk-south). Not "quotes", and not the URL. - The action is the business operation:
quote.read. - The context is everything else that matters: the time, how strongly she authenticated, the client she used.
- The policy is the set of rules that maps those four to a decision: on this site the authorization policy
authz-2026.11.1. - The decision is the answer with its reason:
deny, status 404, ruleR-AZ-03, "record belongs to another tenant". - The enforcement point is the code in the request path that asks for the decision and obeys it: here the quote service.
Identity and trust primitives gives each word its full treatment and shows who verifies what at each hop.
One request, four hops#
In the example, the broker's request crosses four hops before any data moves: her browser and the portal's backend, the API gateway, the quote service, and the database. Each hop sees a different credential and can answer a different question. The lab lets you walk the request and change one thing at a time: the quote she asks for, a forged x-app-id header, a gateway that is the only check, an API key in place of her token, a caller sitting inside the private network.
| Situation | Gateway (svc-api-gateway) | Quote service (svc-quote) | Database | Outcome |
|---|---|---|---|---|
| Broker reads own quote Q-5531 | token valid, audience matches, scope present: pass | PDP rule R-AZ-03: allow | one row; tenant taken from the verified context | 200 |
| Broker reads Q-6620 (other tenant) | pass (coarse: it never sees the record) | PDP rule R-AZ-03: deny, not found | not reached | 404, existence not revealed |
| Same, but only the gateway checks (BOLA) | pass | no object check: trusts the gateway | one row by id only | 200, another tenant's quote leaked (UW-A03) |
A script sends x-app-id: svc-cockpit-bff to a service that trusts the header | bypassed | header trusted, PDP skipped | one row | 200, leaked to an unauthenticated caller (UW-A04) |
| Same script, service requires the mTLS peer identity | bypassed | no verified peer identity: deny | not reached | 401 |
| Portal sends its API key instead of the broker's token | key valid: pass | the key names the application, not the broker: deny by default | not reached | 403 |
| A workload inside the private network, no credential | bypassed | caller unknown: deny | not reached | 401 |
Read the table from the top. In the first two rows, every sensitive hop made a decision about the record: the gateway on the token, the service on the quote, the repository on the tenant. In row three the same valid token and the same scope produced a leak, because the only check that ran could not see the record. Row four is worse: a header that any program can type was treated as an identity. The fix in both cases is the same sentence: prove who, then decide what, on the record itself.
Diagram: One request, four hops · who checks what
Follow the broker's request for Q-6620 from left to right. The portal backend attaches her access token. The gateway can check the token, its audience and a coarse scope, but it never sees the record. The quote service asks the PDP about this record and refuses with 404. The database query would carry the tenant from the verified context, not from the request. Remove the service check and the gateway alone lets the request through: that is BOLA, case UW-A03.
- Hop 1 · caller
- broker via portal BFF: The portal's backend holds the broker's session and attaches her access token to the API call.
- Hop 2 · gateway
- API gateway: Coarse checks at the edge: the token is valid, meant for this API, and carries the route's scope. It cannot know who owns Q-6620.
- Hop 3 · service
- quote service asks the PDP: The service that owns the data loads the record's attributes and asks the policy decision point. It obeys the answer.
- Hop 4 · database
- repository predicate: Even the query carries the tenant from the verified subject, never from a request parameter, as a second line of defense.
The example's agent here is a scripted stand-in, so these results show how the access controls work, not how good any model is.
Six architectures, one table#
The same five questions get different answers depending on who is calling and for whom. Read this table as the map of the site.
| Pattern | Who authenticates? | What gets authorized? | Where is it enforced? |
|---|---|---|---|
| Single-user script | Often the local operating system user | The files and APIs the script can reach | The operating system, the application, the remote service |
| Browser and backend | The person, through a session | The route, the business action and the record | The backend, its API and the data layer |
| Service to service | The calling workload or service | The API operation and the resource | The receiving service |
| Shared MCP server | The user and/or the workload, as the design requires | The tool call, its arguments and the downstream resource | The MCP server and the downstream service |
| Agent acting for a person | The agent's workload and the person's delegated authority | A task-scoped action on specific resources | The tool gateway or service, plus business policy |
| Multi-tenant retrieval (RAG) | The person, the workload and the tenant context | Each document or chunk the caller may read | The retrieval layer and the source systems |
One warning before the details. No single scheme fits all six rows. A nightly reconciliation job has no end user, so a design that demands a person's token on every call breaks it, or pushes someone to invent a fake user. The right requirements come from the principal and the delegation model in front of you. Playbooks works through the choice for six kinds of system.
Start simple, and know what makes you grow#
Every architecture on this site has a simplest credible starting point and a trigger that tells you to grow. The site never assumes the biggest design.
| Case | Starting choice | Escalation trigger |
|---|---|---|
| Single-user local prototype | Operating system user identity and local application controls | Shared users, a hosted API, sensitive secrets |
| Single-application web portal | A managed identity provider, a secure server session, business checks on the server | Federation, several tenants or several applications |
| Machine-to-machine service | Managed workload identity or OAuth client credentials | Delegation across boundaries, shared identity governance |
| Enterprise microservices | Workload identities and gateway controls plus authorization in every service | Fine-grained policy across services, audit at scale |
| B2B multi-tenant SaaS | An identity provider and tenant-scoped object policy | Customer federation, fine-grained organization roles |
| Public agent tool | An explicit tool identity, permission and business validation | Many hosts share the tool: MCP or API gateway governance |
| Agent acting for a user | Separate the agent's identity from the user's delegated authority | Task-scoped grants, third-party permissions, approvals |
| Multi-tenant semantic search | Tenant and source permission filters enforced by the backend | Shared indexes, complex resource relationships, deletions |
Common confusion. API keys are not always wrong in production, a certificate does not prove that a person is behind a request, and a scope or a role does not settle which row someone may read. Network segmentation and a web application firewall are useful layers; neither replaces the authorization decision in the service that owns the data.
The example in one minute#
The whole site follows one synthetic insurer that sells commercial property insurance through brokers. The brokerages are the tenants of the broker portal: brk-north and brk-south. Inside the insurer, work belongs to business units: commercial-west and commercial-east. Those are two separate boundaries.
A broker asks for a quote. The portal's backend creates the quote_id; intake maps it one to one to the insurer's internal submission id. The broker sees Q-5531; the underwriting team works SUB-1004. Authorization is decided on the record both ids point to, never on which id a caller happened to send.
| quote_id | submission_id | tenant | business unit | assigned underwriter |
|---|---|---|---|---|
Q-5531 | SUB-1004 | brk-north | commercial-west | u-uw-w1 |
Q-5532 | SUB-1007 | brk-north | commercial-west | u-uw-w2 |
Q-6620 | SUB-2001 | brk-south | commercial-east | u-uw-e1 |
The underwriting agent gathers evidence for SUB-1004 with tools: the roof assessment (the application said 9 years, the provider says 22), the current guidance, similar past decisions. It writes a recommendation with reasons and citations. The human underwriter assigned to the submission decides in the underwriter cockpit. The model recommends; a person decides.
Along the way the example meets every chapter. The broker's session lives in the portal's backend, never as a token in her browser. The agent runs with its own workload identity, and carries a narrower token that says it acts for the underwriter, for one submission, for one run. The assessment service holds the roof-data vendor's key in a secrets store; no model ever sees it. Retrieval filters guidance and attachments by tenant, unit and policy version before any text reaches the model, and re-checks each passage against its source. When a retrieved passage tells the agent to record a decision itself, the request is refused: the decision tool belongs to a person, through the cockpit, after a fresh strong authentication. Kafka producers and consumers have their own scoped identities. And the audit trail records who decided, which agent helped, under which authorization policy version, without a single token in it.
The principals appear as roles and ids only: two brokers, three underwriters (one of them the peer who is not assigned), an auditor, a platform administrator with no standing rights, the intake agent and the underwriting agent, and the services between them. The cases are this site's own, UW-A01 to UW-A24, plus the series cases UW-004, UW-005 and UW-009.
What this is not. This is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the tenants, people, rules, keys, tokens, certificates and every number are invented, and nothing here reports the quality of a real system or model. The demo tokens are signed with HMAC from the Python standard library using keys that say they are not secrets: teaching code. In production, use a maintained library and a real identity provider.
Where this fits#
Auth is one of fifteen subjects in a series of guides by the same author. Each site owns one question about agentic software and links the others where the subjects meet, instead of repeating them. This one is marked below.
Four neighbours matter most. Agent Communication (just before this site) carries messages between agents; this site decides whether the sender may ask. Guardrails (just after) puts enforceable checks around what the model does; this site decides which principal may do what. MCP Engineering explains the protocol for shared tools; the MCP chapter here gives its authorization from the identity side. RAG Engineering explains how retrieval works; the RAG chapter here owns who may retrieve which chunk.
How to read this site#
The chapters follow the order in which questions come up when a system grows from one login to agents acting for people. Each chapter starts from a moment in the insurance example, explains the idea in plain words, shows the smallest working version, then the failure, the design choice, the test and the advanced notes (folded, for experienced readers). If you know a part well, skip it; every chapter links back to the words it uses.
Foundations. From one login to a token another service can check.
Authorization. Who may do what to which record, and who runs the rules.
Workloads and the enterprise. Services, networks, streams and clouds.
AI-native access. Models, tools, retrieval and agents as callers.
Operations and reference. Proving it works, and keeping it working.
In one breath#
Every request answers five questions: who claims to be calling, what proves it, may this caller do this to this record now, is that answer enforced on every path, and what is recorded. A login, a token, a certificate, a network location or a header answers at most the first two. The decision about the record is made by policy, in the service that owns the data, every time. Agents change who the caller is, not the rule.
Start with Identity and trust primitives: the same request to read one quote, taken apart hop by hop, with the exact name of each piece and the component that checks it.