Security Architecture Decision Records (ADRs) Guide

Security teams lose the reasons behind their own designs, so the same debates repeat, accepted risks outlive their owners and auditors get a diagram with no rationale. An architecture decision record (ADR) is a short, numbered document that captures one significant decision, its context, the options considered and its consequences. This guide shows how to adapt the ADR practice, as described by Michael Nygard, MADR, AWS Prescriptive Guidance and Microsoft's Azure Well-Architected Framework, for security decisions: which decisions need one, the extra fields a security ADR needs, how to approve and supersede them, and how to turn a decision into a check that runs in the pipeline. It is for security architects, platform engineers and the people who sign off risk. For the review process that often produces these decisions, see the Security Architecture Review Guide.

Key takeaways

Record the why, not the how. AWS guidance says an ADR should focus on why a decision was made, so later teams do not overrule it without context; implementation detail belongs in linked design documents.
Security ADRs need a few extra fields. Threats addressed, identities and secrets created, residual risk with a named owner, a confirmation check and a review date turn a design note into usable governance evidence.
Accepted records are immutable. Both AWS and Microsoft say not to edit an accepted ADR: write a new one that supersedes it and link the two, so the history survives.
A decision without a check decays. MADR's optional Confirmation section is where you say how compliance is verified, ideally a policy-as-code rule or test that fails the build.
Keep the log next to the code. Numbered Markdown files in the repository, reviewed by pull request, beat a wiki page that nobody updates.

What a security ADR is, and what it is not

Nygard's 2011 post defined the original five sections: Title, Context, Decision, Status and Consequences, each record one or two pages, numbered in sequence and never reused. The collection forms what AWS calls a decision log. A security ADR is the same artefact applied to choices where security is a driver or a consequence. It overlaps with several existing documents, which is why teams often skip it.

Artefact	Answers	Lifespan	How it relates to an ADR
Security ADR	Why did we choose this option over the alternatives?	Life of the system; superseded, never deleted	The record of the decision itself
Design document or solution architecture	How is it built?	Updated as the design changes	Linked from the ADR; Microsoft warns against ADRs becoming design guides
Threat model	What can go wrong and what do we do about it?	Refreshed on change	Input to the ADR context; the ADR records which mitigation was chosen. See the Threat Modelling Guide
Security architecture review	Is this design acceptable?	Point in time	Produces decisions that should be captured as ADRs
Risk acceptance or exception	Who accepts the remaining risk, until when?	Time-limited	Referenced from the ADR when residual risk exceeds appetite. See the Security Exceptions and Risk Acceptance Guide
Policy or standard	What must every system do?	Reviewed annually	An ADR applies the standard to one system or records a justified deviation

Which security decisions need an ADR

AWS lists the categories of architecturally significant decision: structure, non-functional requirements such as security, dependencies, interfaces and construction techniques. Microsoft narrows it to choices that affect structure or key quality attributes, or that are hard to reverse. For security, write an ADR when the decision:

Creates or changes a trust boundary: a new external API, a cross-account or cross-tenant trust, a partner connection, a new network zone.
Chooses an authentication or authorisation mechanism: OIDC versus SAML, mTLS versus signed tokens, RBAC versus ABAC, where policy is enforced.
Creates non-human identities or secrets: a service account, workload identity federation, API keys for a third party, an AI agent's credentials.
Selects cryptography or key custody: algorithm, key management service, HSM versus software keys, customer-managed keys, certificate authority.
Handles regulated or sensitive data: storage location, tokenisation versus encryption, retention, cross-border transfer.
Accepts a known weakness: a legacy protocol, a missing control with compensating measures, a vendor limitation.
Adopts a security product or platform that other teams will depend on.

Do not write ADRs for decisions already fixed by a mandatory standard with no options. Link the standard from the system documentation instead.

Anatomy of a security ADR

Start from MADR (version 4.0.0, September 2024) or Nygard's format, then add security fields. MADR's required sections are Context and Problem Statement, Considered Options and Decision Outcome; it also offers Decision Drivers, Consequences, Confirmation and front matter for status, date, decision-makers, consulted and informed. Microsoft adds a Confidence level, which helps when a low-confidence decision is reconsidered.

Field	Source	What to write for security
ID and title	Nygard, MADR	ADR-0042: Workload identity federation for CI deployments. Short noun phrase, sequential number
Status and date	Nygard, AWS, MADR	Proposed, Accepted, Rejected, Deprecated or Superseded by ADR-NNNN
Decision-makers, consulted, informed	MADR	Include the security architect and the risk owner by name or role
Context and problem statement	All	Business need, data classification, applicable policy clauses, threat model reference
Decision drivers	MADR	Security requirements stated as testable constraints, e.g. "no long-lived credentials in CI"
Considered options	MADR, Microsoft	At least two real options, including the ones ruled out and why
Decision outcome	All	The chosen option in active voice
Threats addressed	Security extension	Threat model IDs or ATT&CK techniques the decision mitigates
Identities and secrets	Security extension	Every NHI, credential or key created, its owner, storage and rotation
Consequences and residual risk	Nygard, AWS	Positive, negative and neutral effects; residual risk rating; exception reference if above appetite
Confirmation	MADR	The check that proves compliance: policy rule, test, CSPM control or review
Confidence and review date	Microsoft; extension	High, Medium or Low, and the date or trigger for re-review
Links	Microsoft	Design documents, review record, related and superseded ADRs

Example: a compressed security ADR

ADR-0042: Use OIDC workload identity federation for CI deployments to cloud. Status: Accepted, supersedes ADR-0017. Confidence: High.
Context: pipelines deploy with static cloud access keys stored as CI secrets, contrary to the secrets standard. Threat: stolen CI secrets reused from outside the pipeline.
Options: keep static keys with 90-day rotation (ruled out: still long-lived); vault-issued dynamic credentials (viable, more moving parts); OIDC federation with repository and branch conditions (chosen).
Identities: one deployment role per environment; trust policy restricted to the repository and protected branch; no stored secret.
Consequences: removes stored keys; trust policy conditions become security-critical; forks and unprotected branches must not match.
Confirmation: a policy-as-code rule fails any trust policy without a subject condition; a weekly query reports any remaining access keys for CI users.

See the Policy-as-Code for Authorisation Guide for writing confirmation rules.

Lifecycle, approval and governance

AWS describes a review with a 10 to 15 minute reading period, then discussion and one of three outcomes: rework (stays Proposed with action items), reject (reason recorded) or approve (timestamp, version and stakeholders added, status Accepted). Once accepted or rejected, the record is not edited. A changed decision is a new ADR, and the old one becomes Superseded.

Decision type	Author	Approver	Must consult
Within one system, low risk	Engineer or tech lead	Tech lead	Security champion
New trust boundary, NHI or sensitive data	Solution architect	Security architect	IAM or NHI owner, data owner
Residual risk above appetite	Solution architect	Named risk owner	CISO delegate; record an exception
Platform or cross-organisation pattern	Platform architect	Architecture or design authority	Teams that will consume it

The UK Government Secure by Design principles start with "Create responsibility for cyber security risk", asking teams to assign risk owners accountable across the service life cycle. The approver column is where that accountability becomes visible. In November 2025 DSIT and GDS also published an Architectural Decision Record Framework for government teams, which is a useful starting template in the public sector.

Superseding: link both ways. The new ADR says what it supersedes; the old one gets a single status change and a forward link.
Expiry: security ADRs with Low confidence or an attached exception get a review date. A scheduled job that lists ADRs past review date keeps them honest.
Brownfield: Microsoft suggests recording known past decisions retroactively. Start with the decisions behind your largest trust boundaries and longest-lived credentials.

Where identity fits

Many security ADRs are identity decisions in disguise, and they are where non-human identities quietly come into existence. A decision to integrate with a SaaS tool creates an OAuth client; a decision to use a message queue creates a service principal; a decision to add an AI agent creates a credential with delegated authority. Requiring the "Identities and secrets" field means every NHI has a recorded owner, purpose and rotation approach from day one, which is exactly what is missing when teams later try to inventory them. Link the ADR ID in the identity's tags or description so an orphaned account can be traced back to the decision that created it. See the Service Account Security Guide and the NHI Ownership Guide.

How to implement

Pick a template: adopt MADR with the security fields above as your organisation's single template. Microsoft's guidance is to use one consistent template for every record.
Choose storage: Nygard used doc/arch/adr-NNN.md; MADR uses docs/decisions/NNNN-title-with-dashes.md. Pick one, keep it in each system's repository, and add a central index for platform-wide decisions.
Pilot with two teams for a quarter: one greenfield, one brownfield. Write ADRs for every new trust boundary and NHI, and back-fill the three most important past decisions.
Wire it into existing gates: the architecture review outcome is an Accepted ADR; pull requests that change IAM policy, network rules or cryptography link an ADR ID. AWS suggests reviewers link the relevant ADR when code violates it.
Add confirmation checks: for each Accepted security ADR, implement the check in CI or CSPM, starting in report-only mode before failing builds.
Scale: publish the index, train security champions, and add ADR coverage to the review metrics below.
Rolling back: if the process slows delivery, narrow the trigger list rather than abandon it; a rejected or superseded ADR is itself useful history.

Decision guidance

Lightweight versus full template: use Nygard's five sections for low-risk, single-team decisions. Use the full security template where a trust boundary, NHI or residual risk is involved.
Per repository versus central log: per repository keeps decisions next to the code they govern; a central log suits platform patterns and cross-team decisions. Large organisations usually need both, with the central log linking out.
Small organisations: one shared repository and a monthly review is enough. Approver and risk owner may be the same person, but write the name down.
Regulated organisations: ADRs are useful audit evidence for why controls were designed as they are. Protect the repository's history (branch protection, signed commits) so records stand up as evidence.

Detection and measurement

Coverage: percentage of systems in scope with at least one Accepted security ADR for each trust boundary.
NHI traceability: percentage of service accounts, OAuth clients and API keys tagged with an ADR ID.
Confirmation rate: percentage of Accepted security ADRs with an automated confirmation check.
Drift: confirmation check failures per month, and time to resolve or supersede.
Staleness: ADRs past their review date, and exceptions linked to ADRs past expiry.

Monitor the repository itself: changes to Accepted ADRs (other than status) should raise a review, because the immutability rule is what gives the log its evidential value.

Framework mapping

Framework	Reference	How security ADRs contribute
NIST SP 800-53 Rev. 5	PL-8 Security and Privacy Architectures; SA-8 Security and Privacy Engineering Principles; SA-17 Developer Security and Privacy Architecture and Design	Documented rationale for the architecture and how principles were applied
NIST SP 800-53 Rev. 5	CM-3 Configuration Change Control; CM-4 Impact Analyses	Superseding ADRs record significant changes and their security impact
NIST SP 800-53 Rev. 5	RA-3 Risk Assessment; RA-7 Risk Response	Residual risk and chosen response recorded per decision
NIST CSF 2.0	GV.RM-04; ID.RA-06; ID.IM-01	Risk response options, tracked responses, improvements from evaluations
ISO/IEC 27001:2022 Annex A	8.27 Secure system architecture and engineering principles; 8.32 Change management	Evidence that principles were applied and changes controlled
UK Secure by Design	Principle 1 Create responsibility for cyber security risk; Principle 10 Make changes securely	Named risk owners and recorded change decisions

Common failure patterns

Only the chosen option is recorded: without the ruled-out options, a later team re-proposes the rejected design. Microsoft explicitly asks for options ruled out.
Editing accepted records: rewriting history removes the evidence of what was decided and when. Supersede instead.
ADRs as design documents: ten-page records nobody reads. Keep to one or two pages, as Nygard advised, and link the detail.
Residual risk with no owner: "accepted risk" with no named approver or expiry. Link a formal exception.
No confirmation: the decision says "no long-lived keys" while the estate still has them. Without a check, the ADR is aspiration.
Undocumented NHI decisions: integrations approved informally leave credentials no one can explain years later, the pattern behind many token-theft incidents.

Practitioner checklist

Adopt one template: MADR plus threats addressed, identities and secrets, residual risk owner, confirmation and review date.
Publish a trigger list of security decisions that require an ADR.
Store ADRs as numbered Markdown in each repository, with a central index.
Define approvers by decision type, with named risk owners for residual risk.
Make Accepted records immutable and supersede with two-way links.
Tag every new NHI with the ADR ID that created it.
Implement an automated confirmation check for each Accepted security ADR.
Run a monthly job that lists ADRs past review date and exceptions past expiry.
Back-fill ADRs for your largest trust boundaries and longest-lived credentials.

Security architecture decision records (ADRs): How to write, approve and enforce them