Cybersecurity Engineering Handbook / Chapter 62
Security Architecture Decision Record Template
Record security architecture decisions with threats, assumptions, options, controls, residual risk, evidence, and review triggers.
Preparing audio…
Audio edition
Security Architecture Decision Record Template
The Customer Export Service has a cross-tenant path to close. Everyone agrees that tenant context must come from the authenticated subject before a job enters the queue. The disagreement begins one boundary later.
One proposal treats the API check as decisive. Another signs the derived context and requires the worker to reject a mismatch. A third also reauthorizes the archive at download time. Each additional check costs engineering work and another operational dependency. Each omitted check asks a component to trust an earlier decision, even after the job has waited in a queue or the archive has acquired its own identifier.
The team needs more than the winning option. Future reviewers need to know which threat forced the choice, why cheaper designs lost, what must remain true for the approved design to be safe, and which change makes the old reasoning untrustworthy. That is the work of a security architecture decision record.
Record the argument while it can still be challenged
Write a decision record when reasonable designs place trust, enforcement, or evidence in materially different places. Authentication and authorization patterns, tenant boundaries, key custody, data retention, third-party integrations, deployment trust, model and tool access, and logging retention commonly deserve one. A routine implementation detail already governed by an approved standard usually does not.
Begin with the pressure that makes a choice necessary. Context includes the system behavior, business need, constraints, and boundaries that narrow the options. It should not smuggle the preferred answer into the problem statement. “Export jobs run asynchronously and archives are retrieved later” is context. “The API must sign every job” is already a decision.
Threats and assumptions divide hostile possibility from relied-upon fact. The export service faces request-supplied tenant identifiers, altered queue messages, stale authorization, archive-ID substitution, and compromised privileged actors. It assumes the identity provider authenticates subjects correctly, but it does not assume a request body, queue message, or archive identifier carries authority merely because an earlier component accepted it.
Compare real alternatives. State where each option enforces policy, which attacker step it interrupts, what it must trust, how it fails, what operators must run, and what evidence could reveal a defect. Cost belongs in the comparison, but a small implementation estimate cannot compensate for an attacker path the design leaves open. Keep a rejected option in the record when its appeal is likely to return.
Then make one decision. “Use defense in depth” is not an architecture. Name the source of authority, every required enforcement point, the information carried between them, and the behavior on mismatch or uncertainty. Separate the decision from its required controls so that later implementation work cannot quietly discard the conditions that made approval defensible.
The working record
This form is deliberately sequential. The reasoning should lead a reviewer from the force on the system to the choice, then from the choice to proof and continuing ownership.
# Security Architecture Decision: <decision in plain language>
## Identity and scope
- Decision ID and status:
- Date:
- System and accountable owner:
- Decision authority and reviewers:
- Related profile, threat, requirement, exception, and incident IDs:
- Supersedes or is superseded by:
## Context and decision pressure
- Behavior or capability under review:
- Binding business, technical, operational, and assurance constraints:
- Trust boundaries affected:
- Decision that must be made now:
## Threats and assumptions
- Attacker paths and consequences that govern the choice:
- Facts the design relies on:
- Facts the design refuses to trust:
- Unknowns that could change the decision:
## Options considered
### <option name>
- Enforcement design and trust placement:
- Security benefit and attacker steps interrupted:
- Failure modes and residual risk:
- Operational impact, migration work, and cost:
- Evidence capable of showing the option unsafe:
- Disposition and reason:
## Decision
- Approved design and why it survives the governing threats:
- Required behavior at each enforcement point:
- Failure behavior when context is missing, stale, or inconsistent:
- Migration or rollout boundary:
## Conditions of approval
- Required controls, owners, and due conditions:
- Verification and release evidence:
- Production signals, routing, and response ownership:
- Residual risk and authorized risk owner:
## Reopen, supersede, or retire
- Concrete review triggers:
- Review date, if time itself changes the risk:
- Evidence that permits supersession or retirement:
Proposed means the record is still open to challenge. Approved means the named authority accepted the design with its conditions; it does not mean every control is implemented. Rejected preserves an alternative and its failure. Superseded points to the decision that replaced this one. If the organization needs a separate implementation state, record it separately rather than overloading decision status.
Follow the export decision across its boundaries
The record below resolves the attacker path developed in the preceding threat scenario. Notice that the cheapest option is plausible. The record rejects it because asynchronous work and later retrieval create new authorization moments, not because more controls are automatically better.
# Security Architecture Decision: Bind tenant authority across export creation,
# processing, and download
## Identity and scope
- Decision ID and status: SADR-AUTHZ-EXPORT-003; approved
- Date: 2026-07-10
- System and accountable owner: Customer Export Service; Customer Data Platform
service owner
- Decision authority and reviewers: Customer Data Platform director; Security
Architecture, Data Platform, and SRE reviewers
- Related records: SSP-EXPORT-007; TS-AUTHZ-EXPORT-002;
AUTHZ-EXPORT-004; DATA-EXPORT-002; LOG-AUTHZ-003
- Supersedes or is superseded by: initial decision; none
## Context and decision pressure
- Behavior under review: an authenticated tenant administrator starts an
asynchronous export, a worker builds an archive, and the administrator later
requests a download URL
- Binding constraints: jobs may wait or retry; workers cannot call the user
directory during a regional identity outage; archives contain regulated
tenant data; download authorization must remain available independently of
export creation
- Trust boundaries affected: subject to API policy; API to queue; worker to
object storage; subject and archive ID to download policy
- Decision required now: where tenant authority is derived, carried, and
rechecked across the three stages
## Threats and assumptions
- Governing paths: a tenant A administrator supplies tenant B's identifier;
queued context is altered or replayed; a valid archive ID is substituted at
download; a later worker trusts a payload format more broadly than today's
worker
- Relied-upon facts: the identity provider authenticates the subject; the
policy service supplies current tenant membership at request and download;
the signing service protects job-envelope integrity
- Refused trust: tenant IDs in request bodies, unsigned queue attributes,
possession of an archive ID, and an earlier authorization result after the
requested resource or action has changed
- Unknown: future delegated exports may authorize a third-party integration
rather than a human administrator
## Options considered
### Authorize only before enqueue
- Design: derive tenant context from the subject and authorize export creation
at the API; let the worker and download path trust stored identifiers
- Benefit: blocks request-body tenant substitution with the least migration
work and no new worker dependency
- Failure: does not detect altered job context or archive substitution and
gives future consumers an easy way to confuse identity with authority
- Evidence: API negative tests can prove the first boundary but cannot make
claims about queue integrity or download ownership
- Disposition: rejected because it leaves two steps of the named attacker path
governed by possession of data rather than a policy decision
### Authorize before enqueue and verify signed worker context
- Design: derive and authorize tenant context at the API, sign the job envelope,
and make the worker reject a mismatch
- Benefit: closes request and queue substitution paths without requiring an
identity lookup during job execution
- Failure: possession or prediction of another tenant's archive ID can still
succeed if download checks role without resource ownership
- Operational impact: signing-key rotation and worker rejection telemetry are
required
- Disposition: rejected as the complete design; retained as the first two
enforcement points of the approved design
### Reauthorize at request, worker, and download boundaries
- Design: use the preceding option, then authorize subject, action, archive,
and tenant before issuing a short-lived single-object download URL
- Benefit: each stage validates the authority relevant to the object it handles;
a stale creation decision does not authorize a later download
- Failure and cost: adds policy-service dependence to download and requires
signed-envelope key operations, denial handling, and end-to-end testing
- Evidence: boundary-specific negative tests and correlated policy, queue,
worker, object, and download events can contradict the design's claims
- Disposition: approved because it closes every step of TS-AUTHZ-EXPORT-002
while keeping the worker independent of live identity lookup
## Decision
- The API derives tenant context from the authenticated subject and authorizes
export creation before enqueue.
- The API signs subject, tenant, export, action, issued-at time, and schema
version in the job envelope. The worker verifies the signature and rejects
missing, expired, or inconsistent context before reading tenant data.
- The download service derives current tenant membership and authorizes subject,
action, archive, and tenant before issuing a five-minute single-object URL.
- Denial or unavailable policy produces no export or URL. The migration ships
behind an export pause; old unsigned jobs are drained or cancelled rather
than accepted by the new worker.
## Conditions of approval
- Required controls: API object authorization, signed and versioned envelopes,
worker fail-closed validation, archive ownership metadata, download object
authorization, five-minute URLs, tenant-safe audit events, and routed mismatch
alerts. The API, worker, download, storage, and detection owners each own their
enforcement point before public release.
- Evidence: `export-tenant-boundary` tests independently change subject, tenant,
action, envelope, archive, and download request; signing-key rotation and
replay tests; code review at all three policy points; an alert exercise tied
to the reviewed release
- Production response: subject/job or archive/subject mismatch routes to Product
Security and the service owner, who decide whether to pause creation and
download while preserving API, queue, worker, policy, and object-access events
- Residual risk: a compromised legitimate administrator can export data already
authorized to that role. The Customer Data Platform risk owner accepts that
bounded risk with MFA, attributable audit, volume detection, archive expiry,
and customer incident procedures.
## Reopen, supersede, or retire
- Reopen when tenant hierarchy, delegated administration, third-party export,
job-envelope format, signing custody, archive addressing, policy availability,
or data classification changes, or when an incident contradicts an assumption.
- Review annually only to confirm that no trigger was missed; elapsed time alone
does not renew the reasoning.
- Supersession requires a linked record and evidence that the replacement covers
the same attacker path. Retirement requires proof that the export path or
protected asset no longer exists.
Review the claims, not the document
Read the record as a set of claims that may fail. Does the context permit more than one honest answer? Does every option expose its trust placement and failure mode? Could the named evidence reveal that the approved design is wrong, or does it merely show that work occurred? Are the controls conditions of approval, with owners, or a wish list appended after the choice?
Follow the decision into production as well. A design that fails closed during policy-service loss may protect confidentiality while making exports unavailable; that operational consequence belongs in review and testing. A signed envelope protects integrity only if key custody, rotation, schema interpretation, expiry, and replay behavior remain sound. A download check protects the archive only if it binds the current subject to that exact object and tenant.
The record remains useful until a governing fact changes. When a trigger fires, do not edit history until the old choice appears timeless. Create a superseding record, link both directions, and preserve why the earlier design was reasonable under its earlier facts. Architecture memory is valuable precisely because systems outlive the conditions under which their decisions were made.