Entra evidence and troubleshooting

Find and preserve the reports

After logging initializes, the toolkit attempts to save HTML and JSON evidence even when sign-in, deployment, or health evaluation fails. The final output prints the full path of each successfully written report and a copyable command to open the HTML manually. It never launches a browser automatically.

With the default configuration, run this from Products\Entra:

Invoke-Item -LiteralPath '.\Reports\entra-run-report.html'
$report = Get-Content -LiteralPath '.\Reports\entra-run-log.json' -Raw |
    ConvertFrom-Json
$report.moduleSummary | Format-Table module, result, entryCount

The private configuration’s Report section can change these paths. A write warning means that file was not confirmed saved; an older file can still exist at the same location. Check the run ID and timestamps, not just file presence. Preserve reports before retrying because filenames are reused.

entra-breakglass.json is diagnostic evidence containing resolved emergency-access IDs plus a runId and Boolean verified marker. It is invalidated before directory verification, but it is never read to authorize exclusions. The orchestrator accepts exactly one structured in-memory result from the emergency-access module, validates its current run ID, Boolean verification state and typed principal arrays, and copies those arrays into the CA context. Editing, replacing or replaying the JSON cannot change those exclusions, even when its markers look valid. Missing, malformed or inconsistent module results stop deployment. This protects the file boundary, not a compromised PowerShell process. Account creation leaves verified=false and empty IDs, records CreateBreakGlass followed by a failed/blocked BreakGlassHandoff, and stops before Conditional Access writes. Complete manual setup, configure the existing account’s object ID, and rerun; do not repeatedly create accounts. Empty lists mean no principals were verified for that run, not that no emergency accounts exist anywhere in the tenant. Never treat this file as credential storage or as proof of successful recovery.

VerifyWriteBoundary with Failed/Blocked means the public CA module rejected the actual session/tenant or could not reverify the supplied emergency IDs before a POST/PATCH. Check the intended Context.TenantId GUID, operator UPN, current Graph sign-in and directory/role read permissions. Confirm enabled accounts/group membership and permanent tenant-wide Global Administrator recovery, then rerun under approval. Fabricating a run ID or verified=true does not authorize standalone writes. A later-policy failure does not roll back earlier writes: review each applied policy and its readback. Checks are repeated per write but are not atomic against concurrent directory changes.

Reports are private tenant evidence. Redaction is pattern-based, not a guarantee that every service-authored error is safe to share. Review excerpts, and never commit reports, private configuration, tokens, or credentials.

Interpret results without confusing execution and protection

Result or field	Meaning
`OK`	Recorded module work completed without a recorded failure or block. It does not prove the baseline was applied or the tenant is secure.
`FAILED`	An operation failed or a safety/health assessment returned a failure. Read its action and detail; this does not always mean the script crashed.
`BLOCKED`	A prerequisite, safety gate, or assessment finding prevents proceeding. Resolve it under change control.
`SKIPPED`	Work was not executed or remained assessment/guidance-only. It is not proof that configuration is complete.
`GuidedOnly`	Human work or review remains. It is not verified compliance.
`VALIDATED` / `Readback=Verified`	The stated readback check passed, not an end-to-end sign-in or security test.
`TenantWritesAllowed=True`	The Security Defaults gate passed. Approval, scope, emergency access, permissions, and other gates still apply.
`ExclusionsEvaluated=False`	Exclusion checks were not completed. Zero gap counters do not mean no gaps exist.

Review actual writes separately:

$report.entries |
    Where-Object status -in @('Created', 'Updated', 'Adopted') |
    Select-Object module, action, status, readback, detail

A -WhatIf preview must have no applied tenant actions in that result. For an apply, compare each entry with the approved change and confirm its readback. Started or Module process completed alone is not deployment evidence. Intentionally skipped modules reduce the assessment’s coverage.

Selected modules that never start after an earlier failure are recorded as Skipped with a Blocked disposition and an explicit reason. Console, HTML, and JSON use the same module verdicts. Summaries of a failed child do not change the orchestrator’s own verdict, but genuine orchestrator failures and readiness blocks remain visible. The child failure still requires action.

Report-write warnings remain nonterminating even with -WarningAction Stop, so they cannot hide the original error or prevent the other report attempt.

A first run is blocked and health is indeterminate

A first run can connect successfully, find no configured emergency-access principals, report missing toolkit policies, and stop Conditional Access deployment. If enforcing customer policies already exist, the health check cannot verify their emergency exclusions without those principals and can return Indeterminate with a failed module result.

This does not prove the tenant lacks emergency accounts or is currently locked out. It means the tool lacks enough verified configuration to assess recovery. Confirm the existing emergency accounts with the identity owner, test them independently, and configure their object IDs in a complete private config. Then rerun the preview. Do not create duplicate emergency accounts or disable existing policies just to clear the report.

Missing managed policies are expected before the baseline is deployed. The separate EnforcingPoliciesInTenant count includes existing policies, so a missing toolkit baseline does not mean the tenant has no access controls.

For LockoutRisk, stop rollout and use the approved access incident/recovery process immediately. For DriftDetected, reconcile the specific changes before expansion. Healthy covers only the implemented readiness and emergency-access checks, not full policy coverage or a sign-in guarantee.

Common failures

Symptom	What to do
Wrong tenant or verified-domain mismatch	Stop. Check the administrator UPN and, for GDAP, the customer domain. Do not bypass identity verification.
Missing or different operator after sign-in	Select the exact `TenantAdminUpn` account on rerun. The invalid context is disconnected where possible. If disconnect also fails, close PowerShell and start a fresh session; the original identity error remains authoritative. No broader scope is needed.
`401` / `403` or a failed read	Check the exact Graph operation, configured scopes, effective roles, GDAP access, and session. Do not add broad permissions speculatively.
Security Defaults enabled or unknown	Keep active protection. Use the approved transition guide; the toolkit never disables it.
Missing apply parameters or pilot group	Complete the operator checklist. Removing `-WhatIf` alone does not authorize writes.
No configured break-glass principal	Verify existing accounts/groups, populate the private configuration, and rerun. An ID is not a successful recovery test.
Existing or duplicate policy names	Review the exact objects and aliases. Do not use adoption or naming changes to bypass collisions or migration review.
Readback mismatch or unavailable readback	Treat the operation as failed or blocked. Inspect the tenant before retrying because the service might have accepted the preceding write.
Report-write warning	Keep the console output, verify the destination and permissions, and preserve any surviving report. Do not use stale files as current evidence.

WAM broker available describes Windows capability, not a guarantee that the current host can display the sign-in window. If Graph reports A window handle must be configured, open Windows Terminal with PowerShell 7 yourself, change to the same product folder, and rerun the same -WhatIf command. Complete sign-in in the Microsoft window and verify tenant identity.

Do not disable MFA, add permissions, or switch to app-only authentication to work around the host. -NonInteractive suppresses toolkit prompts but cannot create a desktop sign-in window. See the Microsoft WAM parent-window guidance.

Recover from a partial deployment

Existing guest MFA policy reports a scope mismatch

The current guest template uses includeUsers = ["GuestsOrExternalUsers"] without a group include. An older policy targeting the pilot group is not equivalent, even if its name says “guest access”. The toolkit reports GuidedOnly and Readback=Mismatch, without changing or duplicating it. -AdoptExisting does not bypass this review boundary. A matching corrected policy also remains review-only, not an automatic enforcement approval.

Inspect the existing policy by ID with the identity owner, record its state, scope and emergency exclusions, and plan an approved migration. Guest-wide scope can include external users outside the pilot group. Keep existing protection until replacement coverage and recovery are verified.

Recovery procedure

There is no automatic rollback. Before apply, privately record the exact policy IDs, states, targeting, emergency exclusions, ownership, and any tenant-setting values that may change. Reports are redacted evidence, not a complete backup.

After a failure, stop expansion and preserve that run’s reports. With the identity owner, inspect the precise object and whether the service accepted the write. Restore approved before-state or withdraw only the newly created pilot object when safe. Do not delete by display name, remove broad sets of policies, or disable existing protection. Emergency-account removal requires verified replacement access and review of every dependent policy.

If an existing policy requires manual migration, follow the migration procedure. After recovery, rerun -WhatIf, reconcile its findings, and obtain approval before another apply or enforcement change.

Escalation

Provide the product version, run time, module/action, sanitized error, selected scope, and reviewed report excerpt. Record whether the issue is sign-in, permission, configuration, readback, or incomplete health evidence. Never include secrets, raw exports, unreviewed tenant reports, or private IDs in a public issue. Live sign-in, role, policy impact, and recovery validation remain the deployment and identity owners’ responsibility.