Setup guide

Required once to POST to /providers/Microsoft.Authorization/elevateAccess, which grants the caller User Access Administrator at the Tenant Root Group so the mg-alz hierarchy can be created at all.

↳ Activate the role through PIM for the shortest possible window, run elevateAccess, assign the durable roles below to the automation principal, then call DELETE on /providers/Microsoft.Authorization/elevateAccess to de-elevate.

Simplest single role that covers creating management groups, policy assignments with managed identities, role assignments, workspaces, Defender pricings and budgets at the mg-alz scope.

↳ Replace with the four narrower roles below — Management Group Contributor, Resource Policy Contributor, User Access Administrator and Security Admin — assigned at mg-alz rather than at the Tenant Root Group.

Creates, renames and reparents mg-alz / mg-alz-platform / mg-alz-lz / mg-alz-corp / mg-alz-sandbox and moves subscriptions between them.

↳ Management Group Reader is enough for the audit-only path where the hierarchy already exists and the skill is only reading compliance state.

Creates the MCSB and tag policy assignments, remediation tasks and time-bounded policy exemptions at management-group scope.

↳ Policy Insights Data Writer (Preview) plus Reader suffices if the skill is only triggering scans and reading compliance rather than assigning policy.

Creates the role assignments that back DeployIfNotExists/Modify managed identities and grants Contributor to the platform Entra group — without it every remediation silently no-ops.

↳ Role Based Access Control Administrator (f58310d9-a9f6-439a-9e8d-f62e7b41a168) grants roleAssignments/write without the broad data-plane reach of User Access Administrator; prefer it and scope it to mg-alz.

Sets Microsoft Defender for Cloud pricing tiers and subplans per subscription and writes the default security contact.

↳ Security Reader is sufficient for 'az security pricing list' and 'az security secure-scores list' during an audit-only run.

Creates law-platform-eastus with retention and daily quota, and switches high-volume tables such as ContainerLogV2 to the Basic plan.

↳ Log Analytics Reader is enough to run the Usage KQL query that sizes ingestion before any change is made.

Creates the subscription-level diagnostic setting that ships Administrative, Security, Policy, ServiceHealth, ResourceHealth and Alert activity logs to the workspace.

↳ Monitoring Reader covers verification-only runs that just confirm the diagnostic setting exists.

Creates the monthly budget with actual and forecasted notification thresholds and the daily amortized cost export.

↳ Cost Management Reader is enough to read existing budgets and exports during an assessment.

Granted to the inherit-costcenter policy assignment's system-assigned managed identity via --role "Tag Contributor" --identity-scope so the Modify effect can actually write the costCenter tag.

↳ This is already the least-privileged role for tag remediation — do not substitute Contributor, which the skill only uses for the broader MCSB initiative.

Backs 'az graph query --management-groups mg-alz' — Azure Resource Graph returns only resources the caller can already read, so a missing Reader assignment shows up as an empty result set rather than an error.

↳ Assign at mg-alz so it inherits to every child subscription instead of assigning per subscription.

The OAuth2 scope the service principal token is issued for; every az and Terraform call in this skill targets the Azure Resource Manager audience. No Microsoft Graph scope is required because the skill passes raw object IDs instead of resolving principals by name.

Cause: The service principal has roles on subscriptions but nothing at the Tenant Root Group, so it can list its own subscriptions yet cannot create the mg-alz hierarchy.

Fix: Have a Global Administrator run the elevateAccess POST, then assign Owner (or Management Group Contributor) to the principal at /providers/Microsoft.Management/managementGroups/$TENANT_ID and wait a few minutes for propagation.

Cause: The Secret ID column was copied from Certificates & secrets instead of the Value column, or the secret expired.

Fix: Create a new client secret and copy the Value immediately; it is only displayed once. Re-export AZURE_CLIENT_SECRET and ARM_CLIENT_SECRET.

Cause: Resource provider registration was skipped for that subscription, so policy-state and remediation calls are rejected even though RBAC is correct.

Fix: Run 'az provider register -n Microsoft.PolicyInsights' (and the same for Microsoft.Security, Microsoft.OperationalInsights, Microsoft.CostManagement) on every subscription in scope and wait for registrationState to reach Registered.

Cause: Entra replication lag — the role assignment for a policy assignment's freshly created system-assigned managed identity is attempted before the service principal has propagated across the directory.

Fix: Retry the role assignment after 30-60 seconds. In Terraform this shows up on first apply of azurerm_role_assignment.mcsb_msi; re-running apply resolves it, or add a short time_sleep between the policy assignment and the role assignment.

Cause: A DeployIfNotExists or Modify assignment's --identity-scope points at a scope the caller cannot itself grant roles over, or the subscription was moved between management groups mid-operation.

Fix: Set --identity-scope to the same management group the assignment targets, ensure the caller holds User Access Administrator or Role Based Access Control Administrator at that exact scope, and re-check RBAC after any subscription move.

Cause: 'az role assignment create --assignee <upn-or-name>' forces a Microsoft Graph lookup, which a bare ARM service principal cannot perform without a directory read permission.

Fix: Use --assignee-object-id "$GRP_PLATFORM_OID" --assignee-principal-type Group as the skill does, which bypasses Graph entirely. Only grant Directory.Read.All / User.Read.All if name-based lookup is genuinely required.

Cause: A deny-effect assignment created earlier in the run — typically allowed locations e56962a6-4747-49cd-b67b-bf8b01975c4c or a require-tag policy — now blocks the workspace, storage account or remediation deployment the skill itself is creating.

Fix: This is why the skill ships deny-capable assignments with --enforcement-mode DoNotEnforce first. Either flip the assignment back to DoNotEnforce, add the deploying region/tag to the parameters, or file a time-bounded 'az policy exemption create'.

Cause: A CannotDelete or ReadOnly management lock inherited from the subscription or management group blocks the workspace, diagnostic setting or deployment-stack write.

Fix: Azure portal > the scope > Settings > Locks > delete or temporarily downgrade the lock (requires Microsoft.Authorization/locks/delete), apply, then restore it.

Cause: The 'az security contact' argument surface changed between CLI versions, exactly as the skill warns in Procedure step 4.

Fix: Run 'az security contact create --help' against the installed CLI version and use the argument names it reports, or pin the CLI version used in CI.

Cause: The budget timePeriod.startDate or the Terraform time_period start_date is not the first of a month, or the hard-coded 2026-08-01 date has since elapsed.

Fix: Set startDate to the first day of the current or a future month in UTC (for example 2026-08-01T00:00:00Z) and re-run the PUT on Microsoft.Consumption/budgets.