MSA0.3 Architecture Decision Records

The configuration lives in the portal. Anyone with admin access can see that MFA is enforced, that a CA policy exists, that DLP rules are active. What nobody can see in the portal is why. Why push notification MFA and not passkeys? Why does the CA policy exclude that group? Why does DLP cover email but not Teams? ADRs are the mechanism that captures the reasoning — and makes it auditable, transferable, and defensible. This sub teaches the ADR format through two worked examples that include actual Graph API output, PowerShell commands, CA What If evaluation, and sign-in log evidence.

Estimated time: 30 minutes.

The problem ADRs solve

MSA0.1 showed you a CA policy with an MFA exclusion group containing an IT Director with Global Administrator privileges. The JSON was there. The exclusion was visible. What was missing was any record of why that exclusion existed, who approved it, what compensating controls applied, and when it should be reviewed.

That's the problem ADRs solve. The configuration tells you what the tenant looks like right now. The ADR tells you why it looks that way, what would break if you changed it, and what risk the organization knowingly accepted when the decision was made. Without that documentation, every security setting is a black box — you can see it, but you can't understand it, maintain it, or defend it to an auditor.

Architecture Decision Records are a format borrowed from software engineering, where they originated in the Thoughtworks technology radar in the early 2010s. The concept is simple: every significant design decision gets a short document that captures the context, the decision, the alternatives rejected, and the consequences. In software architecture, this prevents teams from revisiting settled decisions or breaking systems by changing things they don't understand. In security architecture, it serves the same purpose — plus it produces the audit evidence that compliance frameworks require.

This sub teaches the format through two complete worked examples. The first is a complex decision with multiple alternatives, trade-offs, and a multi-phase rollout. The second is a simpler decision where the alternatives are fewer but the exceptions and consequences still matter. Both include real tenant artifacts — because an ADR without evidence is an opinion, not architecture.

Why decisions need documentation

The MCRA identifies "disconnected security approach" as one of the most common antipatterns — independent security teams, strategies, and processes that don't connect. ADRs are the mechanism that creates coherence. Every significant decision is documented with its reasoning, its dependencies, and its consequences.

ADRs serve three audiences, each with different needs.

Your successor. The person who inherits the tenant when you move on. They can see the configurations. They can't see why. Without ADRs, they either maintain everything as-is (preventing improvement), change things and break dependencies they didn't know existed, or spend weeks reverse-engineering the reasoning from the configuration. With ADRs, they read the decision log, understand the constraints that shaped each choice, and know which settings are deliberate architecture and which are inherited configuration nobody's reviewed.

Your auditor. ISO 27001 Annex A.5.1 requires documented information security policies. SOC 2 CC1.1 requires control environment documentation. Cyber Essentials requires evidence that security controls are deliberately configured. An ADR with Graph API evidence, What If validation results, and sign-in log confirmation is audit-ready. A portal configuration without documentation is a setting — not a documented control.

Your leadership. The CISO who asks why, the board member who asks about risk, the IT director who asks about cost. Each needs the decision communicated at their level. The Communication field provides the 30-second answer — specific enough to be useful, concise enough to be heard.

The ADR format

Every ADR in this course follows a six-field format. The format is designed to be completed in 10–15 minutes per decision — comprehensive enough to be useful, compact enough to be sustainable. Here's what each field captures and what separates a good entry from a useless one.

Context. What architectural problem are you solving? What constraints exist? Constraints include licensing (E3 vs E5), legacy systems, organizational politics, user populations, regulatory requirements, budget, and timeline. The context field should be specific enough that someone reading it in two years understands why a decision was needed — not just that a decision was made. Include the current state from the API: "Current grantControls shows builtInControls: ["mfa"] with authenticationStrength: null" is a context statement grounded in evidence. "MFA needs to be improved" is not.

Decision. What did you decide? State it as a clear, specific, verifiable action: "Enforce phishing-resistant MFA for all users in the Finance and Executive persona groups via Conditional Access authentication strength policy referencing ID 00000000-0000-0000-0000-000000000004." Not "implement better MFA." Specific, actionable, verifiable by querying the API.

Alternatives Considered. What other options did you evaluate, and why were they rejected? List each with a one-sentence reason that references a specific constraint. "FIDO2 hardware keys — rejected because procurement lead time is 12 weeks and the threat model requires immediate coverage" is defensible. "We considered other options" is not.

Consequences. What does this decision enable, and what does it break? Every security control has consequences beyond its intended effect. Dependencies on other ADRs go here.

Residual Risk. What does this decision not protect against? What risk remains? If the ADR claims zero residual risk, the architect hasn't thought hard enough. Name the gap, the compensating control, the remediation timeline, and the cross-reference to the ADR that addresses the long-term fix.

Communication. The 30-second CISO version. One to two sentences that translate the technical decision into business language.

Worked example 1 — Authentication method selection

This ADR documents a decision you'll encounter in MSA2. The context is a mid-size organization with M365 E5 and four persona groups.

ADR-MSA2-001: Primary authentication method for Standard and Finance persona groups

Context. NE operates M365 E5 with 810 users across four persona groups (Standard, Finance, Executive, IT Admin). Current authentication: password plus push notification MFA via Microsoft Authenticator, deployed 18 months ago. Current CA policy grant controls:

{
  "operator": "OR",
  "builtInControls": ["mfa"],
  "customAuthenticationFactors": [],
  "termsOfUse": [],
  "authenticationStrength": null
}

authenticationStrength: null means any MFA method satisfies the policy. Push notification MFA does not prevent AiTM because the session token is captured after MFA completion — the reverse proxy forwards the authentication to the real Microsoft endpoint, and the session cookie issued after successful authentication (including MFA) is intercepted and replayed. M-Trends 2025 reports AiTM as the primary identity attack vector for M365 environments. NE's threat model (MSA0.4) identifies AiTM phishing as the #1 identity risk.

Constraints: 30% of users on mobile devices without biometric capability. 15% are contractors on unmanaged devices. Hardware security key budget ($30,000–50,000 for FIDO2 keys) not approved this fiscal year.

Decision. Deploy passkeys (device-bound, via Microsoft Authenticator) as the primary authentication method for Standard and Finance persona groups. Enforce via CA authentication strength policy. Implementation:

$params = @{
  DisplayName = "Require Phishing-Resistant MFA - Standard and Finance"
  State       = "enabledForReportingButNotEnforced"
  Conditions  = @{
    Users = @{
      IncludeGroups = @("a1b2c3d4-...", "e5f6a7b8-...")
    }
    Applications    = @{ IncludeApplications = @("All") }
    ClientAppTypes  = @("all")
  }
  GrantControls = @{
    Operator             = "OR"
    AuthenticationStrength = @{
      Id = "00000000-0000-0000-0000-000000000004"
    }
  }
}
New-MgIdentityConditionalAccessPolicy -BodyParameter ($params | ConvertTo-Json -Depth 5)

Note State: "enabledForReportingButNotEnforced" — report-only mode first. This generates What If-equivalent results in the sign-in logs without blocking anyone. The appliedConditionalAccessPolicies array in sign-in logs will show result: "reportOnlyNotApplied" for users who would be blocked, letting you identify who needs to register a phishing-resistant method before enforcement.

Alternatives Considered.

• FIDO2 hardware keys — strongest phishing resistance, hardware-bound private key that never leaves the device. Rejected for standard users: procurement cost ($30,000–50,000), 12-week lead time, physical distribution to 6 NE sites. Retained for IT Admin group (ADR-MSA2-003).
• Certificate-based authentication (CBA) — requires PKI infrastructure that NE doesn't operate. Deploying a PKI for the authentication use case alone is disproportionate. Rejected.
• Windows Hello for Business (WHfB) — phishing-resistant, included in E5, no hardware purchase. Considered as primary, but only works on Windows devices. NE has 15% macOS and 20% mobile-only users. Retained as a complementary method alongside passkeys for Windows users.
• Push notification MFA (status quo) — does not meet phishing-resistant requirement per NE threat model. Rejected as primary; retained as transitional fallback for contractor population.

Consequences.

• Enables: CA policies can differentiate phishing-resistant sessions from non-phishing-resistant. Tiered access controls become enforceable. Sign-in logs show enforcedGrantControls: ["RequireAuthenticationStrength"] instead of ["Mfa"], providing audit evidence of phishing-resistant enforcement.
• Breaks: Users who haven't registered a passkey are blocked when the policy moves from report-only to enforced. Estimated impact: 690 users in Standard and Finance groups need passkey registration before enforcement.
• Requires: Registration campaign, user communication plan, support desk training for passkey troubleshooting, and a report-only testing period (minimum 14 days). CA What If validation across all persona groups before enforcement.
• Dependencies: Persona group membership must be correct (ADR-MSA1-002). Authentication methods policy must allow passkey registration (ADR-MSA2-002).

Validation. Before moving from report-only to enforced, run the CA What If evaluation. The What If tool in the Entra admin center evaluates whether a simulated sign-in would pass the policy. Here's the API equivalent — the response body from POST /identity/conditionalAccess/evaluate:

{
  "appliedPolicies": [
    {
      "displayName": "Require Phishing-Resistant MFA - Standard and Finance",
      "result": "reportOnlyNotApplied",
      "reasonForResult": "User has not registered a phishing-resistant authentication method",
      "enforcedGrantControls": ["RequireAuthenticationStrength"],
      "conditionsSatisfied": ["users", "applications"],
      "conditionsNotSatisfied": ["grantControls"]
    }
  ]
}

result: "reportOnlyNotApplied" tells you this user would be blocked if the policy were enforced — they haven't registered a passkey. conditionsNotSatisfied: ["grantControls"] confirms the specific failure. Run this across a sample of users from each persona group before flipping to enforced.

Residual Risk. Contractor population (15%, ~120 users) continues on push notification MFA, which is vulnerable to AiTM. Compensating control: contractors restricted to session-proxied applications via Defender for Cloud Apps, limiting blast radius of a compromised session. Session duration limited to 1 hour for contractor persona group (ADR-MSA3-008). Remediation target: Q3 2026 when managed device enrollment for contractors completes (ADR-MSA6-004).

Communication. "We're deploying phishing-resistant sign-in for all employees using their existing phones — no hardware purchases. This blocks the #1 identity attack technique. Contractors move to the same standard when their device enrollment completes in Q3."

After enforcement, the sign-in log confirms the architecture is live:

{
  "createdDateTime": "2026-04-22T08:41:15Z",
  "userPrincipalName": "t.ashworth@yourtenant.onmicrosoft.com",
  "conditionalAccessStatus": "success",
  "appliedConditionalAccessPolicies": [
    {
      "id": "5f8b3d72-a1c4-4e9b-b267-8d3f2a6c1e05",
      "displayName": "Require Phishing-Resistant MFA - Standard and Finance",
      "result": "success",
      "enforcedGrantControls": ["RequireAuthenticationStrength"]
    }
  ],
  "authenticationDetails": [
    {
      "authenticationMethod": "Microsoft Authenticator (Passkey)",
      "authenticationMethodDetail": "Device-bound passkey",
      "succeeded": true,
      "authenticationStepResultDetail": "MFA requirement satisfied by strong authentication"
    }
  ],
  "deviceDetail": {
    "deviceId": "7c4a2e91-b3d8-4f5a-a169-8d7e3c2b1f46",
    "isCompliant": true,
    "trustType": "AzureAd"
  }
}

The ADR documents the decision. The PowerShell implements it. The What If validates it before enforcement. The sign-in log proves it's working after enforcement. That's the complete chain — reasoning, implementation, validation, evidence. Every significant decision in this course follows the same pattern.

Worked example 2 — Blocking legacy authentication

This is a simpler ADR for a less ambiguous decision — but the format is identical. Simpler decisions still need documentation because the consequences and exceptions still matter.

ADR-MSA3-001: Block legacy authentication protocols

Context. NE's current CA policies don't block legacy authentication. The policy "Require MFA — All Users" targets clientAppTypes: ["all"], which includes modern auth clients but doesn't explicitly block legacy protocols (Exchange ActiveSync basic auth, POP3, IMAP4, SMTP AUTH, older Office clients using ADAL). Legacy auth protocols don't support MFA — they authenticate with username and password only. Any CA policy that requires MFA is automatically bypassed by a client using legacy auth, because the legacy client never presents an MFA claim.

Query current legacy auth sign-in volume:

$legacySignIns = Invoke-MgGraphRequest -Method GET `
  -Uri "https://graph.microsoft.com/v1.0/auditLogs/signIns?`$filter=clientAppUsed ne 'Browser' and clientAppUsed ne 'Mobile Apps and Desktop clients'&`$top=100"
$legacySignIns.value |
  Group-Object clientAppUsed |
  Select-Object Name, Count |
  Sort-Object Count -Descending

Name                           Count
----                           -----
Exchange ActiveSync             47
Autodiscover                    23
SMTP AUTH                       12
Other clients                    8
IMAP4                            3

93 legacy auth sign-ins in the most recent 100 non-modern-auth entries. The Exchange ActiveSync entries are likely mobile email clients that haven't been migrated to the Outlook app or modern auth. SMTP AUTH entries are typically multifunction printers or line-of-business applications sending email.

Decision. Create a CA policy that blocks legacy authentication for all users with one exception group for service accounts that require SMTP AUTH for application email sending, pending migration to the Microsoft Graph sendMail API.

Alternatives Considered.

• Block all legacy auth with no exceptions — would break multifunction printers and the ERP system's email notification feature. Rejected until those systems are migrated.
• Set CA policy to report-only and monitor — delays the security improvement. Legacy auth is a known, active attack vector (password spray attacks exclusively use legacy auth because it bypasses MFA). Rejected in favor of immediate block with documented exceptions.

Consequences.

• Enables: All MFA-requiring CA policies are now effective against password spray attacks using legacy protocols. Eliminates the single largest MFA bypass vector in the tenant.
• Breaks: 47 Exchange ActiveSync sessions will fail. Users affected need to switch to the Outlook mobile app or another modern auth client. 12 SMTP AUTH sessions from printers/applications will fail unless the service accounts are in the exception group.
• Requires: User communication about mobile email client migration. Exception group with documented service accounts. Migration timeline for SMTP AUTH to Graph API sendMail.
• Dependencies: None — this policy is independent.

Residual Risk. Three service accounts in the exception group continue to use SMTP AUTH with basic credentials. Compensating controls: dedicated service accounts with strong passwords (32+ characters), restricted to SMTP send only via Exchange transport rules, sign-in logs monitored in Sentinel for anomalous source IPs. Remediation: migrate to Graph API sendMail by Q4 2026 (ADR-MSA7-003).

Communication. "We're shutting down the one authentication backdoor that lets attackers bypass MFA entirely. Three printer service accounts get a temporary exception with monitoring. Everyone else is protected immediately."

ADR anti-patterns

ADRs lose their value when they fall into these traps. You'll see all of these in real tenants — recognize them so you don't repeat them.

"Microsoft recommended it." Not a rationale. Microsoft's recommendations are designed for the median customer across millions of tenants. Your organization has specific threat models, specific constraints, specific populations. The ADR must explain why the recommendation is appropriate for your context. If you can't articulate why beyond "it's best practice," you don't understand the decision well enough to document it.

No alternatives listed. If only one option was considered, the decision isn't defensible. Maybe there genuinely was only one viable option — but document why the other options were rejected. "FIDO2 keys were the only phishing-resistant option considered because CBA requires PKI and WHfB requires Windows" is a valid alternatives section. An empty alternatives section means either the architect didn't evaluate options (undisciplined) or evaluated them mentally but didn't document them (not transferable).

No residual risk statement. Every security control has gaps. A CA policy that requires MFA for all users still has an exception group. A DLP policy that blocks external sharing still allows internal sharing to compromised accounts. If the ADR claims zero residual risk, the architect hasn't examined the control's boundaries. The residual risk field is where honesty lives — it's the statement that says "this is what we chose not to protect against, and here's why that's acceptable."

Communication field = Decision field. The Communication field isn't a technical summary. It's a translation. "Deploy passkeys via CA authentication strength policy referencing ID 00000000-0000-0000-0000-000000000004" is a technical decision. "We're blocking the #1 identity attack technique for our highest-risk users first, using their existing phones, no procurement required" is a business communication. Different audience, different language, different purpose.

No evidence attachments. An ADR that says "we configured phishing-resistant MFA" without the Graph API output, the What If result, or the sign-in log entry is an assertion, not evidence. The attachments are what make the difference between documentation someone trusts and documentation someone has to verify by opening the portal.

Your first ADR

Before moving to MSA0.4, write one ADR. Pick any security decision you've made or observed in an M365 tenant — an MFA method selection, a CA policy, a DLP rule, a Sentinel connector deployment. Use the six-field format. Include at least one tenant artifact — a PowerShell output, a Graph API JSON response, a sign-in log entry. Spend 10–15 minutes.

If you don't have a real decision to document, use this scenario: NE currently has 14 permanent Global Administrator assignments and no PIM configuration. You need to reduce standing GA to 2 accounts and move the rest to PIM-eligible. Document the decision as an ADR, including: what the current state looks like (query Get-MgDirectoryRoleMember for the Global Administrator role), what the implementation looks like, what exceptions you'd allow, and what residual risk remains.

Before moving on, verify your understanding: Name the three audiences for ADRs and explain what each needs that the portal configuration alone can't provide. Look at worked example 1's Alternatives Considered field. For each rejected alternative, identify the specific constraint that made it unsuitable for NE's context. Explain why "we considered other options" would fail as an alternatives entry.

Reusable script — the commands from this sub assembled for operational use:

Copy this template for every significant security design decision. The evidence slots are what distinguish a Ridgeline ADR from a generic documentation template.

ADR-[MODULE]-[NUMBER]: [Decision title]

CONTEXT
  Problem: [What architectural problem are you solving?]
  Constraints: [Licensing, legacy, politics, timeline, regulatory]
  Current state evidence:
    Command: [PowerShell command that shows current state]
    Output:  [Graph API JSON or command output]

DECISION
  Action: [Specific, verifiable statement]
  Implementation:
    Command: [PowerShell/Graph API that implements the change]

ALTERNATIVES CONSIDERED
  1. [Alternative] — rejected because [specific constraint/reason]
  2. [Alternative] — rejected because [specific constraint/reason]

CONSEQUENCES
  Enables:  [What this unlocks — be specific]
  Breaks:   [What this disrupts — quantify the impact]
  Requires: [Pre-requisites, registration campaigns, training]
  Depends on: [Cross-references to other ADRs]

VALIDATION
  Method: [CA What If / attack simulation / sign-in log review]
  Evidence:
    [What If JSON result or sign-in log entry showing enforcement]

RESIDUAL RISK
  Gap: [What this decision does not protect against]
  Compensating control: [What mitigates the gap]
  Remediation: [Timeline and cross-reference to future ADR]

COMMUNICATION
  CISO version: [30 seconds, business language]

APPROVAL
  Approved by: [Name, role, date]
  Review date: [When this ADR should be revisited]