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

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.

You will tell apart
Authentication, authorization, enforcement and audit, and the credential, token, session, scope and role each one uses.
You will be able to build
A small web application and a service-to-service flow where every sensitive hop decides on the record itself.
You will be able to explain
Delegated agent authority, multi-tenant retrieval, managed identity and governance to an architecture review.

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. 1 · Identification
    1. a claim: The caller says who it is. A claim costs nothing and proves nothing.
  2. 2 · Authentication
    1. verified identity: Proof is checked by the identity provider or the receiving service. The result is who, and how sure, never what.
  3. 3 · Authorization
    1. decision on the record: Policy decides whether this subject may perform this action on this resource now, and says why.
  4. 4 · Enforcement
    1. every path obeys: The code in each request path asks and obeys. A decision only one path respects is not a control.
  5. 5 · Audit
    1. 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 beliefWhat is trueChapter
She logged in, so she can see her dataA successful login proves identity; each request still needs a decision about the recordAuthorization
The token is valid, so the request is allowedA valid token proves who issued it, for whom and until when; it says nothing about quote Q-6620Tokens
It came from inside our network, so it is trustedA network location is not an identity; zero trust starts from that sentenceGateways and zero trust
The request carries x-app-id, so we know the callerA plain header is metadata anyone can type; identity needs a verified credentialWorkload identity
We use JWT for authenticationJWT is a token format; the protocol that authenticated someone is a different thingTokens
OAuth logs the user inOAuth delegates access to an application; OpenID Connect adds who logged inOAuth and OIDC
Strong MFA means the user is trusted for this actionAssurance of identity and authority to act are separate questionsAuthenticators

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.

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.

SituationGateway (svc-api-gateway)Quote service (svc-quote)DatabaseOutcome
Broker reads own quote Q-5531token valid, audience matches, scope present: passPDP rule R-AZ-03: allowone row; tenant taken from the verified context200
Broker reads Q-6620 (other tenant)pass (coarse: it never sees the record)PDP rule R-AZ-03: deny, not foundnot reached404, existence not revealed
Same, but only the gateway checks (BOLA)passno object check: trusts the gatewayone row by id only200, another tenant's quote leaked (UW-A03)
A script sends x-app-id: svc-cockpit-bff to a service that trusts the headerbypassedheader trusted, PDP skippedone row200, leaked to an unauthenticated caller (UW-A04)
Same script, service requires the mTLS peer identitybypassedno verified peer identity: denynot reached401
Portal sends its API key instead of the broker's tokenkey valid: passthe key names the application, not the broker: deny by defaultnot reached403
A workload inside the private network, no credentialbypassedcaller unknown: denynot reached401

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.

  1. Hop 1 · caller
    1. broker via portal BFF: The portal's backend holds the broker's session and attaches her access token to the API call.
  2. Hop 2 · gateway
    1. 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.
  3. Hop 3 · service
    1. 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.
  4. Hop 4 · database
    1. 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.

PatternWho authenticates?What gets authorized?Where is it enforced?
Single-user scriptOften the local operating system userThe files and APIs the script can reachThe operating system, the application, the remote service
Browser and backendThe person, through a sessionThe route, the business action and the recordThe backend, its API and the data layer
Service to serviceThe calling workload or serviceThe API operation and the resourceThe receiving service
Shared MCP serverThe user and/or the workload, as the design requiresThe tool call, its arguments and the downstream resourceThe MCP server and the downstream service
Agent acting for a personThe agent's workload and the person's delegated authorityA task-scoped action on specific resourcesThe tool gateway or service, plus business policy
Multi-tenant retrieval (RAG)The person, the workload and the tenant contextEach document or chunk the caller may readThe 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.

CaseStarting choiceEscalation trigger
Single-user local prototypeOperating system user identity and local application controlsShared users, a hosted API, sensitive secrets
Single-application web portalA managed identity provider, a secure server session, business checks on the serverFederation, several tenants or several applications
Machine-to-machine serviceManaged workload identity or OAuth client credentialsDelegation across boundaries, shared identity governance
Enterprise microservicesWorkload identities and gateway controls plus authorization in every serviceFine-grained policy across services, audit at scale
B2B multi-tenant SaaSAn identity provider and tenant-scoped object policyCustomer federation, fine-grained organization roles
Public agent toolAn explicit tool identity, permission and business validationMany hosts share the tool: MCP or API gateway governance
Agent acting for a userSeparate the agent's identity from the user's delegated authorityTask-scoped grants, third-party permissions, approvals
Multi-tenant semantic searchTenant and source permission filters enforced by the backendShared 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_idsubmission_idtenantbusiness unitassigned underwriter
Q-5531SUB-1004brk-northcommercial-westu-uw-w1
Q-5532SUB-1007brk-northcommercial-westu-uw-w2
Q-6620SUB-2001brk-southcommercial-eastu-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.

INSTRUCTPrompt EngineeringHow instructions are written, composed, ranked, versioned and defended. CURATEContext EngineeringThe working set the model can see now: selection, retrieval, budget, compaction. REMEMBERMemory EngineeringDurable information and saved execution state, and the difference. CONNECTAgent CommunicationMessages between agents, the A2A protocol, and A2A versus MCP. IDENTIFY · you are hereAuth EngineeringIdentity, delegation, enforcement and audit for every caller and every hop. PROTECTGuardrails EngineeringEnforceable checks around a probabilistic agent. SEEObservability EngineeringEvidence of what happened: logs, metrics, traces, audit events, replay. ACTTools EngineeringCallable capabilities: schema, execution, MCP tools. INTEGRATEMCP EngineeringShared capabilities across teams: when MCP is justified, identity, authorization, governance. RETRIEVERAG EngineeringRetrieval from SQL rows to production: embeddings, vector indexes, hybrid search, reranking. STRUCTUREStructured Output EngineeringTyped contracts: shape, validation, repair, evolution. COORDINATEAgent OrchestrationThe control plane: what runs next, under which condition. RECOVERAgent ReliabilityAcceptable outcomes despite failures, retries, load and changing dependencies. PublishedHarness EngineeringThe runtime around a model call: the agent harness. PublishedEvals for agentic softwareMeasurement: graders, golden sets, judges, trials, release gates. PublishedDiff to DeployShipping a change with coding agents: hooks, review, lanes, CI.

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.