A guided path from approved inputs to a reviewed Exchange change
Start the eight-step wizardThe active workflow evaluates a versioned Exchange-only profile for a Worldwide tenant. It uses Microsoft-managed Standard and Strict preset security policies without copying or modifying their individual settings.
Microsoft's recommended baseline profile for broad recipient coverage.
A more aggressive Microsoft-managed profile for selected high-value targets or priority users.
Automated Investigation and Response, Threat Explorer, and Attack Simulation Training are separate Microsoft Defender for Office 365 Plan 2 capabilities. Assigning Strict does not enable them.
One versioned Exchange-only configuration; Standard and Strict are recipient-targeted Microsoft presets, not separate script downloads.
__ADMIN_REQUIRED:... token with independently approved data.Standard and Strict are Microsoft-managed preset policies. This repository does not ship different scripts for them; administrators initialize the presets in the Microsoft Defender portal and manage the supported recipient scope. Virtually all individual settings in these presets are Microsoft-managed and cannot be customized. Custom policies do not override an applicable Standard or Strict preset because presets have higher precedence.
Start with the prerequisites and support boundary. When those fit your situation, continue to the ordered steps. Progress stays in this browser tab: your current step and scope and preset choices survive a refresh, but typed domains and addresses are not saved. The microsite does not save tenant data, connect to your tenant, or execute scripts.
O365Default)Use the exact module version approved for the change. Preset policies can be managed through applicable Defender Unified RBAC permissions or Exchange Online Organization Management or Security Administrator role groups. Global Administrator is highly privileged; prefer narrower supported roles.
Rollback restores only reviewed settings whose current state still matches the approved change. It cannot undo delivered or processed messages. Follow the approved-change runbook; do not recreate Microsoft-managed preset policies from exported data.
Open recovery instructionsEvery change needs two people. The scripts enforce this: Validate and Apply refuse an approval signed by the requester or by anyone not in the authorized signer file. This is the change's separation-of-duties control, not optional paperwork.
| Role | Who | What they do | What they need |
|---|---|---|---|
| You (requester and operator) | The Exchange admin running this walkthrough | Steps 1–5, then 7 and 8: prepare, check, preview, apply, collect evidence | Least-privilege Exchange role, the kit, the protected folder |
| Approver | A different person whose name is in the authorized signer file | Step 6 only, about 10 minutes: reviews your preview and signs it. Needs no Exchange connection or admin role. | PowerShell 7, the same kit, read/write access to your protected folder, and their enterprise signing certificate (with private key) whose subject matches the signer file |
| Approval authority owner | Usually change management or security; not you | Before Step 3: gives you the path to the protected authorized signer file. Keeps it out of your control. | — |
Before Step 1: know who your approver is, confirm they are in the signer file and have their certificate, and agree a time. The preview you send them expires 24 hours after Step 5, so they must sign within that window.
The active journey is limited to Worldwide tenants and has not validated sovereign-cloud or hybrid endpoints, authentication, licensing, or feature behavior.
Step 1 of 8: Get the change kit and open PowerShell 7
Step 1 · Get the kit
Everything after this step runs in one PowerShell 7 terminal, from the expanded kit folder. Keep that terminal open until Step 8.
Open Start, PowerShell 7 (or Windows Terminal, then run pwsh). Do not use “Windows PowerShell” 5.1. If PowerShell 7 is missing, install it first:
winget install --id Microsoft.PowerShell --source wingetPaste this whole block. The hash check must print True; if it prints False, delete the zip and stop.
$kit = Join-Path $HOME 'exchange-online-change-kit'
$release = 'https://github.com/chadhage/enterprise-scale-exchange-online/releases/latest/download'
Invoke-WebRequest -Uri "$($release)/exchange-online-change-kit.zip" -OutFile "$($kit).zip"
Invoke-WebRequest -Uri "$($release)/exchange-online-change-kit.zip.sha256" -OutFile "$($kit).zip.sha256"
$expected = (Get-Content -LiteralPath "$($kit).zip.sha256").Split(' ')[0]
(Get-FileHash -LiteralPath "$($kit).zip" -Algorithm SHA256).Hash -eq $expected
Unblock-File -LiteralPath "$($kit).zip"
Expand-Archive -LiteralPath "$($kit).zip" -DestinationPath $HOME -Force
Get-ChildItem -LiteralPath $kit -Recurse -File | Unblock-File
Set-Location -LiteralPath $kitInstall-Module ExchangeOnlineManagement -MinimumVersion 3.10.0 -Scope CurrentUser
./scripts/Test-ExchangeOnlineChangeReadiness.ps1 -WorkstationOnlyExchange Online change readiness (read-only)
Kit folder: C:\Users\admin\exchange-online-change-kit
1. Workstation and kit
Core 7.6.1; minimum 7.5
[PASS] Kit files present - 9 required files found
[PASS] Downloaded files unblocked - no Mark-of-the-Web found
[PASS] Execution policy allows local scripts - effective policy RemoteSigned
[PASS] ExchangeOnlineManagement module - installed 3.10.0; minimum 3.10.0
WORKSTATION READY: 5 checks passed.Any FAIL line prints the exact command that fixes it on the line below. Run that command, then rerun the check.
Stop if: the hash check prints False, or a FAIL remains after you run its fix.
Step 2 · Choose
Answer three questions. Each answer builds the exact values you paste in Step 3, and the commands in Steps 4 and 5 update to match. Record the same choices in your change ticket; the scope is frozen into the preview and cannot be widened later.
Tick only the scopes your approved ticket names. New to the workflow? Start with Transport alone. Badges tell you what each scope needs.
Your scope
Select at least one scope above.EopPresets or AtpPresets.Standard and Strict are Microsoft-managed preset policies. Everyone in your primary domain gets Standard. Members of one mail-enabled security group get Strict instead. The group is always required, even if it is empty.
What to do
Paste into your parameter file in Step 3
workflowOptions section.Some scopes need a workflowOptions section that names exactly what to change. Required sections are already ticked. Tick an optional one only if your ticket asks for it.
What to do
Paste into your parameter file in Step 3, then replace every REPLACE- value
Stop if: there is no approved ticket, the ticket's scope is unclear, or the work needs a new tenant, new users or groups, or first-time preset activation. Use the net-new Exchange administrator journey for that work.
Full scope table and adapter coverage Microsoft: preset security policiesStep 3 · Inputs
Create a protected folder outside the kit and outside any Git repository, then copy the sample parameter file into it. The sample is synthetic and is refused until you replace its values.
$protected = 'D:\ExchangeChanges'
New-Item -ItemType Directory -Path $protected -Force
Copy-Item -LiteralPath ./config/parameters.exchange-only.sample.json -Destination (Join-Path $protected 'contoso.parameters.json')
notepad (Join-Path $protected 'contoso.parameters.json')From your Step 2 choices
| Field | What to enter | Where it comes from |
|---|---|---|
MICROSOFT_ENTRA_TENANT_GUID | Your tenant ID (a GUID) | Microsoft Entra admin center, Overview, Tenant ID |
PRIMARY_SMTP_DOMAIN | Main email domain, such as contoso.com | You (Exchange admin) |
INITIAL_ONMICROSOFT_DOMAIN | Such as contoso.onmicrosoft.com | Microsoft 365 admin center, Settings, Domains |
EXTERNAL_POSTMASTER_SMTP_ADDRESS | Postmaster address for NDRs | You (Exchange admin) |
MAIL_ENABLED_PRIORITY_USERS_GROUP | Strict group email address (Step 2, question 2) | Group owner |
SECURITY_OPERATIONS_MAILBOX | SecOps mailbox address | Security operations |
MAILBOX_RETENTION_POLICY_NAME | Existing MRM policy name (governance scopes only) | Records management owner |
domainInventory | Every accepted domain, whether it sends mail, and its owner; also set tenantId | Domain/DNS owner |
entitlement | Licensing handoff: verified, tenantId, servicePlans, per-recipient recipients, future expiresOn, owner, reference | Licensing owner only. Never set verified to true yourself. |
| Input | What to enter | Example |
|---|---|---|
| Change ID | Your ticket number. Letters, digits, and hyphens, up to 64 characters. New for every attempt. | CHG-1001 |
| Requested by | UPN of the person requesting the change (you) | requester@contoso.com |
| Artifact folder | A new folder for this change's files. Created at Preview. | D:\ExchangeChanges\CHG-1001 |
| Authorized signer file | JSON list of who may approve. The approval authority owner provides it and keeps it protected from you. | D:\ExchangeChanges\authorized-signers.json |
| Your approver | The person you lined up before Step 1. Their UPN must be an Identity in the signer file and must not be yours. They sign in Step 6. | approver@contoso.com |
The authorized signer file looks like this. You receive it; you do not write it:
[
{ "Identity": "approver@contoso.com", "Subject": "CN=Approver Name", "Authority": "ExchangeOnlineChangeApproval" }
]Stop if: an owner has not supplied their value, the licensing handoff is missing or expired, or you are the only authorized signer. Never fill in a value just to get past a check.
How to resolve inputs and owner handoffsStep 4 · Ready check
Run the full readiness check with your values from Step 3. You do not need to connect first. The script checks the ExchangeOnlineManagement module, reuses an existing session, or signs you in (MFA prompts appear in your browser). It then shows the account and tenant and asks you to confirm them. The check is read-only. It confirms the workstation, files, inputs, licensing, signer list, the session tenant, your role's cmdlets, and preset initialization.
./scripts/Test-ExchangeOnlineChangeReadiness.ps1 `
-UserPrincipalName 'admin@contoso.onmicrosoft.com' `
-ParameterPath 'D:\ExchangeChanges\contoso.parameters.json' `
-ArtifactRoot 'D:\ExchangeChanges\CHG-1001' `
-ChangeId 'CHG-1001' `
-RequestedBy 'requester@contoso.com' `
-AuthorizedSignerPath 'D:\ExchangeChanges\authorized-signers.json' `
-Scope 'Transport'The -Scope value comes from your Step 2 choices.
-UseDeviceCode and enter the code on another device.N, run Disconnect-ExchangeOnline, and rerun with the right -UserPrincipalName.-ConfirmSession:$false to skip the account prompt. Use it only after you've checked the session.2. Change inputs (offline)
[FAIL] Licensing entitlement verified - ExchangeEntitlementUnverified: supply a current tenant- and recipient-bound licensing owner handoff (RAID-D02).
Ask the licensing owner for a current handoff; they set entitlement.verified, servicePlans, and a future expiresOn. Never set verified yourself.
NOT READY: 1 of 18 checks failed. Fix each item above, then rerun this script.3. Exchange Online session (read-only)
[PASS] Exactly one Exchange Online session - 1 connected session(s)
[PASS] Session tenant matches parameters - session 6c1f9a2e-… as admin@contoso.onmicrosoft.com
[PASS] Worldwide endpoint - https://outlook.office365.com/...
[PASS] Role grants Get-TransportConfig for Transport
READY FOR PREVIEW: 18 checks passed.
Copy these lines into this same terminal to create the preview:
$change = @{
ParameterPath = 'D:\ExchangeChanges\contoso.parameters.json'
ConfigurationPath = './config/exchange-only.v1.json'
ArtifactRoot = 'D:\ExchangeChanges\CHG-1001'
ChangeId = 'CHG-1001'
RequestedBy = 'requester@contoso.com'
AuthorizedSignerPath = 'D:\ExchangeChanges\authorized-signers.json'
PreviewPath = 'D:\ExchangeChanges\CHG-1001\preview-CHG-1001.json'
ApprovalPath = 'D:\ExchangeChanges\CHG-1001\approval-CHG-1001.json'
}
./scripts/Invoke-ExchangeOnlineChange.ps1 -Stage Preview @change -Scope 'Transport' -Confirm:$falseStop if: any line says FAIL after you apply its fix, especially the session tenant, licensing, or preset checks. For first-time preset activation, use the net-new preset guidance.
Microsoft: connect to Exchange Online PowerShellStep 5 · Preview
Paste the $change block and the Preview command that the readiness check printed. Preview reads the tenant and records every exact before-and-after value. It changes nothing. It is valid for 24 hours.
./scripts/Invoke-ExchangeOnlineChange.ps1 -Stage Preview @change -Scope 'Transport' -Confirm:$falseThen review what it plans to do:
$preview = Get-Content -LiteralPath $change.PreviewPath -Raw | ConvertFrom-Json
$preview | Select-Object ChangeId, Tenant, DeploymentProfile, Scope, GeneratedOn, ExpiresOn
$preview.Operation | ForEach-Object {
[pscustomobject]@{
Command = $_.Command
Identity = $_.Identity
Before = $_.Before.Value | ConvertTo-Json -Compress -Depth 10
After = $_.After.Value | ConvertTo-Json -Compress -Depth 10
}
} | Format-ListCheck each operation: the command, the object it targets, and the before and after values.
When the preview matches your ticket, copy a handoff note to the clipboard and send it to your approver (chat, email, or the ticket). It contains the $change block they paste, the preview fingerprint they compare, and the expiry time:
$previewHash = (Get-FileHash -LiteralPath $change.PreviewPath -Algorithm SHA256).Hash
$changeBlock = '$change = @{' + [Environment]::NewLine + (($change.GetEnumerator() | Sort-Object Key | ForEach-Object { " $($_.Key) = '$(([string]$_.Value).Replace("'", "''"))'" }) -join [Environment]::NewLine) + [Environment]::NewLine + '}'
@(
"Please review and sign Exchange change $($change.ChangeId) (requested by $($change.RequestedBy))."
"Preview SHA-256: $($previewHash)"
"Preview expires: $($preview.ExpiresOn) - please sign before then."
'In PowerShell 7, from the kit folder, paste this block, then follow Step 6a of the guided wizard:'
$changeBlock
) -join [Environment]::NewLine | Set-ClipboardThen wait. You continue with Step 6b after the approver tells you they have signed.
Stop if: the tenant, target, or value differs from your ticket. Do not edit the preview file. Fix the input, use a new change ID, and rerun Steps 4 and 5.
Open Invoke-ExchangeOnlineChange.ps1 Preview command and review guidanceStep 6 · Approve
This is the approver you lined up before Step 1 (see Who is involved). You sent them the handoff note at the end of Step 5. Step 6a is done by the approver on their own computer; you wait, then do 6b.
If you are the approver: open PowerShell 7 in the kit folder (Step 1 of this wizard, if you don't have the kit), paste the $change block from the handoff note, and confirm the preview is the one the requester sent. The hash must match the note exactly:
(Get-FileHash -LiteralPath $change.PreviewPath -Algorithm SHA256).HashReview the operations with the Step 5 review commands. If they match the ticket, sign with your enterprise certificate. You do not need an Exchange connection or admin role:
$approvalIdentity = 'approver@contoso.com'
$certificate = Get-Item -LiteralPath 'Cert:\CurrentUser\My\CERTIFICATE-THUMBPRINT'
./scripts/Invoke-ExchangeOnlineChange.ps1 -Stage Approve @change -ApprovalIdentity $approvalIdentity -SigningCertificate $certificateTo find your thumbprint, run Get-ChildItem Cert:\CurrentUser\My | Select-Object Subject, Thumbprint, NotAfter and pick the certificate whose subject matches your entry in the signer file. Signing writes approval-<ChangeId>.json into the shared folder. Tell the requester you have signed.
Approver, do not sign if: the hash differs from the note, an operation does not match the ticket, or you are the person who requested the change.
After the approver says they have signed, go back to your own terminal and confirm the signature, signer, certificate trust, and preview binding:
./scripts/Invoke-ExchangeOnlineChange.ps1 -Stage Validate @changeStop if: the approver is the requester, Validate reports a signature or trust error, the approval expired, or any file changed after signing. Never edit approval JSON by hand.
How approval and signer trust work Approve and validate commandsStep 7 · Apply
Use your approved change window. First rehearse: -WhatIf confirms your session, checks the approval and current state, and lists the operations, but changes nothing and writes no files. Then apply.
./scripts/Deploy-ExchangeOnlineBaseline.ps1 @change -Apply -WhatIf./scripts/Deploy-ExchangeOnlineBaseline.ps1 @change -ApplyAnswer Y at the confirmation prompt only after checking the tenant and change ID it shows. Apply writes prechange, apply, postchange, and rollback files to the artifact folder.
Stop if: the rehearsal fails, the prompt shows the wrong tenant or change, or apply reports drift.
Open Deploy-ExchangeOnlineBaseline.ps1 Apply and WhatIf guidanceStep 8 · Verify and close
Collect evidence with the same inputs. The collector reuses your existing session after it shows the signed-in account and confirms the tenant, so evidence is never read from the wrong tenant. Then build the Markdown report for the ticket:
./scripts/Test-ExchangeOnlineBaseline.ps1 -ParameterPath $change.ParameterPath -ConfigurationPath $change.ConfigurationPath -OutputPath (Join-Path $change.ArtifactRoot 'evidence')
./scripts/New-ExchangeChangeEvidenceReport.ps1 -ArtifactRoot $change.ArtifactRoot -ChangeId $change.ChangeIdThe second command reads every change artifact and the evidence file, then writes evidence-report-<ChangeId>.md into the artifact folder. It does not connect to the tenant. It reports INCOMPLETE if any artifact belongs to a different change or the evidence was collected for another tenant, configuration, or before apply. Expected output:
APPLIED - EVIDENCE COLLECTED
Artifacts present: 6 of 6
Evidence: Pass 41, Manual 3
Report: D:\ExchangeChanges\CHG-1001\evidence-report-CHG-1001.mdDisconnect-ExchangeOnline -Confirm:$false.Rollback restores only the settings this change touched, and only if they have not changed since apply. It works within the 24-hour approval window and cannot undo delivered or processed messages.
& (Join-Path $change.ArtifactRoot "rollback-$($change.ChangeId).ps1") -ApplyStop and escalate if: evidence is missing or stale, a required control fails, or an external owner has not supplied evidence.
Open Test-ExchangeOnlineBaseline.ps1 Evidence and go-live decision guide Recovery and artifact retentionYou have reached the end of the walkthrough. This is not a go-live approval; follow the evidence gate and your organization’s release decision.
Repository tests establish repository behavior; Microsoft documentation establishes product behavior
Invoke-Pester `
.\samples\contoso-exchange-online-managed-service\tests\SecureBaseline.Tests.ps1These tests inspect shipped configuration. They do not certify a live tenant.
Invoke-Pester `
.\samples\contoso-exchange-online-managed-service\tests\unit\MicrositeContent.Tests.ps1The content tests reject legacy scripts, obsolete schemas, detect-only preset claims, and other unsupported concepts.
Live collection must use the same configuration, parameters, entitlement handoff, recipient matrix, manifest, and approval that governed the change. Pass, NotEntitled, ApprovedException, Fail, and Error remain distinct. Externally owned readiness remains unverified until its accountable owner supplies admissible evidence.
No. The supported plan and approved preview describe proposed administrative changes. Standard and Strict presets enforce their documented actions when assigned. Microsoft Defender evaluation is a separate feature and is not configured by this workflow.
No. Virtually all individual preset settings are Microsoft-managed. Manage supported recipient scope and exclusions instead. A custom policy does not override an applicable Strict or Standard preset.
No. Strict is a Microsoft-managed protection profile. AIR and other advanced investigation capabilities are separate Plan 2 features and require applicable tenant and recipient entitlement.
No general cost claim can be made. Required licensing depends on the capability and every recipient who benefits from it. Verify current tenant service plans and recipient assignments; do not infer entitlement from a suite display name.
Submit legitimate messages, URLs, or attachments to Microsoft first. When Microsoft filtering caused the block, the service can create the applicable temporary allow entry. Entity type controls behavior and expiration. Broad or permanent sender allows must not replace authentication fixes, correct scope, or verdict review.
The active configuration prohibits permanent allow entries and requires owner, ticket, timestamps, expiry, and justification for governed entries.
No validated support is claimed. The active administrator journey is Worldwide-only. Sovereign and hybrid environments require a separately reviewed and tested journey.