An architecture review at the insurer has three items on its agenda. A data engineer wants to run a nightly script that reconciles quote counts between the portal and the underwriting system. The broker portal team wants to let a second brokerage group sign in with its own identity provider. And the underwriting team wants the agent to book roof inspections with an outside scheduling service on the underwriter's behalf.
Someone proposes one rule for all three: "every call carries a user token and an application token, validated at the gateway." It sounds rigorous. It is wrong for the first item, because the nightly script has no user; forcing one in means inventing a fake account that everybody shares. It is incomplete for the second, because the gateway never sees which brokerage owns a quote. And it is dangerous for the third, because forwarding the underwriter's token to an outside service hands that service everything the underwriter can do.
Every chapter on this site has argued the same point from a different side: the right design comes from the principal and the delegation model in front of you, not from a template. This chapter turns that into six playbooks. Each one starts with the simplest design that is honestly secure, names the trigger that should make you grow it, lists the alternatives and what each depends on, says how it fails, and ends with a checklist you can apply on Monday.
Plain English. A playbook is a worked decision: given this kind of system, start here, grow when this happens, watch for these failures. A decision record is the written trace of one such decision, so the next team knows why.
How to read a playbook#
Each playbook answers the same six questions, in the order an architect asks them.
- Who are the principals? People, applications, workloads, agents, and whether one acts for another.
- Simplest credible option. The smallest design that still answers all five questions from the Start page: identification, authentication, authorization on the record, enforcement on every path, audit.
- Escalation trigger. The concrete change that makes the simple option insufficient.
- Alternatives and dependencies. What else would work, and what each one needs to exist first.
- Failure modes. How this design usually breaks, with the chapter that explains the fix.
- Production checklist. Short, testable items.
Diagram: Six playbooks · start simple, grow on a trigger
Each column is one kind of system, with the simplest credible design in the first box and the trigger that makes it grow in the second. Columns are not a ladder of maturity: a script with its own scoped identity is finished, not junior. Click a box for the detail.
- 1 · Script or job
- own job identity: A dedicated non-human identity scoped to the job's work; credentials from the platform.
- trigger: writes or shared use: A second user, a hosted API, or any write makes the simple option insufficient.
- 2 · Public SaaS
- IdP + server session: Managed sign-in, an HttpOnly cookie session, and a policy check on every record.
- trigger: API clients: Another client needs API access, or a second application should share sign-in.
- 3 · B2B multi-tenant
- tenant on subject + row: The tenant comes from the verified identity; every row carries it; the repository adds it again.
- trigger: federation: Customers bring their own identity provider, roles or provisioning.
- 4 · Private enterprise
- workload identity + per-service authz: Verified service identities, caller allowlists, and every service deciding on its own records.
- trigger: shared policy: Many services need the same fine-grained rule, or investigations need central audit.
- 5 · Event platform
- one principal per app: Producers and consumers each have their own identity and only the operations they need.
- trigger: self-service: Teams provision topics themselves, or events leave the organization.
- 6 · Autonomous agent
- own identity + narrow delegation: The agent has its own workload identity and a short-lived delegated token for one task; tools re-check every call.
- trigger: shared tools, A2A: Tools shared across hosts, delegation to other agents, or long-running tasks.
What this is not. These playbooks are not a maturity model where more components mean more security. A nightly script with an operating system account and a scoped database role is a finished design, not a beginner's one. Growth is justified by a trigger, never by the wish to look complete.
Playbook 1 · A script or a single-user tool#
Principals. One person running a program on their own machine, or one scheduled job with no person behind it. The data engineer's nightly reconciliation is the second kind.
Simplest credible option. For a person's local tool: the operating system user is the identity, and the files and services the tool can reach are the authorization. For a scheduled job: a dedicated non-human identity (a service account, a cloud workload identity, or a managed identity) with read-only access to exactly the two tables it compares. No user token, because there is no user. Credentials come from the platform or a secrets manager, not from a file next to the script.
Escalation trigger. A second person starts using the tool; the tool moves to a hosted API; it starts touching sensitive data or writing anything; or its credential would let it do more than its job.
Alternatives. An API key scoped to one read endpoint is reasonable when the target service offers nothing better and the key lives in a secrets manager with rotation. OAuth client credentials when the target is a resource server behind an authorization server.
Failure modes. The job runs under a person's account, so it breaks when that person leaves (governance, the orphan account svc-legacy-export). A long-lived key sits in the repository (coding agents). The job is given write access "in case".
Production checklist.
- The job has its own identity, named for the job, with an owner.
- Its permissions are read-only and limited to what it compares.
- No credential is in source code, configuration in the repository, or a prompt.
- The identity appears in access reviews and is removed when the job is retired.
Playbook 2 · A public SaaS web application#
Principals. Members of the public signing in to one application, and the application's backend calling its own APIs.
Simplest credible option. A managed identity provider (or a maintained library) for sign-up, sign-in and recovery; passkeys offered, passwords stored only as salted slow hashes if you keep them (people); a server-side session in an HttpOnly, Secure, SameSite cookie held by the backend (sessions); and business authorization in the backend on every record: a user reads their own data because the query and the policy both say so, not because the user interface hides other rows.
Escalation trigger. A mobile app or a third party needs API access; you add a second application that should share sign-in; regulation demands a stronger assurance level; you add organizations with several members (that is playbook 3).
Alternatives. Tokens in the browser instead of a backend for frontend, with the trade-offs sessions sets out. OpenID Connect with an external provider for "sign in with" buttons (OAuth and OIDC).
Failure modes. Object-level checks missing behind a correct login (the broker reading Q-6620: BOLA, enforcement). CSRF on a cookie session without a token or fetch-metadata check. Account recovery by email that silently undoes MFA. CORS treated as an access control.
Production checklist.
- Every endpoint that returns or changes a record asks a policy about that record.
- A test proves user A cannot read, change or delete user B's records (threat-testing).
- Cookies carry
HttpOnly,Secureand an explicitSameSite; state-changing requests are protected against CSRF. - Recovery has the same assurance as sign-in, and sensitive actions ask for step-up.
- Sign-in, failed sign-in and recovery events are recorded without secrets (audit).
Playbook 3 · A B2B multi-tenant SaaS#
Principals. People who belong to customer organizations (the brokerages brk-north and brk-south), their administrators, your own support staff, and your services.
Simplest credible option. One identity provider, a tenant attribute on every subject that comes from the verified identity (never from a request parameter), a tenant column on every tenant-owned row, and an object-level policy in the service that owns the data. The repository adds the tenant predicate from the verified context as a second line (tenants, QuoteRepository.find). Cross-tenant reads answer 404, so existence is not revealed (UW-A02).
Escalation trigger. Customers ask to sign in with their own identity provider (federation, SAML or OIDC: OAuth and OIDC); customers need their own fine-grained roles; a customer needs provisioning from their directory (SCIM); contracts require data residency or separate databases.
Alternatives. Row-level security in the database as the enforced second line (tenants, the PostgreSQL run). Schema or database per tenant when isolation must be physical. A relationship engine when access follows sharing and hierarchy rather than flat tenancy (models, policy as code).
Failure modes. The tenant id taken from the URL or the body. A support tool or a background job that bypasses the policy. An aggregate or export path that forgot the tenant filter. A search index or vector store that holds every tenant's text in one place without per-chunk permissions (RAG).
Production checklist.
- The tenant comes from the verified subject only; no endpoint accepts it as input for authorization.
- Cross-tenant negative tests run in CI for every read and write path, including exports and search (
test_negative.pyhas the pattern). - Support access to a tenant is time-bound, approved and audited (privileged access).
- Federation, if offered, maps each external identity provider to exactly one tenant.
Playbook 4 · A private enterprise platform#
Principals. Employees and contractors from an enterprise directory, many internal services, administrators, and partners.
Simplest credible option. The enterprise identity provider for people, with groups provisioned from the HR source of truth (governance); workload identities for services (mutual TLS with short-lived certificates, or a platform-issued identity: workload identity, TLS and PKI); an API gateway for coarse checks at the edge plus authorization in every service on the records it owns (gateways and zero trust); each receiving service keeps an allowlist of which callers may call which operations; and audit records that a security team can query.
Escalation trigger. Fine-grained policy that several services must share consistently (then a policy engine: policy as code); audit at a scale where each team's logs no longer answer an investigation (audit); a regulator asks who could access what on a given date; a private controlled environment with egress control and an internal certificate authority (private environments).
Alternatives. A service mesh for mutual TLS (identity at the connection, never business authorization). Token exchange so a downstream call carries a narrowed token instead of the original one (OAuth and OIDC). Cloud IAM roles for workloads that live in one cloud (cloud IAM).
Failure modes. "It came from inside the network, so it is trusted" (hops preset private). A plain x-app-id header treated as the caller's identity (UW-A04). The gateway as the only check (UW-A03). Movers who keep old access. Standing administrator rights that nobody reviews.
Production checklist.
- Every service authenticates its callers with a verified credential, not a header.
- Every service decides on its own records, even behind a gateway.
- Joiner, mover and leaver changes reach access within an agreed time, and a test shows a leaver loses access (
UW-A17). - Administrator rights are eligible, not standing; break-glass is loud and reviewed (
UW-A18,UW-A19). - Key and certificate rotation is rehearsed without downtime (operations).
Playbook 5 · An event-driven platform#
Principals. Producer and consumer applications, stream processors, replay and repair tools, and the people who operate them.
Simplest credible option. Each producer and consumer has its own principal (a client certificate or SASL credential per application, never one shared account), ACLs that grant exactly the operations each needs (produce on one topic; consume on one topic with one consumer group), default deny, and a provisioning workflow that creates the principal and its ACLs together (Kafka). Events carry provenance (who produced it, for which submission, under which run), never a bearer token.
Escalation trigger. Many teams self-serve topics (a provisioning portal is one organizational pattern, not a Kafka requirement); events cross a trust boundary to another organization; replay or dead-letter repair tools need access to data their operators should not read; schema changes need their own permission (Kafka, schema registry).
Alternatives. OAuth-based client authentication to the broker where the platform supports it; mutual TLS with an internal certificate authority; prefixed ACLs per team namespace.
Failure modes. A consumer that can also write and so can forge events. A token copied into an event payload and replayed later. A dead-letter topic readable by everyone. A replay tool that re-publishes under its own identity, so provenance is lost (UW-A15).
Production checklist.
- One principal per application; no shared credentials between producer and consumer.
- Consumers have no write permission on the topics they read.
- Replay and repair tools have their own principal, their own audit, and no broader read than their job.
- Events carry provenance fields and no credential of any kind.
Playbook 6 · An autonomous agent acting for people#
Principals. The agent's own workload, the person it acts for, the services and tools it calls, and the person who decides.
Simplest credible option. The agent runs with its own workload identity. When it acts for a person, it obtains a narrower delegated token by token exchange: the person as subject, the agent as actor, one audience, the scopes the task needs, a short life (agents, UW-A22). Every tool or service re-checks the request against policy on the specific record, so a model that writes an unexpected request is refused by deterministic code (MCP, UW-A21). Actions with irreversible effects, and every final business decision, belong to a person, through their own interface, after a fresh strong authentication (UW-A12). Retrieval filters by the verified identity and revalidates against the source (RAG). Model provider credentials stay in a gateway or cloud IAM (model providers).
Escalation trigger. The agent calls tools shared across many hosts (MCP or API gateway governance); it delegates work to another agent, possibly in another organization (A2A trust); it acts on third-party systems with their own consent; it runs long enough that a task token would outlive the person's session.
Alternatives. The agent acting only on its own authority, with no delegation, for background tasks no person requested (then it is playbook 1 or 4, and its permissions must be scoped to that job). A tool gateway in front of all tools that enforces policy centrally, in addition to each service's own check.
Failure modes. The person's token forwarded to a tool (token passthrough). The agent given the person's full rights instead of a task-scoped subset. A retrieved passage that persuades the model to request a write, and a tool that trusts the request because the model "decided" (UW-005, refused in the example by scope and by rule R-AZ-09). An audit record that names the agent but not the person it acted for, or the other way round.
Production checklist.
- The agent's token can never carry the decision permission; a test proves it is refused even when misgranted.
- Every delegated token names the person, the agent, the audience, the task and the expiry.
- Every tool call is authorized on the record by deterministic code, and refused calls are audited.
- Human decisions are recorded with who decided, the agent's recommendation, the authorization policy version and the reason.
- Retrieval never accepts a filter written by the model.
The six playbooks side by side#
| Playbook | Principals | Simplest credible option | Escalation trigger | Typical failure |
|---|---|---|---|---|
| Script or single-user tool | one person or one job | operating system user, or a dedicated job identity with read-only access | shared use, hosted API, writes, sensitive data | job runs as a person; key in the repository |
| Public SaaS | public users, one backend | managed identity provider, server session, object checks in the backend | mobile or third-party API access, more applications | BOLA behind a correct login; recovery undoes MFA |
| B2B multi-tenant SaaS | members of customer organizations | tenant on the verified subject, tenant on every row, object policy, repository predicate | customer federation, custom roles, residency | tenant id taken from input; export path without filter |
| Private enterprise | employees, services, admins | enterprise IdP, workload identities, gateway plus per-service authorization | shared fine-grained policy, audit at scale | trust by network location; header as identity |
| Event-driven platform | producers, consumers, tools | one principal per application, minimal ACLs, provenance without tokens | self-service topics, cross-boundary events | consumer can write; token in a payload |
| Autonomous agent | agent workload, delegating person | own identity plus narrowed delegated token, per-call policy, human decision | shared tools, agent-to-agent delegation | token passthrough; model output trusted as permission |
Write the decision down#
A decision that lives only in a meeting is re-argued every six months. An architecture decision record (ADR) is a short document that states the context, the decision, the alternatives considered and the consequences, kept next to the code. For auth decisions it should also name the principals, the trigger that would reopen it, and the tests that prove it.
Here is the record the insurer's review wrote for its third agenda item. It is illustrative, written for this site.
ADR-017 Agent books roof inspections on the underwriter's behalf
Status: accepted (illustrative)
Context: The underwriting agent (wl-underwriting-agent) must ask an external
inspection-scheduling agent to book an inspection for SUB-1004 when
R-ROOF-03 fires. The underwriter u-uw-w1 owns the submission.
Principals: agent workload; underwriter as delegator; external agent as recipient.
Decision: The agent exchanges the underwriter's delegated token for a new token
whose audience is the external agent only, scope inspection.request, subject
u-uw-w1, actor wl-underwriting-agent, lifetime 10 minutes. No underwriter token
leaves the insurer. The external agent authorizes the request on its side.
Alternatives rejected: forwarding the underwriter's token (passthrough);
a shared API key for all bookings (loses who asked and for whom).
Consequences: one more exchange per booking; audit records both principals.
Reopen when: the external agent needs to read submission data, or bookings
become irreversible commitments with cost.
Tests: token for another audience refused; scope beyond inspection.request
refused at exchange; audit record names u-uw-w1 and the agent.
In a coding agent. The same habit pays off for repository automation. A one-page record that says "the coding agent uses a repository-scoped GitHub App installation, proposes pull requests, cannot merge, and CI deploys through OIDC federation with no stored cloud keys" answers most of a later audit before anyone asks. Coding agents explains each piece.
Diagram: One decision record · from context to the test that proves it
Read left to right. The record states the context and the principals, the decision and the rejected alternatives, the consequences, the trigger that would reopen it, and the tests that prove it holds. The last box is the one most records forget.
- Context
- principals and delegation: Name every principal and whether one acts for another before deciding anything.
- Decision
- chosen design: The design, plus the alternatives considered and why each was rejected.
- Reopen
- escalation trigger: The observable change that would make this decision wrong.
- Prove
- negative tests: Tests that fail if the decision is silently undone.
Choosing in a review: three questions#
When a design arrives at review, three questions sort most of it out quickly.
Is there a person behind this request? If not, do not invent one. Give the job or service its own identity and scope it to its work. If yes, ask whether something acts for that person, because then there are two principals and both must be visible to the policy.
Where is the decision about the record made? Point to the line of code or the policy rule that decides whether this caller may touch this specific record. If the answer is "the gateway" or "the user interface hides it", the design is not finished.
What happens when a component is down or a credential leaks? The identity provider, the policy decision point, the audit store, a signing key. Writes should fail closed; the blast radius of a leaked credential should be one job, one task or one tenant, never everything (operations).
When two playbooks apply at onceMost real systems combine them; keep each principal in its own playbook.
The insurer's platform is all six at once: scheduled reconciliation jobs (1), a broker portal for the public in a business role (2 and 3), an internal enterprise platform (4), an event stream between intake and underwriting (5), and an agent acting for underwriters (6). The mistake is to pick one playbook for the whole platform. The workable approach is per principal and per path: the nightly job follows playbook 1 even though it runs inside the enterprise platform; the agent follows playbook 6 even when it reads from Kafka, where its consumer identity follows playbook 5. Write one decision record per path that crosses a trust boundary, and let each record reference the playbook it follows.
Triggers are evidence, not calendar datesGrow a design when its assumption breaks, and write down which assumption.
Each simple option rests on an assumption: "only one person uses this", "the gateway is the only way in", "tenants never share data", "the agent never acts outside one submission". An escalation trigger is the observable moment that assumption stops being true: a second user appears in the logs; a service gets an internal address that bypasses the gateway; a customer asks for cross-organization sharing; a task needs a second submission. Teams that write the assumption into the decision record can attach a test or an alert to it. Teams that do not usually discover the broken assumption in an incident review. The playbooks above name triggers so that you can turn each into a check: a query over access logs, a CI test, an alert on a new route.
The cost of growing too earlyEvery component you add must be operated, rotated, monitored and understood.
A policy engine, a token exchange service, a service mesh and a privileged access system each solve a real problem, and each adds a component that can fail, a configuration that can drift, and a skill the team must keep. Adding them before the trigger appears does not make a system safer by itself; it often moves the real decision to a place fewer people understand. A small service with a clear object check in code, tests for every negative case, and audit records is easier to reason about than the same service behind three layers nobody reviews. Grow when the trigger appears, and when you grow, keep the tests from the simple version: they are the evidence that the bigger design still does what the small one did.
Exercises#
- The data engineer's reconciliation job now also needs to mark mismatched quotes for review. Which playbook still applies, and what changes in its identity and permissions?
- A brokerage asks to sign in with its own identity provider. Which trigger is this, which chapter covers the mechanism, and what must the mapping guarantee?
- A colleague proposes giving the underwriting agent the underwriter's full token "to keep it simple". Name two failure modes from playbook 6 that this creates.
AnswersShort answers to the three exercises.
- Still playbook 1, but the job now writes: give it a separate write permission limited to the review flag on the quotes table (or a separate job identity for the write), add it to access reviews, and record its writes in audit.
- It is playbook 3's federation trigger. OAuth and OIDC covers OIDC and SAML federation; the mapping must bind that external identity provider to exactly one tenant,
brk-northfor example, so its users can never receive another tenant's attribute. - Token passthrough (every tool receives the underwriter's full authority and audience), and the agent exceeding a task-scoped subset (it could reach the decision action or other submissions; in the example only the scope ceiling and rule
R-AZ-09stop it).
In one breath#
Start every design from the principals and the delegation model, choose the simplest option that still decides on the record and audits the decision, and write down the assumption that makes it enough. Grow when a named trigger shows that assumption broke, not before. Keep the negative tests from the small design as the proof that the bigger one still holds.
That completes the chapters. The glossary collects every term with what it is and what it is not, and About lists the sources each claim was checked against, with the date.